Guia de agentes

O que é um agente de IA, como criar, equipar com ferramentas, bases de conhecimento e variáveis, testar, publicar e acompanhar as execuções.

Um agente é uma IA que atende conversas em nome do workspace. Ele é feito de um prompt, um modelo, ferramentas (as ações que a IA pode tomar), bases de conhecimento e variáveis iniciais. Depois de publicado, atende as conversas receptivas de um canal, as conversas delegadas a ele e as chamadas de fluxos.

Todo agente tem um rascunho e, depois da primeira publicação, uma versão publicada. Tudo o que você edita muda só o rascunho; as conversas usam a versão publicada até a próxima publicação. A simulação e os cenários de teste rodam no rascunho.

Cada tipo de ferramenta tem a própria configuração e os próprios campos. Eles estão no Catálogo de ferramentas, gerado a partir do código.

Como um agente é montado

ParteOnde ficaO que faz
Nome e descriçãoname (obrigatório, até 120 caracteres) e descriptionIdentificam o agente nas listas e nas transferências.
PromptmessagingPrompt (obrigatório)As instruções da IA. Aceita variáveis no formato {{nome}}.
ModelomessagingModel (obrigatório, até 64 caracteres) e provider (platform)O modelo de linguagem que responde.
Ferramentas/agents/{id}/toolsAções que a IA pode tomar: transferir, agendar, chamar uma API, buscar na base de conhecimento e outras.
Bases de conhecimentoknowledgeBaseIds, ragEnabled e ragConfigDocumentos que a IA consulta antes de responder.
Variáveis iniciaisvariablesValores que cada conversa traz para o prompt, com valor padrão opcional.
EstadoisActiveSó um agente ativo assume conversas.
DepartamentodepartmentIdO departamento a que o agente pertence. Veja Workspaces e departamentos.

Crie um agente

POST /agents com o corpo mínimo abaixo. internalTools é obrigatório: envie [] e adicione as ferramentas depois, uma a uma, em /agents/{id}/tools.

curl -X POST "https://api.vozkoia.com/agents" \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "X-Workspace-ID: SEU_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Atendimento",
    "messagingPrompt": "Você atende os clientes da loja. Responda em português, com frases curtas.",
    "messagingModel": "openai/gpt-4o",
    "provider": "platform",
    "internalTools": []
  }'

A resposta 201 traz o agente criado, com o id que as demais rotas usam.

  • provider é sempre platform.
  • messagingModel é o id de um modelo de GET /agents/options (veja a seção Prompt e modelo).
  • departmentId escolhe o departamento do agente. Quem participa de mais de um departamento precisa enviá-lo (400 com o código agent_department_required).
  • O agente nasce ativo: na criação, isActive é sempre true.
  • variables e knowledgeBaseIds também podem ir na criação, com as regras das seções abaixo.
  • mcpCollectionIds não é mais aceito (400 com o código agent_mcp_collections_moved): servidores MCP são ferramentas do tipo mcp_source.

Um agente recém-criado ainda não tem versão publicada e, por isso, não atende ninguém. Teste, ajuste e publique (veja a seção Publicação e versões).

Prompt e modelo

GET /agents/options lista os modelos disponíveis, do mais popular para o menos popular:

CampoO que traz
messagingOs ids aceitos em messagingModel.
modelPricingPara cada modelo: preço por milhão de tokens, janela de contexto, capacidades (capabilities) e, quando o modelo oferece, os níveis de raciocínio.
modelCapabilitiesO vocabulário de capacidades, como vision, tools e long_context.
defaults.messagingModelO modelo padrão.

Um agente com ferramentas precisa de um modelo com a capacidade tools. Sem ela, a publicação é recusada com o problema agent_model_without_tools. A publicação também confere se o prompt e as ferramentas cabem na janela de contexto do modelo (agent_tools_exceed_context).

Para mudar o prompt, o modelo ou os outros campos, use PUT /agents/{id}. Esta rota substitui os campos do agente pelo corpo enviado, então envie o agente inteiro:

  • isActive é obrigatório.
  • name, description, messagingPrompt, messagingModel, provider, avatarUrl, tags, metadata, ragEnabled e ragConfig são gravados como vieram; um campo ausente fica vazio, e ragEnabled ausente vale false.
  • variables, knowledgeBaseIds e mediaIds ausentes ficam como estão; enviados, substituem a lista inteira.
  • As ferramentas não vão neste corpo: um corpo com internalTools recebe 400 com o código agent_tools_moved.

Ao ligar de novo um agente desligado (isActive de false para true), as ferramentas da versão publicada são conferidas; se alguma tiver problema bloqueante, a resposta é 422 com o código agent_not_activatable e a lista de problemas em details.

Ferramentas

Cada ferramenta de um agente é uma instância de um tipo do catálogo (GET /agents/tools), com o próprio nome de função, a própria descrição para a IA e a própria configuração. O tipo diz quantas instâncias cabem num agente:

instancesRegra
singleUma por agente. A segunda responde 409 com o código agent_tool_single_type_taken.
per_targetUma por destino (por exemplo, um fluxo ou um departamento), identificado pelo campo em bindingKey. Repetir o destino responde 409 com o código agent_tool_target_taken.
manyQuantas forem precisas, como Requisição HTTP e Buscar na base de conhecimento. Cada instância exige description (400 com o código agent_tool_description_required).

Adicione uma ferramenta

POST /agents/{id}/tools com o tipo em type, a configuração em config, a descrição em description e, se quiser, o nome da função em name:

curl -X POST "https://api.vozkoia.com/agents/ID_DO_AGENTE/tools" \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "X-Workspace-ID: SEU_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "search_knowledge_base",
    "description": "Busque aqui antes de responder perguntas sobre produtos, preços e prazos.",
    "config": {}
  }'
  • Nome da função. É o nome que a IA chama: letras minúsculas, dígitos e _, começando por letra, com até 64 caracteres, sem repetir outro nome do agente. Sem name, a API propõe o nome do tipo, numerado quando o agente já tem outra instância (search_knowledge_base, search_knowledge_base_2).
  • Configuração. Os campos de config de cada tipo, com tipo, obrigatoriedade, opções e valor padrão, estão no Catálogo de ferramentas. Um campo desconhecido ou com o tipo errado responde 400 com o código agent_tool_invalid.
  • Credenciais. Credenciais digitadas em cabeçalhos de autenticação ou na consulta da URL vão para os segredos do workspace, e a configuração guarda só a referência ({{secret.nome}}). Nas leituras, a credencial nunca volta.
  • Ordem. A IA recebe as ferramentas na ordem da lista. Para mudar, envie todos os ids na nova ordem em PUT /agents/{id}/tools/order.
  • Revisões. Cada alteração grava uma revisão imutável. Em PUT /agents/{id}/tools/{toolId}, envie a revision que você leu; se outra pessoa salvou antes, a resposta é 409 com o código agent_tool_revision_conflict.

No objeto do agente (GET /agents/{id}), as ferramentas aparecem em internalTools com o tipo em name e o nome da função em function. Nas rotas /agents/{id}/tools, o tipo vem em type e o nome da função em name.

Confira e teste

  • POST /agents/{id}/tools/validate roda o mesmo validador da publicação. Sem corpo, confere as ferramentas salvas; com tools, confere um rascunho sem salvar. Cada problema traz code, severity (blocking ou advisory), toolId e uma dica. Se uma conferência externa não responder, o resultado traz agent_tool_validation_unavailable como bloqueante.
  • POST /agents/{id}/tools/{toolId}/test roda uma ferramenta sozinha, e POST /agents/{id}/tools/test faz o mesmo com uma configuração ainda não salva. O testMode de cada tipo diz o que acontece: run chama a API de verdade (métodos que alteram dados exigem "confirmRealCall": true, senão 422 com o código agent_tool_test_real_call_not_confirmed), preview mostra o que a ferramenta faria sem executar, e scenario não roda sozinha (422 com o código agent_tool_test_unsupported): teste num cenário.

Servidores MCP

Um servidor MCP oferece ferramentas próprias à IA. Primeiro o servidor é conectado ao workspace, no aplicativo, em Menu lateral › Agentes › Servidores MCP: servidores integrados do catálogo, com chave de API ou login OAuth 2, ou servidores remotos por um endereço https, sem autenticação, com chave de API ou com OAuth 2.

Depois, cada agente recebe o servidor como uma ferramenta do tipo mcp_source, uma por servidor:

  1. GET /agents/tools/mcp-sources lista os servidores conectados com as ferramentas de cada um. Um servidor que não respondeu vem com unavailable: true e sem ferramentas.
  2. POST /agents/{id}/tools com "type": "mcp_source" e, em config, o servidor em source_id e as ferramentas permitidas em tools, ou "all_tools": true para todas, inclusive as que o servidor ganhar depois.

Cada ferramenta permitida chega à IA como uma função própria.

Bases de conhecimento

Uma base de conhecimento guarda documentos divididos em trechos e indexados por significado. As rotas ficam em /knowledge-bases: cada workspace tem até 5 bases, e cada base até 120 documentos, criados a partir de texto, de uma mídia já enviada ou de arquivos (POST /knowledge-bases/{id}/documents/upload, até 10 MB por arquivo).

O agente usa as bases de dois jeitos, que podem ser combinados:

JeitoComo ligarO que acontece
Contexto automáticoknowledgeBaseIds e "ragEnabled": trueA cada mensagem do cliente, os trechos mais próximos das bases do agente entram no contexto da IA.
Ferramenta de buscaUma ferramenta search_knowledge_baseA IA decide quando buscar e pode reformular a busca. Com knowledge_base_ids na configuração, a busca olha só para essas bases; vazio, olha todas as bases do agente.

As bases do agente vão em knowledgeBaseIds, na criação ou no PUT /agents/{id}, ou em PUT /agents/{id}/knowledge-bases. Cada base precisa ser do mesmo workspace (400 com o código agent_knowledge_base_no_access).

O contexto automático segue ragConfig; um campo ausente usa o padrão:

CampoPadrãoO que controla
maxChunks5Quantos trechos entram no contexto.
minScore0.3A nota mínima de similaridade de um trecho.
maxChunksPerDoc3Quantos trechos de um mesmo documento entram.
contextWindow1Quantos trechos vizinhos acompanham cada trecho encontrado.
numCandidates10Quantos candidatos a busca considera antes de escolher.
maxCharacters10000O limite de caracteres do contexto.

Para ver o que um agente encontraria, use POST /knowledge-bases/query com a pergunta em query e as bases em knowledgeBaseIds.

Variáveis iniciais

Variáveis levam dados de cada conversa para o prompt. Escreva {{nome}} no prompt e declare a variável em variables:

{
  "messagingPrompt": "Você confirma pedidos. O pedido do cliente é {{pedido}} e o turno de entrega é {{turno}}.",
  "variables": [
    { "name": "pedido", "description": "Número do pedido" },
    { "name": "turno", "description": "Turno de entrega", "defaultValue": "Manhã" }
  ]
}
RegraCódigo da recusa
Nome com letras sem acento, dígitos e _, até 64 caracteresagent_variable_name_invalid
lead_name, lead_number e campaign_name são preenchidos pela plataforma e não podem ser declaradosagent_variable_name_reserved
Nomes sem repetiragent_variable_duplicate
Até 50 variáveisagent_variable_too_many
  • Uma variável sem defaultValue é obrigatória: quem aciona o agente precisa preencher. Com defaultValue, é opcional.
  • Um {{nome}} sem valor na conversa e sem padrão vira texto vazio no prompt.
  • O nome amigável e o tipo de cada variável moram na declaração do workspace, em /conversation-variables (grupo Dados da conversa da referência), a mesma de fluxos, campanhas e transferências. Um nome não declarado vale como texto. Na publicação, um defaultValue incompatível com o tipo declarado é bloqueado (agent_variable_default_invalid).

Para conferir as variáveis antes de salvar, POST /agents/{id}/conversation-variables (ou POST /agents/conversation-variables, para um agente novo) recebe o prompt e as variáveis do formulário e devolve cada variável com required, inAgent, inPrompt, quem pode preenchê-la (filledBy: default, campaign, handoff ou transfer) e, quando o nome não pode ser salvo, o motivo em problem. Para quem vai acionar o agente, GET /agents/{id}/required-variables lista as variáveis com required e usedIn.

Teste antes de publicar

Simulação

POST /agents/{id}/simulate roda um turno de conversa no rascunho, montado como em produção: prompt, ferramentas, base de conhecimento e memórias do lead.

{
  "message": "Qual o prazo de entrega para São Paulo?",
  "history": [
    { "role": "user", "content": "Oi" },
    { "role": "assistant", "content": "Olá! Como posso ajudar?" }
  ]
}
  • message é obrigatório; history aceita até 60 mensagens, com role user ou assistant. lead_id traz as memórias reais de um lead.
  • Só ferramentas de leitura rodam de verdade: busca na base de conhecimento, consulta de disponibilidade, validação de CEP e Requisição HTTP com método de leitura. As demais são interceptadas, e a chamada volta com stubbed: true.
  • A resposta traz replies, toolCalls e, em debug, o modelo, o prompt de sistema montado, as ferramentas oferecidas e os tokens.
  • A simulação consome créditos de IA como uma conversa.

Cenários

Um cenário é uma conversa roteirizada que você salva e roda de novo a cada mudança, para ver o que passou a falhar. POST /agents/{id}/scenarios:

{
  "name": "Pergunta de prazo",
  "messages": [
    { "content": "Qual o prazo de entrega para São Paulo?" }
  ],
  "mocks": {},
  "assertions": [
    { "kind": "tool_called", "toolId": "ID_DA_FERRAMENTA" },
    { "kind": "reply_matches", "match": "contains", "value": "dias úteis" }
  ]
}
  • name (até 120 caracteres), ao menos uma mensagem (até 60) e ao menos uma verificação são obrigatórios.
  • mocks dá uma resposta simulada a uma ferramenta, pelo id dela: {"ID_DA_FERRAMENTA": {"result": {...}, "isError": false}}, até 64 KB cada. Ferramentas com resposta simulada não chamam nada; sem ela, valem as mesmas regras da simulação.
kindCampos
tool_calledtoolId e, opcionalmente, arguments com match exact, subset ou regex.
tool_not_calledtoolId.
tool_output_matchestoolId, path (por exemplo data.itens[0].id), match exact ou regex e value.
reply_matchesmatch contains ou regex e value; confere a última resposta.
reply_judgedrubric (até 2.000 caracteres): um avaliador de IA lê a conversa e decide; o uso é cobrado como na simulação.

POST /agents/{id}/scenarios/{scenarioId}/run roda um cenário e POST /agents/{id}/scenarios/run roda todos. GET /agents/{id}/scenarios/{scenarioId}/runs mostra as 20 execuções mais recentes. Para transformar uma conversa real em cenário, POST /agents/{id}/runs/{runId}/scenario monta um rascunho a partir de uma execução; revise e salve com POST /agents/{id}/scenarios.

Publicação e versões

POST /agents/{id}/publish publica o rascunho como uma nova versão imutável, que fixa a revisão de cada ferramenta.

  • Antes de publicar, o rascunho passa pelo validador. Com algum problema bloqueante, a resposta é 422 com o código agent_not_publishable e a lista em details.issues.
  • Um rascunho igual à versão publicada não cria versão nova; a resposta é a versão atual.
  • Se a nova versão exigir variáveis que canais receptivos não trazem, a publicação desligaria esses canais: a resposta é 409 com o código automation_publish_switches_off, e os canais vêm em details.impact. Confira antes com GET /automation-needs/agent/{id}/publish-impact e confirme com ?confirmSwitchOff=true.
RotaO que faz
GET /agents/{id}/publicationA versão publicada, quando e por quem, e se o rascunho tem mudanças não publicadas. Sem versão, publishedVersion vem nulo e o agente não atende.
GET /agents/{id}/versionsAs versões publicadas, da mais nova para a mais antiga.
GET /agents/{id}/versions/{version}O prompt, o modelo e as revisões de ferramenta de uma versão.
POST /agents/{id}/versions/{version}/restoreCopia uma versão para o rascunho. Nada muda nas conversas até a próxima publicação.

Execuções

Cada turno da IA vira uma execução: modelo, situação, duração, tokens, custo informado pelo provedor e as chamadas de ferramenta, com argumentos, requisição e resposta HTTP (segredos mascarados) e o que a IA leu.

  • GET /agents/{id}/runs lista as execuções, da mais recente para a mais antiga, com os filtros from, to, source (conversation, simulator, scenario ou workflow), status (ok, tool_failed ou failed), toolId, errorKind, entryId e handledFailure. Um filtro inválido responde 400 com o código agent_run_filter_invalid.
  • GET /agents/{id}/runs/{runId} devolve uma execução completa.
  • Execuções de conversas aparecem só para quem pode ver a conversa. As execuções são guardadas por 180 dias; o conteúdo das chamadas, por 30.

Coloque o agente para atender

Um agente atende quando está ativo e publicado. Ele chega às conversas por:

CaminhoRota
Atendimento receptivo de um número do WhatsApp oficialPUT /whatsapp/business-phones/{id}/automation, com o agente em agentId. Vale para as conversas receptivas do número.
Delegação de uma conversaPUT /conversations/{entryType}/{entryId}/delegation com {"kind": "agent", "id": "ID_DO_AGENTE"}. O agente passa a responder só essa conversa e fica como responsável (ai:<id>) até ela ser finalizada.
Transferência entre automaçõesUma ferramenta transfer_to_automation em outro agente, com este agente entre os destinos.

Se a conversa não tiver valor para uma variável obrigatória, a delegação responde 409 com o código automation_variables_missing; preencha com PUT /conversations/{entryType}/{entryId}/variables e tente de novo. PATCH /conversations/{entryType}/{entryId}/automation pausa ou retoma o atendimento automático de uma conversa.

Arquivar, excluir e departamentos

  • PATCH /agents/{id}/archive tira o agente de GET /agents sem perder a configuração; ele passa a aparecer em GET /agents/archived. PATCH /agents/{id}/unarchive desfaz.
  • DELETE /agents/{id} apaga o agente de vez.
  • PATCH /agents/{id}/department move o agente de departamento. Só donos e administradores do workspace movem um agente depois de criado.
  • Um agente de outro workspace, ou de um departamento a que a pessoa não tem acesso, responde 403 com o código agent_forbidden.

Erros principais

StatuscodeQuando acontece
400agent_name_required, agent_name_too_longname vazio ou com mais de 120 caracteres.
400agent_messaging_prompt_requiredmessagingPrompt vazio.
400agent_messaging_model_too_longmessagingModel com mais de 64 caracteres.
400sem code, campo em expectedprovider, messagingModel ou internalTools ausente ou inválido.
400agent_tools_moved, agent_mcp_collections_movedinternalTools no PUT /agents/{id}, ou mcpCollectionIds em qualquer corpo.
400agent_tool_invalidTipo de ferramenta indisponível ou configuração inválida.
400agent_variable_name_invalid, agent_variable_name_reserved, agent_variable_duplicate, agent_variable_too_manyVariável fora das regras.
400agent_knowledge_base_no_accessBase de conhecimento de fora do workspace.
400agent_department_required, agent_department_invalidDepartamento ausente para quem participa de mais de um, ou sem acesso.
400agent_tool_type_unknown, agent_tool_name_invalid, agent_tool_description_required, agent_tool_order_mismatchFerramenta fora das regras.
403agent_forbiddenAgente de outro workspace ou de um departamento sem acesso.
404agent_not_found, agent_tool_not_found, agent_version_not_found, agent_scenario_not_found, agent_run_not_foundO recurso não existe neste agente.
409agent_tool_name_taken, agent_tool_single_type_taken, agent_tool_target_taken, agent_tool_revision_conflictConflito com as ferramentas atuais.
409automation_publish_switches_offA publicação desligaria canais receptivos.
422agent_not_publishable, agent_not_activatableProblemas bloqueantes; a lista vem em details.
422agent_tool_test_real_call_not_confirmed, agent_tool_test_unsupportedTeste de ferramenta sem confirmação ou de um tipo que só roda em cenário.
400, 413agent_scenario_invalid, agent_scenario_too_long, agent_scenario_mock_too_largeCenário fora das regras.
503agent_tool_validation_unavailableUma conferência externa não respondeu. Tente de novo em instantes.

A simulação usa códigos próprios: invalid_request (400), not_found (404) e ai_error (502, quando o provedor de IA falha). O formato das respostas de erro está em Erros.

Referência

Os tipos de ferramenta, com a configuração e os campos de cada um, estão no Catálogo de ferramentas.