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
| Parte | Onde fica | O que faz |
|---|---|---|
| Nome e descrição | name (obrigatório, até 120 caracteres) e description | Identificam o agente nas listas e nas transferências. |
| Prompt | messagingPrompt (obrigatório) | As instruções da IA. Aceita variáveis no formato {{nome}}. |
| Modelo | messagingModel (obrigatório, até 64 caracteres) e provider (platform) | O modelo de linguagem que responde. |
| Ferramentas | /agents/{id}/tools | Ações que a IA pode tomar: transferir, agendar, chamar uma API, buscar na base de conhecimento e outras. |
| Bases de conhecimento | knowledgeBaseIds, ragEnabled e ragConfig | Documentos que a IA consulta antes de responder. |
| Variáveis iniciais | variables | Valores que cada conversa traz para o prompt, com valor padrão opcional. |
| Estado | isActive | Só um agente ativo assume conversas. |
| Departamento | departmentId | O 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é sempreplatform.messagingModelé oidde um modelo deGET /agents/options(veja a seção Prompt e modelo).departmentIdescolhe o departamento do agente. Quem participa de mais de um departamento precisa enviá-lo (400com o códigoagent_department_required).- O agente nasce ativo: na criação,
isActiveé sempretrue. variableseknowledgeBaseIdstambém podem ir na criação, com as regras das seções abaixo.mcpCollectionIdsnão é mais aceito (400com o códigoagent_mcp_collections_moved): servidores MCP são ferramentas do tipomcp_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:
| Campo | O que traz |
|---|---|
messaging | Os ids aceitos em messagingModel. |
modelPricing | Para 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. |
modelCapabilities | O vocabulário de capacidades, como vision, tools e long_context. |
defaults.messagingModel | O 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,ragEnablederagConfigsão gravados como vieram; um campo ausente fica vazio, eragEnabledausente valefalse.variables,knowledgeBaseIdsemediaIdsausentes ficam como estão; enviados, substituem a lista inteira.- As ferramentas não vão neste corpo: um corpo com
internalToolsrecebe400com o códigoagent_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:
instances | Regra |
|---|---|
single | Uma por agente. A segunda responde 409 com o código agent_tool_single_type_taken. |
per_target | Uma 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. |
many | Quantas 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. Semname, 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
configde 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 responde400com o códigoagent_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 emPUT /agents/{id}/tools/order. - Revisões. Cada alteração grava uma revisão imutável. Em
PUT /agents/{id}/tools/{toolId}, envie arevisionque você leu; se outra pessoa salvou antes, a resposta é409com o códigoagent_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/validateroda o mesmo validador da publicação. Sem corpo, confere as ferramentas salvas; comtools, confere um rascunho sem salvar. Cada problema trazcode,severity(blockingouadvisory),toolIde uma dica. Se uma conferência externa não responder, o resultado trazagent_tool_validation_unavailablecomo bloqueante.POST /agents/{id}/tools/{toolId}/testroda uma ferramenta sozinha, ePOST /agents/{id}/tools/testfaz o mesmo com uma configuração ainda não salva. OtestModede cada tipo diz o que acontece:runchama a API de verdade (métodos que alteram dados exigem"confirmRealCall": true, senão422com o códigoagent_tool_test_real_call_not_confirmed),previewmostra o que a ferramenta faria sem executar, escenarionão roda sozinha (422com o códigoagent_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:
GET /agents/tools/mcp-sourceslista os servidores conectados com as ferramentas de cada um. Um servidor que não respondeu vem comunavailable: truee sem ferramentas.POST /agents/{id}/toolscom"type": "mcp_source"e, emconfig, o servidor emsource_ide as ferramentas permitidas emtools, ou"all_tools": truepara 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:
| Jeito | Como ligar | O que acontece |
|---|---|---|
| Contexto automático | knowledgeBaseIds e "ragEnabled": true | A cada mensagem do cliente, os trechos mais próximos das bases do agente entram no contexto da IA. |
| Ferramenta de busca | Uma ferramenta search_knowledge_base | A 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:
| Campo | Padrão | O que controla |
|---|---|---|
maxChunks | 5 | Quantos trechos entram no contexto. |
minScore | 0.3 | A nota mínima de similaridade de um trecho. |
maxChunksPerDoc | 3 | Quantos trechos de um mesmo documento entram. |
contextWindow | 1 | Quantos trechos vizinhos acompanham cada trecho encontrado. |
numCandidates | 10 | Quantos candidatos a busca considera antes de escolher. |
maxCharacters | 10000 | O 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ã" }
]
}| Regra | Código da recusa |
|---|---|
Nome com letras sem acento, dígitos e _, até 64 caracteres | agent_variable_name_invalid |
lead_name, lead_number e campaign_name são preenchidos pela plataforma e não podem ser declarados | agent_variable_name_reserved |
| Nomes sem repetir | agent_variable_duplicate |
| Até 50 variáveis | agent_variable_too_many |
- Uma variável sem
defaultValueé obrigatória: quem aciona o agente precisa preencher. ComdefaultValue, é 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, umdefaultValueincompatí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;historyaceita até 60 mensagens, comroleuserouassistant.lead_idtraz 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,toolCallse, emdebug, 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.mocksdá uma resposta simulada a uma ferramenta, peloiddela:{"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.
kind | Campos |
|---|---|
tool_called | toolId e, opcionalmente, arguments com match exact, subset ou regex. |
tool_not_called | toolId. |
tool_output_matches | toolId, path (por exemplo data.itens[0].id), match exact ou regex e value. |
reply_matches | match contains ou regex e value; confere a última resposta. |
reply_judged | rubric (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 é
422com o códigoagent_not_publishablee a lista emdetails.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 é
409com o códigoautomation_publish_switches_off, e os canais vêm emdetails.impact. Confira antes comGET /automation-needs/agent/{id}/publish-impacte confirme com?confirmSwitchOff=true.
| Rota | O que faz |
|---|---|
GET /agents/{id}/publication | A 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}/versions | As 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}/restore | Copia 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}/runslista as execuções, da mais recente para a mais antiga, com os filtrosfrom,to,source(conversation,simulator,scenarioouworkflow),status(ok,tool_failedoufailed),toolId,errorKind,entryIdehandledFailure. Um filtro inválido responde400com o códigoagent_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:
| Caminho | Rota |
|---|---|
| Atendimento receptivo de um número do WhatsApp oficial | PUT /whatsapp/business-phones/{id}/automation, com o agente em agentId. Vale para as conversas receptivas do número. |
| Delegação de uma conversa | PUT /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ções | Uma 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}/archivetira o agente deGET /agentssem perder a configuração; ele passa a aparecer emGET /agents/archived.PATCH /agents/{id}/unarchivedesfaz.DELETE /agents/{id}apaga o agente de vez.PATCH /agents/{id}/departmentmove 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
403com o códigoagent_forbidden.
Erros principais
| Status | code | Quando acontece |
|---|---|---|
400 | agent_name_required, agent_name_too_long | name vazio ou com mais de 120 caracteres. |
400 | agent_messaging_prompt_required | messagingPrompt vazio. |
400 | agent_messaging_model_too_long | messagingModel com mais de 64 caracteres. |
400 | sem code, campo em expected | provider, messagingModel ou internalTools ausente ou inválido. |
400 | agent_tools_moved, agent_mcp_collections_moved | internalTools no PUT /agents/{id}, ou mcpCollectionIds em qualquer corpo. |
400 | agent_tool_invalid | Tipo de ferramenta indisponível ou configuração inválida. |
400 | agent_variable_name_invalid, agent_variable_name_reserved, agent_variable_duplicate, agent_variable_too_many | Variável fora das regras. |
400 | agent_knowledge_base_no_access | Base de conhecimento de fora do workspace. |
400 | agent_department_required, agent_department_invalid | Departamento ausente para quem participa de mais de um, ou sem acesso. |
400 | agent_tool_type_unknown, agent_tool_name_invalid, agent_tool_description_required, agent_tool_order_mismatch | Ferramenta fora das regras. |
403 | agent_forbidden | Agente de outro workspace ou de um departamento sem acesso. |
404 | agent_not_found, agent_tool_not_found, agent_version_not_found, agent_scenario_not_found, agent_run_not_found | O recurso não existe neste agente. |
409 | agent_tool_name_taken, agent_tool_single_type_taken, agent_tool_target_taken, agent_tool_revision_conflict | Conflito com as ferramentas atuais. |
409 | automation_publish_switches_off | A publicação desligaria canais receptivos. |
422 | agent_not_publishable, agent_not_activatable | Problemas bloqueantes; a lista vem em details. |
422 | agent_tool_test_real_call_not_confirmed, agent_tool_test_unsupported | Teste de ferramenta sem confirmação ou de um tipo que só roda em cenário. |
400, 413 | agent_scenario_invalid, agent_scenario_too_long, agent_scenario_mock_too_large | Cenário fora das regras. |
503 | agent_tool_validation_unavailable | Uma 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
| Assunto | Rotas |
|---|---|
| Agente | Criar, listar, obter, atualizar, opções de modelos, arquivar, excluir |
| Ferramentas | Catálogo de tipos, listar, adicionar, substituir, conferir, testar, servidores MCP |
| Bases de conhecimento | Criar base, enviar arquivos, consultar, ligar ao agente |
| Variáveis | Variáveis iniciais, variáveis do agente, declarações do workspace |
| Teste | Simular, criar cenário, rodar cenários |
| Publicação | Publicar, estado, versões, restaurar |
| Execuções | Listar, obter |
| Atendimento | Automação do número, delegar conversa |
Os tipos de ferramenta, com a configuração e os campos de cada um, estão no Catálogo de ferramentas.