# Assistants Overview

Assistants are AI-powered agents in Freddy that can be configured with specific behaviors, knowledge, and tools to help users accomplish tasks. Each assistant is highly customizable and can be tailored to specific use cases within your organization.

## What is an Assistant?

An assistant is a configured AI agent that combines:

- **Base Model**: The underlying AI model (e.g., GPT-4, Claude)
- **Instructions**: System prompts that define behavior and personality
- **Knowledge**: Rules, documents, and context that inform responses
- **Tools**: Built-in system tools, MCP integrations, and Streamline automations
- **Configuration**: Settings for reasoning, response format, and context handling


## Key Features

### 🎯 Purpose-Built Agents

Create specialized assistants for different tasks:

- Customer support agents
- Code review assistants
- Data analysis experts
- Content creation helpers
- Research assistants


### 🧠 Intelligent Reasoning

Configure how assistants think and respond:

- Chain-of-thought reasoning
- Step-by-step problem solving
- Multi-step planning
- Reflection and self-correction


### 🔧 Tool Integration

Equip assistants with powerful capabilities:

- **System Tools**: File search, web search, code execution
- **MCP Tools**: Custom integrations via Model Context Protocol
- **Streamline Automations**: Workflow automation tools
- **Personal Connectors**: OAuth-based third-party integrations


### 📚 Knowledge Management

Give assistants access to organizational knowledge:

- Attach rules and guidelines
- Connect vector stores for semantic search
- Use preset prompts for common tasks
- Maintain conversation history


### 🔒 Access Control

Control who can use which assistants:

- Organization-level assistants
- Department-specific assistants
- User-level permissions
- Role-based access


## Assistant Architecture

Assistants in Freddy use a normalized database structure for flexibility and scalability:


```
assistants (main table)
├── assistant_rules (knowledge & guidelines)
├── assistant_reasoning (thinking configuration)
├── assistant_json_schemas (structured output)
├── assistant_vector_stores (semantic search)
├── assistant_rule_attachments (file attachments)
└── assistant_tool_configurations (tools & integrations)
    ├── system_tools (built-in capabilities)
    ├── mcp_tools (MCP integrations)
    └── streamline_tools (automations)
```

## Common Use Cases

### Customer Support Assistant


```json
{
  "name": "Support Agent",
  "instructions": "You are a helpful customer support agent...",
  "tools": {
    "system_tools": ["file_search", "web_search"],
    "mcp_tools": ["zendesk_integration"]
  },
  "rules": ["support_guidelines", "escalation_policy"]
}
```

### Code Review Assistant


```json
{
  "name": "Code Reviewer",
  "instructions": "You are an expert code reviewer...",
  "tools": {
    "system_tools": ["code_interpreter"],
    "mcp_tools": ["github_integration"]
  },
  "reasoning": {
    "enabled": true,
    "type": "chain_of_thought"
  }
}
```

### Data Analysis Assistant


```json
{
  "name": "Data Analyst",
  "instructions": "You are a data analysis expert...",
  "tools": {
    "system_tools": ["code_interpreter"],
    "mcp_tools": ["database_connector", "visualization_tool"]
  },
  "vector_stores": ["company_data_warehouse"]
}
```

## Quick Start

### 1. Create an Assistant


```bash
curl https://api.aitronos.com/v1/assistants \
  -H "X-API-Key: $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My First Assistant",
    "instructions": "You are a helpful assistant.",
    "model": "gpt-4"
  }'
```

### 2. Configure Tools


```bash
curl https://api.aitronos.com/v1/assistants/{assistant_id}/tools \
  -H "X-API-Key: $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "system_tools": {
      "file_search": {"enabled": true},
      "web_search": {"enabled": true}
    }
  }'
```

### 3. Attach Knowledge


```bash
curl https://api.aitronos.com/v1/assistants/{assistant_id}/rules \
  -H "X-API-Key: $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rule_id": "rule_abc123"
  }'
```

### 4. Use the Assistant


```bash
curl https://api.aitronos.com/v1/responses \
  -H "X-API-Key: $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": "asst_abc123",
    "thread_id": "thread_xyz789",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'
```

## Next Steps

- [Tool Integration](/docs/documentation/assistants/tools) - Working with tools and integrations


## Learn More

- [API Reference: Assistants](/docs/api-reference/assistants/create)
- [Core Concepts: Rules](/docs/documentation/core-concepts/rules)
- [Core Concepts: MCP Tools](/docs/documentation/core-concepts/mcp-tools)