---
title: Creating Agents
description: AI assistants that understand context, call tools, and help users accomplish tasks
icon: Bot
---

import Callout from "../../../../components/ui/Callout.astro";

## Understanding Agents

Each agent:
- **Understands natural language** - Users can talk to them conversationally
- **Calls tools autonomously** - Decides which tools to use based on the situation
- **Follows instructions** - Behaves according to your system prompt
- **Maintains context** - Remembers conversation history 
- **Has access to resources** - Users can `@mention` any resource (tools, documents, workflows, views) to give the agent access 

**Common use cases:**
- Customer support automation
- Internal productivity assistants
- Data analysis helpers
- Content creation
- Process automation

## Creating Agents with Deco Chat

The easiest way to create an agent is by describing what you need:

**Example prompts:**
```
I need a customer support agent that can look up orders and process refunds under $100

Create an agent that helps my team analyze sales data and generate reports

Build a content writer agent that follows our brand guidelines and can publish to our CMS

I want an agent that triages customer inquiries and routes them to the right specialist
```

**What happens next:**
1. Deco chat asks clarifying questions (What tools? What personality? What boundaries?)
2. Suggests a system prompt based on your needs
3. Recommends which tools to give it
4. Creates the agent using `@AGENTS_CREATE`
5. You test and iterate together

**Refine as you go:**
```
Make it more formal in tone
Add the ability to create support tickets
Don't let it process refunds over $50 without approval
Include our product FAQ as context
```

Start with a rough idea and iterate toward exactly what you need.


<Callout type="info">
  The sections below explain the mechanics if you want to understand how agents work.
</Callout>

---

## What Goes on Under the Hood?

When you create an agent (whether via deco chat or by clicking through the UI), these are the key components being configured:

### 1. System Prompt (Most Important)

The system prompt defines your agent's:
- **Behavior** - How it acts and responds
- **Personality** - Tone and style
- **Boundaries** - What it should/shouldn't do
- **Domain knowledge** - Areas of expertise

Think of the system prompt as persistent context that's included with every user message. You can reference any resource in system prompts using `@` mentions (tools, documents, workflows, views).

**Example system prompt:**

```
You are a customer support agent for Acme SaaS, a project management platform.

You help customers with:
- Billing and subscription questions
- Account access and login issues  
- Product feature explanations and how-tos
- Bug reports and technical troubleshooting

You are friendly, patient, and solution-oriented. 
You use clear language and avoid jargon.

You can:
- Process refunds under $100 using @PROCESS_REFUND
- Reset passwords using @RESET_PASSWORD
- Look up account status using @GET_ACCOUNT_STATUS
- Create support tickets using @CREATE_TICKET for complex issues
- Schedule calls with specialists using @SCHEDULE_CALL

You cannot:
- Make promises about future features or roadmap
- Modify custom pricing or enterprise contracts
- Share data about other customers
- Override security policies

When handling refunds:
- For amounts under $100, use @PROCESS_REFUND immediately
- For amounts over $100, use @CREATE_TICKET and tell the customer 
  a manager will review within 24 hours

When users can't log in:
- First use @GET_ACCOUNT_STATUS to check account status
- If suspended, explain why and what they need to do
- If active, use @RESET_PASSWORD and guide them through the process

For technical bugs:
- Always use @CREATE_TICKET to ensure engineering team sees it
- Get reproduction steps before creating the ticket
- Set priority based on impact (blocks work = high, cosmetic = low)

Example interaction:

User: "I can't log in and I have a demo in 30 minutes!"

You: "I understand the urgency, let me help you right away. I'm checking 
      your account status now using our system. 

      [calls @GET_ACCOUNT_STATUS]
      
      Your account is active. Let me send you a password reset link to 
      get you back in quickly.
      
      [calls @RESET_PASSWORD]
      
      Done! Check your email for the reset link. It's valid for 1 hour. 
      If you don't see it in 2 minutes, check your spam folder.
      
      Is there anything else you need before your demo?"

When you don't know something, say so clearly and offer to connect them 
with a specialist. Never guess or make up information.
```

<Callout type="success">
  The system prompt is where most agent tuning happens. Notice how we **show** the agent how to behave through examples and **specify** exactly when to use each tool.
</Callout>

### 2. Model Selection

Choose the AI model that powers your agent. We currently offer the models shown below, and are always adding more:

- Claude Sonnet 4.5
- Claude Haiku 4.5
- OpenAI GPT-4.1 mini
- OpenAI GPT OSS 120B
- OpenAI GPT OSS 20B
- Google Gemini Pro 2.5
- Claude Sonnet 4
- Claude Sonnet 3.7

**Practical guidance:**
- **Customer support** - Claude Haiku or Sonnet (good understanding, fast)
- **Data analysis** - Claude Sonnet or GPT-4.1 (better reasoning)
- **Simple automation** - GPT-4.1 mini (fast and cost-effective)
- **Content writing** - Claude Sonnet (creative and nuanced)

You can change models anytime.

**For detailed model specifications**, see:
- [OpenRouter Models](https://openrouter.ai/models) - Comprehensive model comparison
- [Models.dev](https://models.dev/) - Open-source database of AI models with pricing and features

**Bring Your Own Model (BYOM) / Bring Your Own Tokens (BYOT):**
If you want to use your own API keys or custom models, go to **Organization** → **Models** to manage these settings. 

### 3. Tool Assignment

Give your agent access to specific tools, but start minimal. 
```
❌ Give access to all 50 workspace tools
✅ Start with 3-5 essential tools, add as needed
```

Too many tools confuse the agent and make the context window too large, leading to slower responses and higher costs.

**Example toolset for customer support:**
```
Customer Information:
├─ CUSTOMER_FETCH
└─ CUSTOMER_UPDATE

Billing:
├─ INVOICE_FETCH
├─ REFUND_PROCESS
└─ SUBSCRIPTION_UPDATE

Communication:
├─ EMAIL_SEND
└─ TICKET_CREATE
```

**In your system prompt, explain how and when to use each tool:**
```
To look up a customer's order history, use @ORDERS_FETCH with their email.
To process a refund under $100, use @REFUND_PROCESS with the order ID.
For refunds over $100, use @TICKET_CREATE to escalate to a manager.
```

**Assigning tools from integrations:**

In the Agents tab, click **Tools** → **Add Integration** to give your agent access to tools that come with pre-built integrations (apps). Here, add new integrations or select from installed ones.

<Callout type="warning">
  Be careful giving agents tools that delete data, charge money, or call expensive APIs. Consider adding approval workflows for sensitive operations.
</Callout>

### 4. Additional Context

Beyond the system prompt, you can give agents access to additional context through multiple sources:

#### Documents

Attach documents that the agent can search and reference using `@` mentions in threads and system prompts (e.g., `@product-guide`, `@support-faq`).

**What to attach:**
- Product documentation (feature guides, FAQs)
- Process documentation (SOPs, escalation guidelines)  
- Company information (policies, pricing, terms)

**Example:**
```
Customer Support Agent Documents:
├─ Product Features Guide.md
├─ Billing FAQ.md
├─ Troubleshooting Guide.md
└─ When to Escalate.md
```

The agent automatically searches these when relevant. You don't need to tell it to, it figures out when it needs more information.

#### Database Context

Give agents access to your database for real-time data retrieval:

**Current approach:**
Use `@DATABASES_RUN_SQL` to query your database directly. Reference this tool in your system prompt with examples:

```
To check a customer's subscription status, use @DATABASES_RUN_SQL:
SELECT status, plan, expiry_date FROM subscriptions WHERE user_id = ?
```

**Coming soon:** Direct table and field references without writing SQL.

#### RAG and Knowledge Bases

**Coming soon:** Native first-class RAG and knowledge base support.

**For now, use:**
- **Documents** (as shown above) for simple Q&A and reference material
- **Pinecone integration** from the deco store for production-grade vector search and semantic retrieval

Install Pinecone from **Integrations** → **Browse Store** → **Pinecone**, then give your agent access to Pinecone tools for semantic search over large knowledge bases.

### 5. Advanced Settings

Fine-tune behavior (most agents work well with defaults):

**Max Steps** (default: 15)
- How many tool invocations the agent can make per response
- Higher = can complete more complex tasks
- Lower = faster, simpler responses

**Max Tokens** (default: 4096-64000 depending on model)
- Maximum response length
- Adjust based on your use case (short replies vs. long-form content)

**Temperature** (0.0 - 1.0, default: varies by model)
- Lower (0.2) = Consistent, deterministic (support agents)
- Higher (0.8) = Creative, varied (content agents)

**Context Window**
- The number of recent messages to keep in memory
- Larger window = better context but higher cost

**Access Control**
- Control who can interact and edit this agent 

## Common Agent Patterns

### Customer Support Agent
```
Model: Claude Sonnet (fast, good at conversation)
Tools: CUSTOMER_FETCH, ORDER_LOOKUP, REFUND_PROCESS, TICKET_CREATE
Documents: FAQ, troubleshooting guide, return policy
Tone: Friendly, patient, solution-oriented
Visibility: Public
```

### Internal Data Analyst
```
Model: GPT-4 (better at complex queries)
Tools: DATABASE_QUERY, CHART_GENERATE, REPORT_CREATE
Documents: Database schema, KPI definitions
Tone: Technical, precise
Visibility: Workspace
```

### Content Writer
```
Model: GPT-4 (more creative)
Tools: CONTENT_GENERATE, SEO_ANALYZE, CMS_PUBLISH
Documents: Brand guidelines, style guide
Tone: Creative, engaging, on-brand
Visibility: Workspace
```

## Testing Your Agent

1. **Happy path** - Everything works as expected
2. **Missing info** - Agent asks follow-up questions
3. **Errors** - Tools fail, agent handles gracefully
4. **Edge cases** - Unusual or unexpected requests
5. **Multi-step** - Complex tasks requiring multiple tools
6. **Boundaries** - User asks agent to do something it shouldn't

Open the agent in a thread and try real conversations. Watch which tools it calls and how it responds. Refine the system prompt based on what you see, this is an iterative process.

<Callout type="tip">
  **Two ways to configure agents:** You can make changes manually (test and then edit system prompt, assign tools, adjust settings) or ask deco chat to test and adjust for you.
</Callout>

## Monitoring Agent Usage

Track agent performance and usage:

- Go to **Usage** in your org
- See conversations, messages, tool invocations, costs per agent
- Filter threads by agent to see all conversations

Use these insights to:
- Learn how others use the agent
- Identify common issues or confusion
- Discover unexpected use cases
- Improve system prompts based on real patterns

**Remember:** The best agents have clear, specific system prompts and carefully curated toolsets. Start simple and evolve based on real usage.