# Agents

**Agents** are configured AI assistants with specific instructions, behavior patterns, and default context. They act as a reusable interface layer between users and content, encoding domain expertise into queryable entities that provide consistent, high-quality responses across your organization.

## What is an Agent?

An agent consists of:

- **Instructions**: System prompt defining behavior, tone, domain expertise, and guidelines
- **Default Context**: Pre-configured libraries and search settings
- **Default Model**: The underlying AI model the agent uses (e.g., GPT-4, Claude, etc.)
- **Model Switching Policy**: Whether end users can override the default model
- **Implicit Permissions**: Agents inherit permissions from the user querying them


Key characteristics:

- Reusable across queries and users
- Encapsulate domain expertise (legal, medical, financial, technical)
- Provide consistent behavior and output quality
- Act as a governance/access control layer


## Agent Components

### Instructions Field

Acts as the system prompt for the AI, defining expertise, tone, behavior, and guidelines. These can include:

- Role definition and domain expertise
- Output formatting rules
- Citation and source attribution requirements
- Domain-specific guidelines
- Limitations and disclaimers (e.g., "not legal advice")


### Default Context

- `libraries`: Array of library IDs to include by default
- `contentFilters`: Filters of content the agent will have access to
- `includeWebSearchResults`: Boolean for web search augmentation
- Can be overridden per-query for flexibility


### Model Configuration

- `defaultModel`: Specifies which AI model the agent uses (e.g., "gpt-4", "claude-3-opus", "gpt-4-turbo")
- `canSwitchModel`: Boolean flag (default: `true`) controlling whether users can override the model at query time
  - `true`: Users can specify a different model when querying (flexibility, experimentation)
  - `false`: Agent always uses the default model (consistency, cost control, compliance)


### Metadata (read-only)

- `agentId`, `accountId`, `createdBy`, `createdAt`, `lastUpdatedAt`
- Used for audit trails and usage tracking


## Creating an Agent


```bash
POST https://cloud.syncdocs.ai/api/accounts/scd-k2j8n4m1/agents
Authorization: Bearer <your-token>
Content-Type: application/json

{
  "name": "SF Legal Research Assistant",
  "description": "AI assistant specializing in California and San Francisco law",
  "instructions": "You are an expert legal research assistant specializing in California state law and San Francisco municipal law. Always cite specific statutes, distinguish between client files vs. legal references, and provide practical guidance relevant to San Francisco jurisdiction. Use formal, professional language suitable for legal documentation.",
  "defaultModel": "gpt-4-turbo",
  "canSwitchModel": false,
  "defaultContext": {
    "libraries": [
      "c7f85f64-9821-4a62-b8fc-1c963f66afa6",
      "d8a96g75-1932-5b73-c9gd-2d074g77bgb7"
    ],
    "includeWebSearchResults": false
  }
}
```

**When to lock model switching (`canSwitchModel: false`):**

- Ensure consistent quality/format across all users
- Control costs by preventing expensive model selection
- Meet compliance requirements for specific model usage
- Agent instructions are optimized for a specific model


## Using Agents in Queries

### Basic Query


```bash
POST https://sws-x9p3q7r5.syncdocs.ai/api/content/sds-a1b2c3d4/query
{
  "query": "What are the tenant notification requirements for eviction in San Francisco?",
  "agentId": "550e8400-e29b-41d4-a716-446655440000"
}
```

The agent's instructions become the system prompt, default model is used, and default libraries are included.

### Agent + Metadata Filters


```bash
POST https://sws-x9p3q7r5.syncdocs.ai/api/content/sds-a1b2c3d4/query
{
  "query": "Based on our case files, what is our strongest defense strategy?",
  "agentId": "550e8400-e29b-41d4-a716-446655440000",
  "context": {
    "contentFilters": {
      "clientId": "CLIENT-2024-789",
      "caseType": "Eviction Defense"
    }
  }
}
```

Demonstrates privacy/governance with client-specific scoping.

### Overriding Model or Libraries


```bash
POST https://sws-x9p3q7r5.syncdocs.ai/api/content/sds-a1b2c3d4/query
{
  "query": "Quick check: is this document a contract?",
  "agentId": "550e8400-e29b-41d4-a716-446655440000",
  "model": "gpt-3.5-turbo",  // Only works if canSwitchModel: true
  "context": {
    "libraries": ["c7f85f64-9821-4a62-b8fc-1c963f66afa6"]  // Override default libraries
  }
}
```

### Conversation History


```bash
POST https://sws-x9p3q7r5.syncdocs.ai/api/content/sds-a1b2c3d4/query
{
  "query": "What evidence supports the secondary defense?",
  "agentId": "550e8400-e29b-41d4-a716-446655440000",
  "conversationId": "conv-a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```

Sync automatically maintains conversation context—no need to pass previous messages.

## Agent Permissions Model

**Agents don't have permissions themselves**—they inherit from the user making the query.

**Example Scenario:**

- Two users query the same agent
- User A has access to Client X files → agent can access Client X
- User B has access to Client Y files → agent can access Client Y
- Same agent, different effective permissions based on user


**Governance Benefits:**

- Agents never bypass security controls
- Audit logs show which agent was used
- Metadata filters provide additional scoping (privacy by design)
- Model locking ensures compliance requirements


## Agent Design Patterns

### Single-Purpose Agents

- One agent per specific task type
- Clear, focused instructions
- Often lock model for consistency (`canSwitchModel: false`)
- Example: "Invoice Data Extractor", "Document Classifier"


### General-Purpose Research Agents

- Broad expertise across document types
- Flexible, adaptable behavior
- Usually allow model switching (`canSwitchModel: true`)
- Example: "Enterprise Knowledge Assistant"


### Domain-Specific Agents

- Deep expertise in one domain
- Custom libraries for that domain
- May lock model to ensure quality
- Example: "SF Legal Research Assistant", "Medical Records Analyzer"


### Multi-Stage Agent Workflows

- Chain multiple agents together
- Each agent performs one step in a pipeline
- Mix of locked/flexible models based on requirements
- Example: Classification → Extraction → Validation → Routing


## Agents vs. Direct Queries

| Aspect | With Agent | Without Agent |
|  --- | --- | --- |
| **Instructions** | Defined once, reused | Must specify per query |
| **Model Selection** | Configured default with optional override | Must specify each time |
| **Consistency** | Same behavior across users | Varies per query |
| **Audit Trail** | Tagged with agent ID | Only user + query |
| **Library Context** | Pre-configured defaults | Must specify each time |
| **Maintenance** | Update agent once | Update all queries |
| **Use Case** | Production applications | Ad-hoc exploration |


## Query Logging & Analytics

Every query logs:

- Agent ID and model used (default or overridden)
- Full request/response
- Documents accessed, libraries searched
- Conversation threads


**Analytics Use Cases:**

- Track which agents are most used
- Monitor model usage and costs per agent
- Identify poorly performing agents for instruction refinement
- Measure response quality by agent type
- Allocate costs per agent/department
- Track model override patterns for cost optimization


## Next Steps

- **[Build a Research Agent](/guides/build-research-agent)** - Step-by-step tutorial creating a legal research agent
- **[Understand Queries](/concepts/queries)** - How queries work with agents
- **[Explore Libraries](/concepts/libraries)** - Add external knowledge to agents
- **[API Reference](/api)** - Complete agent API documentation