Configuração do especialista

Um especialista é a configuração de um agente: um documento YAML que define qual modelo ele usa, as instruções que segue, as ferramentas que pode acionar, os limites de custo, se ele atende por voz, se aceita visitantes anônimos e como ele raciocina antes de responder. Cada especialista tem um id único e é acionado pelo seu identificador quando uma conversa começa.

Esta página é a referência completa do arquivo de configuração: todos os campos, o que cada um faz, quais são obrigatórios e exemplos prontos para copiar.

Anatomia do arquivo

Um especialista mínimo precisa de identidade (id, version, kind), um modelo (model), instruções (prompt), a lista de ferramentas (tools, que pode ser vazia) e um teto de custo (cost_cap):

id: assistente
version: "1.0.0"
kind: specialist

model:
  default: default
  fallback: default

tools: []

prompt: |
  Você é um assistente prestativo e objetivo. Responda em português,
  de forma clara e concisa.

installed_skills: []

cost_cap:
  per_conversation: 1.00

Esse é um especialista completo e válido. Todo o resto — raciocínio estendido, ferramentas, sub-agentes, saída estruturada e pausas para revisão humana — é opcional e some por padrão quando você não declara.

Referência de campos

Campo	Obrigatório	Tipo	Descrição
id	✅	texto	Identificador único do especialista. É por ele que a conversa aciona o agente.
version	✅	texto	Versão da configuração. Use aspas ("1.0.0") para o YAML não interpretar como número.
kind	✅	texto	Tipo da configuração. Use specialist.
model.default	✅	texto	Modelo principal do especialista.
model.fallback	✅	texto	Modelo de reserva, usado se o principal ficar indisponível.
prompt	✅	texto	Instruções do agente (o "system prompt"). Use `
tools	✅	lista	Ferramentas que o especialista pode usar. Pode ser vazia ([]).
cost_cap.per_conversation	✅	número	Teto de custo por conversa, em dólares (USD).
installed_skills	—	lista	Habilidades instaladas para o especialista. Padrão: vazia.
allowed_agents	—	lista	Outros especialistas para os quais este pode delegar tarefas. Padrão: vazia.
sub_agents	—	lista	Sub-agentes declarados dentro deste especialista. Padrão: vazia.
reasoning	—	mapa	Configuração de raciocínio estendido. Padrão: desligado.
stream_sub_agent_events	—	booleano	Mostra ao vivo os eventos dos sub-agentes. Padrão: false.
response_format	—	mapa	Esquema (JSON Schema) para forçar uma resposta estruturada. Padrão: resposta livre.
interrupt_on	—	mapa	Pausas para aprovação humana antes de certas ferramentas. Padrão: sem pausas.
voice_enabled	—	booleano	Habilita chamada de voz para este agente. Padrão: true.
public	—	booleano	Permite que o agente atenda visitantes anônimos (modo público). Padrão: false.

Campos obrigatórios

Identidade — id, version, kind

id: suporte-nivel-1
version: "1.0.0"
kind: specialist

• id identifica o especialista de forma única. É o nome usado para acioná-lo.
• version documenta a versão da configuração. Sempre entre aspas, para o YAML tratar como texto e não como número.
• kind descreve o tipo da configuração — use specialist.

Modelo — model

O bloco model define qual modelo responde e qual entra como reserva:

model:
  default: default
  fallback: default

Cada valor pode ser um perfil automático — que escolhe o modelo conforme a complexidade de cada mensagem — ou o identificador de um modelo específico.

Perfil	Quando usar
cheap	Prioriza custo. Bom para tarefas simples e de alto volume.
default	Equilíbrio entre custo e qualidade. Escolha segura para a maioria dos casos.
smart	Prioriza qualidade. Bom para tarefas complexas ou sensíveis.

Para fixar um modelo específico, use o identificador do modelo no lugar do perfil (por exemplo, um modelo da família Claude Sonnet ou Haiku):

model:
  default: us.anthropic.claude-sonnet-4-6-20251001-v1:0
  fallback: us.anthropic.claude-haiku-4-5-20251001-v1:0

O fallback só é acionado quando o default fica indisponível — declare sempre os dois.

Instruções — prompt

O prompt são as instruções permanentes do agente. Use o indicador | do YAML para escrever em várias linhas preservando as quebras:

prompt: |
  Você é um atendente de suporte de nível 1. Seja cordial e direto.

  - Resolva o que estiver ao seu alcance com as ferramentas disponíveis.
  - Quando não for possível, transfira para um atendente humano.
  - Nunca invente informações sobre a conta do cliente.

Boas instruções são específicas: descrevem o papel do agente, o tom, o que ele deve e não deve fazer e quando pedir ajuda.

Teto de custo — cost_cap

Limita quanto uma única conversa pode custar, em dólares:

cost_cap:
  per_conversation: 1.50

Ao atingir o teto, a conversa para de consumir novos recursos do modelo. Ajuste conforme o valor de cada atendimento e o volume esperado.

Campos opcionais

Ferramentas — tools

Lista as ferramentas que o especialista pode acionar. Cada item usa o formato servidor.ferramenta, onde servidor é uma fonte de ferramentas conectada à plataforma e ferramenta é a capacidade específica que ela expõe:

tools:
  - tavily.tavily_search
  - tavily.tavily_extract

Se o especialista não usa ferramentas, declare a lista vazia:

tools: []

Descreva no prompt quando e como usar cada ferramenta — só listá-las não garante que o agente as use no momento certo.

Cada servidor é uma fonte de ferramentas conectada à plataforma. Veja Fontes de ferramentas (MCP) para como configurá-las e os modos de autenticação disponíveis.

Habilidades — installed_skills

Habilidades são pacotes reutilizáveis de instruções e recursos que ampliam o que o especialista sabe fazer. Liste as que ele deve ter instaladas:

installed_skills:
  - resumo-de-documentos
  - triagem-de-chamados

Padrão: nenhuma habilidade instalada ([]).

Voz — voice_enabled

Controla se o agente pode ser acionado por chamada de voz. Por padrão, todo agente tem voz habilitada (true). Para desligar a voz de um agente:

voice_enabled: false

Isso faz com que o botão de chamada de voz não apareça para esse agente no painel e que os canais de voz recusem inicia-lo. Especialistas criados antes deste campo existirem mantêm voz habilitada.

Padrão: true.

Agente público — public

Permite que o agente atenda visitantes anônimos (sem login) através da porta pública da sua organização. É um opt-in: por padrão, nenhum agente aceita acesso anônimo.

public: true

Quando true, o agente pode receber conversas de visitantes que não fizeram login. As ferramentas disponíveis nessas conversas continuam limitadas ao que cada fonte MCP permite como "acesso anônimo".

Padrão: false.

Raciocínio estendido — reasoning

Faz o especialista pensar antes de responder, gastando um esforço extra de raciocínio em problemas mais difíceis. Há duas formas de configurar, e você usa exatamente uma delas.

Por esforço (recomendado):

reasoning:
  effort: medium        # um de: minimal | low | medium | high

Por orçamento de tokens (controle fino):

reasoning:
  budget_tokens: 5000   # número positivo de tokens de raciocínio

Regras:

• Declare effort ou budget_tokens, nunca os dois no mesmo bloco — declarar ambos (ou nenhum) é um erro de configuração e o especialista não carrega.
• budget_tokens precisa ser um número positivo.
• Para desligar o raciocínio, omita o bloco reasoning inteiro.

Você também pode definir tetos de raciocínio, que limitam o quanto uma conversa pode elevar o esforço:

reasoning:
  effort: low           # valor padrão do especialista
  max_effort: high      # teto que uma conversa pode solicitar

Campo	Descrição
effort	Nível de esforço padrão: minimal, low, medium ou high.
budget_tokens	Orçamento padrão de tokens de raciocínio (número positivo).
max_effort	Teto de esforço que uma conversa pode solicitar.
max_budget_tokens	Teto de orçamento de tokens que uma conversa pode solicitar.

Delegação para outros especialistas — allowed_agents

Permite que este especialista delegue tarefas para outros especialistas já configurados na plataforma. Liste os ids permitidos:

allowed_agents:
  - tradutor
  - analista-financeiro

Padrão: lista vazia — nenhuma delegação para especialistas externos.

Sub-agentes — sub_agents

Sub-agentes são auxiliares declarados dentro do próprio especialista. O agente principal divide um pedido complexo em subtarefas e despacha cada uma para o sub-agente adequado, depois consolida os resultados numa resposta final.

sub_agents:
  - name: resumidor
    description: "Resume um texto em exatamente três tópicos."
    prompt: |
      Você resume textos. Leia a passagem do usuário e produza exatamente
      três tópicos concisos com os pontos principais. Sem introdução.
    tools: []

  - name: verificador
    description: "Verifica afirmações e rotula cada uma como VERDADEIRO / FALSO / DESCONHECIDO."
    prompt: |
      Você verifica fatos. Para cada afirmação, responda VERDADEIRO, FALSO ou
      DESCONHECIDO, com uma frase de justificativa.
    tools: []
    model: us.anthropic.claude-haiku-4-5-20251001-v1:0

Campos de cada sub-agente:

Campo	Obrigatório	Descrição
name	✅	Nome único do sub-agente (usado para despachar tarefas a ele).
description	✅	Para que serve — orienta quando o agente principal deve acioná-lo.
prompt	✅	Instruções do sub-agente.
tools	—	Ferramentas do sub-agente. Devem ser um subconjunto das ferramentas do especialista principal.
model	—	Modelo próprio do sub-agente. Se omitido, herda o comportamento padrão.
reasoning	—	Raciocínio próprio do sub-agente (mesmas regras da seção acima). Não é herdado do especialista principal.

Regras importantes:

• Cada name de sub-agente deve ser único dentro do especialista.
• As tools de um sub-agente precisam estar contidas nas tools do especialista principal — um sub-agente não pode usar ferramenta que o principal não tem.
• Uma referência sem ponto (ex.: tavily) no tools do especialista principal concede todas as ferramentas daquele servidor. Sub-agentes também podem usar essa referência ampla.

Eventos de sub-agentes ao vivo — stream_sub_agent_events

Por padrão, o trabalho interno dos sub-agentes não aparece ao vivo na conversa. Para exibi-lo enquanto acontece, ligue:

stream_sub_agent_events: true

Padrão: false.

Saída estruturada — response_format

Força a resposta final a seguir um formato estruturado, descrito como um esquema (JSON Schema). Útil quando outra parte do sistema vai consumir a resposta:

response_format:
  type: object
  properties:
    sentimento:
      type: string
      enum: [positivo, neutro, negativo]
    resumo:
      type: string
  required:
    - sentimento
    - resumo

Padrão: sem response_format — a resposta é texto livre.

Aprovação humana — interrupt_on

Faz o agente pausar e pedir aprovação de uma pessoa antes de executar determinadas ferramentas — útil para ações sensíveis ou irreversíveis. A chave é o nome da ferramenta:

interrupt_on:
  db.delete_record:
    allowed_decisions:
      - approve
      - reject
    description: "Remoção de registro — requer confirmação humana."

Para cada ferramenta listada:

Campo	Descrição
allowed_decisions	Decisões que a pessoa pode tomar: approve (aprovar), edit (editar antes de executar), reject (recusar), respond (responder sem executar). Padrão: approve e reject.
description	Texto opcional mostrado junto ao pedido de aprovação.

Padrão: sem interrupt_on — nenhuma pausa; o agente executa as ferramentas diretamente.

Exemplos completos

Assistente com busca na web

id: pesquisador-web
version: "1.0.0"
kind: specialist

model:
  default: default
  fallback: default

tools:
  - tavily.tavily_search
  - tavily.tavily_extract

prompt: |
  Você é um assistente de pesquisa. Quando a pergunta exigir informação atual,
  use `tavily_search` para buscar e `tavily_extract` para ler URLs específicas.
  Escreva uma resposta concisa e sempre cite as fontes (URLs).

installed_skills: []

cost_cap:
  per_conversation: 1.00

Agente que raciocina antes de responder

id: raciocinador
version: "1.0.0"
kind: specialist

model:
  default: smart
  fallback: default

tools: []

prompt: |
  Você é um assistente cuidadoso. Para qualquer pergunta, pense passo a passo
  antes de responder. Seja conciso na resposta final.

installed_skills: []

cost_cap:
  per_conversation: 1.50

reasoning:
  effort: medium
  max_effort: high

Agente público de atendimento (com voz)

id: atendimento-publico
version: "1.0.0"
kind: specialist

model:
  default: default
  fallback: default

tools:
  - tavily.tavily_search

prompt: |
  Você é um atendente de primeiro contato. Seja cordial e objetivo.

  - Quando não souber responder, transfira para um atendente humano.
  - Nunca peça dados pessoais sensíveis.

installed_skills: []

cost_cap:
  per_conversation: 1.00

voice_enabled: true
public: true

Coordenador com sub-agentes

id: coordenador
version: "1.0.0"
kind: specialist

model:
  default: us.anthropic.claude-haiku-4-5-20251001-v1:0
  fallback: us.anthropic.claude-haiku-4-5-20251001-v1:0

tools: []

prompt: |
  Você é um coordenador de pesquisa. Para pedidos complexos, quebre em
  subtarefas e delegue cada uma ao sub-agente adequado. Depois, escreva uma
  resposta consolidada.

installed_skills: []

cost_cap:
  per_conversation: 1.00

stream_sub_agent_events: true

sub_agents:
  - name: resumidor
    description: "Resume um texto em exatamente três tópicos."
    prompt: |
      Leia a passagem e produza exatamente três tópicos concisos. Sem introdução.
    tools: []

  - name: verificador
    description: "Verifica afirmações (VERDADEIRO / FALSO / DESCONHECIDO)."
    prompt: |
      Para cada afirmação, responda VERDADEIRO, FALSO ou DESCONHECIDO, com uma
      frase de justificativa.
    tools: []

Erros comuns de configuração

Se um especialista tem configuração inválida, ele não é carregado e qualquer conversa que tente acioná-lo recebe erro de agente desconhecido. Verifique:

• Faltou um campo obrigatório (id, version, kind, model.default, model.fallback, prompt, tools, cost_cap.per_conversation).
• Bloco reasoning com os dois valores (effort e budget_tokens) ou com nenhum — declare exatamente um.
• budget_tokens zero ou negativo — precisa ser positivo.
• Sub-agente com nome repetido — cada name deve ser único.
• Sub-agente usando ferramenta que o principal não tem — as tools do sub-agente devem ser um subconjunto das do especialista principal.
• version sem aspas — pode ser interpretada como número e falhar.