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 da conversa inteira, cumulativo, em dólares (USD). 0 = sem teto aqui — vale o teto da organização, se houver. Ao ser atingido, a conversa termina, não só o turno. Detalhes em Teto de custo.
installed_skills	—	lista	Habilidades instaladas para o especialista. Padrão: vazia.
installed_prompts	—	lista	Prompts prontos de fontes de ferramentas anexados a este especialista, no formato fonte.prompt. Padrão: vazia.
installed_shared	—	lista	Pastas da área compartilhada que este especialista pode ler. É prefixo de pasta, não caminho de arquivo. Padrão: vazia — e vazia significa que ele não enxerga nada.
knowledge_base	—	mapa	Diz quais arquivos da base de conhecimento o especialista pode ler, por files e/ou tags (ou all_files: true para a base inteira). Sem este bloco, ele não enxerga nenhum arquivo — o acesso é concedido, nunca presumido. Veja a receita em Anexos de conversa.
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: true — para ocultá-los, declare 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.
handoff_message	—	texto	Frase que a plataforma envia ao contato quando a conversa passa para uma pessoa da equipe. De 20 a 500 caracteres e no mínimo 4 palavras. Padrão: frase padrão da plataforma. Detalhes em Mensagem de passagem.
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.

Além dos perfis prontos, você pode criar perfis de roteamento customizados, mapeando cada faixa de complexidade para um modelo e um nível de esforço de raciocínio — e usar o nome deles aqui do mesmo jeito. Veja Perfis de roteamento de modelos.

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 a conversa inteira pode custar, em dólares:

cost_cap:
  per_conversation: 1.50

• É cumulativo e nunca zera. O custo acumulado soma a vida inteira da conversa — não reseta a cada turno, numa compactação nem por passar o tempo.
• 0 significa "sem teto aqui", não "bloqueia tudo". Quando o especialista não define um teto (ou define 0), vale o teto da organização, se houver um configurado. Se nem o especialista nem a organização tiverem um teto positivo, a conversa não tem limite de custo. Não configure um valor negativo: o editor só aceita números ≥ 0.
• O teto do especialista tem precedência quando configurado (> 0), mesmo que seja maior que o da organização. O teto da organização é só o fallback para especialistas que não configuraram o seu.
• Ao ser atingido, a conversa termina — não apenas o turno. Todo turno seguinte é barrado. A mensagem que aparece no painel oferece duas saídas: aumentar o teto do especialista nas configurações dele, ou começar uma conversa nova. A primeira funciona de verdade na mesma conversa — o teto efetivo é reavaliado a cada turno a partir do especialista atual, então subir o valor acima do acumulado libera o turno seguinte sem precisar recomeçar.
• O acumulado só é atualizado ao fim de cada trecho de turno, não durante ele. Um único turno caro pode ultrapassar o teto e mesmo assim completar o trecho em andamento; o corte só vale a partir do trecho seguinte. Isso inclui uma pausa para formulário ou aprovação humana: o custo até a pausa já é contabilizado, e a conversa reavalia o acumulado ao retomar — então o teto pode barrar bem na volta do formulário. Ao ajustar o valor, conte com essa folga.

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.

A plataforma já traz fontes prontas para o especialista trabalhar com anexos e dados: uma para ler e transformar o arquivo enviado na conversa, uma para guardar e consultar documentos na base de conhecimento e uma para analisar planilhas e tabelas. Elas aparecem na tela de fontes de ferramentas como fontes da plataforma, sem endereço nem autenticação para configurar — veja a receita completa em Anexos de conversa.

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 ([]).

Uma habilidade pode ir muito além de um bloco de instruções: ela tem um roteiro principal e pode carregar arquivos de apoio que o agente abre só quando precisa. Veja Habilidades para como escrevê-las.

Prompts prontos de uma fonte — installed_prompts

Além das ferramentas que expõe, uma fonte de ferramentas pode publicar prompts prontos: instruções que os próprios autores da fonte já escreveram para o assunto dela. Anexar um desses prompts faz o especialista se comportar como se aquele texto fosse uma habilidade sua:

tools:
  - documentos.ler_arquivo

installed_prompts:
  - documentos.resumo-executivo

Padrão: nenhum prompt anexado ([]). Anexar as ferramentas de uma fonte não anexa os prompts dela — são listas independentes, de propósito. Veja Prompts prontos de uma fonte para como anexar pela tela, como o conteúdo chega ao agente a cada conversa e os limites.

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 libera no campo Acesso sem usuário identificado — veja Fontes de ferramentas (MCP).

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

O esforço do especialista aceita quatro valores. É um vocabulário diferente do que os perfis de roteamento usam, onde o mesmo campo aceita também none e xhigh: veja Esforço de raciocínio.

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 aparece ao vivo na conversa. Para ocultá-lo e mostrar só a resposta final:

stream_sub_agent_events: false

Padrão: true.

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.

Mensagem de passagem — handoff_message

É a frase que a plataforma envia ao contato no momento em que a conversa passa para uma pessoa da equipe (veja Atendimento humano). Escreva a frase neste campo, não no prompt: no prompt, diga só quando passar a conversa para uma pessoa.

handoff_message: "Vou chamar uma pessoa da nossa equipe para continuar com você. Um instante, por favor."

A frase precisa ter:

• de 20 a 500 caracteres e pelo menos 4 palavras;
• nenhum caractere de controle, além da quebra de linha.

Se a frase não cumprir essas regras, a publicação do especialista é recusada. Espaços no início e no fim são ignorados, e um campo em branco vale como se não estivesse declarado.

No editor do especialista, o campo aparece como Mensagem de passagem para uma pessoa (opcional), com um contador de caracteres.

Padrão: sem handoff_message — a plataforma envia uma frase padrão. A transferência de uma chamada de voz tem o próprio fluxo; veja Transferência para uma pessoa.

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

handoff_message: "Vou chamar uma pessoa da nossa equipe para continuar com você. Um instante, por favor."

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.