---
title: Criando Agents
description: Assistentes de IA que entendem contexto, chamam tools e ajudam usuários a realizar tarefas
icon: Bot
---

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

## Entendendo Agents

Cada agent:
- **Entende linguagem natural** - Usuários podem conversar com eles naturalmente
- **Chama tools autonomamente** - Decide quais tools usar baseado na situação
- **Segue instruções** - Se comporta de acordo com seu system prompt
- **Mantém contexto** - Lembra do histórico de conversa
- **Tem acesso a resources** - Usuários podem usar `@menção` em qualquer resource (tools, documents, workflows, views) para dar acesso ao agent

**Casos de uso comuns:**
- Automação de suporte ao cliente
- Assistentes de produtividade interna
- Auxiliares de análise de dados
- Criação de conteúdo
- Automação de processos

## Criando Agents com Deco Chat

A maneira mais fácil de criar um agent é descrevendo o que você precisa:

**Exemplos de prompts:**
```
Preciso de um agent de suporte ao cliente que possa consultar pedidos e processar reembolsos abaixo de R$500

Crie um agent que ajude minha equipe a analisar dados de vendas e gerar relatórios

Construa um agent escritor de conteúdo que siga nossas diretrizes de marca e possa publicar em nosso CMS

Quero um agent que faça triagem de consultas de clientes e as encaminhe para o especialista certo
```

**O que acontece em seguida:**
1. Deco chat faz perguntas esclarecedoras (Quais tools? Qual personalidade? Quais limites?)
2. Sugere um system prompt baseado nas suas necessidades
3. Recomenda quais tools dar a ele
4. Cria o agent usando `@AGENTS_CREATE`
5. Você testa e itera juntos

**Refine conforme avança:**
```
Deixe o tom mais formal
Adicione a capacidade de criar tickets de suporte
Não deixe processar reembolsos acima de R$250 sem aprovação
Inclua nosso FAQ de produto como contexto
```

Comece com uma ideia vaga e itere em direção a exatamente o que você precisa.


<Callout type="info">
  As seções abaixo explicam a mecânica se você quiser entender como agents funcionam.
</Callout>

---

## O Que Acontece Por Baixo dos Panos?

Quando você cria um agent (seja via deco chat ou pela UI), estes são os componentes principais sendo configurados:

### 1. System Prompt (Mais Importante)

O system prompt define as características do seu agent:
- **Comportamento** - Como ele age e responde
- **Personalidade** - Tom e estilo
- **Limites** - O que ele deve/não deve fazer
- **Conhecimento de domínio** - Áreas de expertise

Pense no system prompt como contexto persistente que é incluído com cada mensagem do usuário. Você pode referenciar qualquer resource em system prompts usando menções `@` (tools, documents, workflows, views).

**Exemplo de system prompt:**

```
Você é um agent de suporte ao cliente para Acme SaaS, uma plataforma de gerenciamento de projetos.

Você ajuda clientes com:
- Perguntas sobre cobrança e assinatura
- Problemas de acesso à conta e login
- Explicações e tutoriais de recursos do produto
- Relatórios de bugs e solução de problemas técnicos

Você é amigável, paciente e orientado a soluções.
Você usa linguagem clara e evita jargões.

Você pode:
- Processar reembolsos abaixo de R$500 usando @PROCESS_REFUND
- Redefinir senhas usando @RESET_PASSWORD
- Consultar status da conta usando @GET_ACCOUNT_STATUS
- Criar tickets de suporte usando @CREATE_TICKET para problemas complexos
- Agendar chamadas com especialistas usando @SCHEDULE_CALL

Você não pode:
- Fazer promessas sobre recursos futuros ou roadmap
- Modificar preços customizados ou contratos enterprise
- Compartilhar dados sobre outros clientes
- Burlar políticas de segurança

Ao lidar com reembolsos:
- Para valores abaixo de R$500, use @PROCESS_REFUND imediatamente
- Para valores acima de R$500, use @CREATE_TICKET e informe ao cliente
  que um gerente fará a revisão em até 24 horas

Quando usuários não conseguem fazer login:
- Primeiro use @GET_ACCOUNT_STATUS para verificar o status da conta
- Se suspensa, explique o motivo e o que precisam fazer
- Se ativa, use @RESET_PASSWORD e guie-os pelo processo

Para bugs técnicos:
- Sempre use @CREATE_TICKET para garantir que a equipe de engenharia veja
- Obtenha passos de reprodução antes de criar o ticket
- Defina prioridade baseada no impacto (bloqueia trabalho = alta, cosmético = baixa)

Exemplo de interação:

Usuário: "Não consigo fazer login e tenho uma demo em 30 minutos!"

Você: "Entendo a urgência, vou ajudá-lo imediatamente. Estou verificando
      o status da sua conta agora usando nosso sistema.

      [chama @GET_ACCOUNT_STATUS]

      Sua conta está ativa. Vou enviar um link de redefinição de senha para
      você voltar rapidamente.

      [chama @RESET_PASSWORD]

      Pronto! Verifique seu email para o link de redefinição. Ele é válido por 1 hora.
      Se não ver em 2 minutos, verifique sua pasta de spam.

      Precisa de mais alguma coisa antes da sua demo?"

Quando não souber algo, diga claramente e ofereça conectá-lo
com um especialista. Nunca adivinhe ou invente informações.
```

<Callout type="success">
  O system prompt é onde acontece a maioria do ajuste do agent. Note como **mostramos** ao agent como se comportar através de exemplos e **especificamos** exatamente quando usar cada tool.
</Callout>

### 2. Seleção de Modelo

Escolha o modelo de IA que alimenta seu agent. Atualmente oferecemos os modelos mostrados abaixo, e estamos sempre adicionando mais:

- 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

**Orientação prática:**
- **Suporte ao cliente** - Claude Haiku ou Sonnet (boa compreensão, rápido)
- **Análise de dados** - Claude Sonnet ou GPT-4.1 (melhor raciocínio)
- **Automação simples** - GPT-4.1 mini (rápido e custo-efetivo)
- **Escrita de conteúdo** - Claude Sonnet (criativo e com nuances)

Você pode mudar modelos a qualquer momento.

**Para especificações detalhadas dos modelos**, veja:
- [OpenRouter Models](https://openrouter.ai/models) - Comparação abrangente de modelos
- [Models.dev](https://models.dev/) - Banco de dados open-source de modelos de IA com preços e recursos

**Bring Your Own Model (BYOM) / Bring Your Own Tokens (BYOT):**
Se quiser usar suas próprias API keys ou modelos customizados, vá em **Organização** → **Models** para gerenciar essas configurações.

### 3. Atribuição de Tools

Dê ao seu agent acesso a tools específicos, mas comece com o mínimo.
```
❌ Dar acesso a todos os 50 tools do workspace
✅ Começar com 3-5 tools essenciais, adicionar conforme necessário
```

Muitos tools confundem o agent e tornam a janela de contexto muito grande, levando a respostas mais lentas e custos maiores.

**Exemplo de toolset para suporte ao cliente:**
```
Informações do Cliente:
├─ CUSTOMER_FETCH
└─ CUSTOMER_UPDATE

Cobrança:
├─ INVOICE_FETCH
├─ REFUND_PROCESS
└─ SUBSCRIPTION_UPDATE

Comunicação:
├─ EMAIL_SEND
└─ TICKET_CREATE
```

**No seu system prompt, explique como e quando usar cada tool:**
```
Para consultar o histórico de pedidos de um cliente, use @ORDERS_FETCH com o email dele.
Para processar um reembolso abaixo de R$500, use @REFUND_PROCESS com o ID do pedido.
Para reembolsos acima de R$500, use @TICKET_CREATE para escalar para um gerente.
```

**Atribuindo tools de integrações:**

Na aba Agents, clique em **Tools** → **Adicionar Integração** para dar ao seu agent acesso a tools que vêm com integrações pré-construídas (apps). Aqui, adicione novas integrações ou selecione das instaladas.

<Callout type="warning">
  Tenha cuidado ao dar aos agents tools que deletam dados, cobram dinheiro ou chamam APIs caras. Considere adicionar workflows de aprovação para operações sensíveis.
</Callout>

### 4. Contexto Adicional

Além do system prompt, você pode dar aos agents acesso a contexto adicional através de múltiplas fontes:

#### Documents

Anexe documents que o agent pode buscar e referenciar usando menções `@` em threads e system prompts (ex: `@product-guide`, `@support-faq`).

**O que anexar:**
- Documentação de produto (guias de recursos, FAQs)
- Documentação de processo (SOPs, diretrizes de escalação)
- Informações da empresa (políticas, preços, termos)

**Exemplo:**
```
Documents do Agent de Suporte ao Cliente:
├─ Guia de Recursos do Produto.md
├─ FAQ de Cobrança.md
├─ Guia de Troubleshooting.md
└─ Quando Escalar.md
```

O agent automaticamente busca nesses quando relevante. Você não precisa dizer a ele, ele descobre quando precisa de mais informação.

#### Contexto de Banco de Dados

Dê aos agents acesso ao seu banco de dados para recuperação de dados em tempo real:

**Abordagem atual:**
Use `@DATABASES_RUN_SQL` para consultar seu banco diretamente. Referencie este tool no seu system prompt com exemplos:

```
Para verificar o status de assinatura de um cliente, use @DATABASES_RUN_SQL:
SELECT status, plan, expiry_date FROM subscriptions WHERE user_id = ?
```

**Em breve:** Referências diretas a tabelas e campos sem escrever SQL.

#### RAG e Bases de Conhecimento

**Em breve:** Suporte nativo de primeira classe para RAG e bases de conhecimento.

**Por enquanto, use:**
- **Documents** (como mostrado acima) para Q&A simples e material de referência
- **Integração Pinecone** da deco store para busca vetorial de nível produção e recuperação semântica

Instale Pinecone em **Integrações** → **Navegar Store** → **Pinecone**, depois dê ao seu agent acesso aos tools do Pinecone para busca semântica em grandes bases de conhecimento.

### 5. Configurações Avançadas

Ajuste fino no comportamento (a maioria dos agents funciona bem com padrões):

**Max Steps** (padrão: 15)
- Quantas chamadas de tools o agent pode fazer por resposta
- Maior = pode completar tarefas mais complexas
- Menor = respostas mais rápidas e simples

**Max Tokens** (padrão: 4096-64000 dependendo do modelo)
- Comprimento máximo de resposta
- Ajuste baseado no seu caso de uso (respostas curtas vs. conteúdo longo)

**Temperature** (0.0 - 1.0, padrão: varia por modelo)
- Menor (0.2) = Consistente, determinístico (agents de suporte)
- Maior (0.8) = Criativo, variado (agents de conteúdo)

**Context Window**
- O número de mensagens recentes para manter na memória
- Janela maior = melhor contexto mas maior custo

**Controle de Acesso**
- Controle quem pode interagir e editar este agent

## Padrões Comuns de Agents

### Agent de Suporte ao Cliente
```
Modelo: Claude Sonnet (rápido, bom em conversação)
Tools: CUSTOMER_FETCH, ORDER_LOOKUP, REFUND_PROCESS, TICKET_CREATE
Documents: FAQ, guia de troubleshooting, política de devolução
Tom: Amigável, paciente, orientado a soluções
Visibilidade: Público
```

### Analista de Dados Interno
```
Modelo: GPT-4 (melhor em queries complexas)
Tools: DATABASE_QUERY, CHART_GENERATE, REPORT_CREATE
Documents: Schema do banco de dados, definições de KPI
Tom: Técnico, preciso
Visibilidade: Workspace
```

### Escritor de Conteúdo
```
Modelo: GPT-4 (mais criativo)
Tools: CONTENT_GENERATE, SEO_ANALYZE, CMS_PUBLISH
Documents: Diretrizes de marca, guia de estilo
Tom: Criativo, envolvente, alinhado com a marca
Visibilidade: Workspace
```

## Testando Seu Agent

1. **Caminho feliz** - Tudo funciona como esperado
2. **Informação faltando** - Agent faz perguntas de follow-up
3. **Erros** - Tools falham, agent lida graciosamente
4. **Casos extremos** - Solicitações incomuns ou inesperadas
5. **Multi-etapas** - Tarefas complexas requerendo múltiplos tools
6. **Limites** - Usuário pede ao agent para fazer algo que não deveria

Abra o agent em uma thread e tente conversas reais. Observe quais tools ele chama e como responde. Refine o system prompt baseado no que vê, este é um processo iterativo.

<Callout type="tip">
  **Duas maneiras de configurar agents:** Você pode fazer mudanças manualmente (testar e depois editar system prompt, atribuir tools, ajustar configurações) ou pedir ao deco chat para testar e ajustar para você.
</Callout>

## Monitorando Uso do Agent

Rastreie performance e uso do agent:

- Vá em **Uso** na sua org
- Veja conversas, mensagens, chamadas de tools, custos por agent
- Filtre threads por agent para ver todas as conversas

Use esses insights para:
- Aprender como outros usam o agent
- Identificar problemas comuns ou confusão
- Descobrir casos de uso inesperados
- Melhorar system prompts baseado em padrões reais

**Lembre-se:** Os melhores agents têm system prompts claros e específicos e toolsets cuidadosamente curados. Comece simples e evolua baseado no uso real.
