Agentes de IA

create_agent

Escrita

Cria um agente de IA. Ele nasce DESLIGADO: teste com test_agent e os casos de teste, e ligue com update_agent (isActive: true), que passa pela aprovação. Respeita o limite de agentes do plano.

Permissão

agents:write

Operação

agents.create

Parâmetros

namestringobrigatório

descriptionstringopcional

systemPromptstringopcional

Instruções do agente (até 4.000 caracteres). null = usa o prompt da empresa.

providerstringopcional

modelstringopcional

Um value de list_ai_models (null = o da empresa).

temperaturenumberopcional

voiceTonestringopcional

Tom de voz.

senderNamestringopcional

Nome com que assina as mensagens.

knowledgeBaseIdstringopcional

Base de conhecimento própria (null = todas as bases da empresa).

enabledModulesstring[]opcional

Módulos (ferramentas) que o agente usa; null = os da empresa.

teamstringopcional

SUPPORTSALESMARKETINGMANAGEMENT

rolestringopcional

reception, support, sdr, closer, account_manager, strategist, copywriter, traffic, analyst, manager ou custom.

roleLabelstringopcional

Nome do papel quando custom.

create_agent_test_case

Escrita

Cria um caso de teste: messages (a última é do cliente e é a avaliada) e expectations — mustInclude, mustNotInclude, expectedTool, expectHandoff ou rubric (critério em texto que outra IA confere). Pelo menos uma expectativa.

Permissão

agents:write

Operação

agents.evals.cases.create

Parâmetros

namestringobrigatório

inputobjectobrigatório

input.messagesobject[]obrigatório

expectationsobjectobrigatório

expectations.mustIncludestring[]opcional

expectations.mustNotIncludestring[]opcional

expectations.expectedToolstringopcional

expectations.expectHandoffbooleanopcional

expectations.rubricstringopcional

isActivebooleanopcional

agentIdstringobrigatório

delete_agent_test_case

Escrita

Apaga um caso de teste.

Permissão

agents:write

Operação

agents.evals.cases.delete

Parâmetros

agentIdstringobrigatório

caseIdstringobrigatório

get_agent

Leitura

Um agente de IA completo: prompt (instruções), modelo, temperatura, tom, nome que assina, base de conhecimento, módulos, time/papel, roteamento por especialidade e a versão do prompt em uso. null nos campos = herda da empresa.

Permissão

agents:read

Operação

agents.get

Parâmetros

agentIdstringobrigatório

get_agent_ai_budget

Leitura

Créditos de IA usados no mês por cada agente e por time, com os tetos definidos (null = sem teto). Ao atingir o teto, as conversas do agente ou do time passam para a equipe e as tarefas autônomas param.

Permissão

agents:read

Operação

agents.budget

Parâmetros

Sem parâmetros.

get_agent_performance

Leitura

Desempenho dos agentes de IA no período (mês, trimestre ou ano corrente): conversas, resolvidas sem humano, agendamentos, negócios criados e ganhos, receita e tarefas autônomas, com as metas e o progresso. Sem agentId, traz todos os agentes por time.

Permissão

agents:read

Operação

agents.performance

Parâmetros

agentIdstringopcional

periodstringopcional

MONTHLYQUARTERLYYEARLY

get_agent_test_run

Leitura

Resultado de uma execução: cada caso com a resposta do agente, se passou e por quê, e a comparação com a execução anterior (o que passou a falhar ou a passar).

Permissão

agents:read

Operação

agents.evals.runs.get

Parâmetros

agentIdstringobrigatório

runIdstringobrigatório

get_conversation_ai_turns

Leitura

Por que a IA respondeu assim numa conversa (últimos 30 dias): em cada resposta, o que buscou na base (com a nota de cada trecho), as ferramentas que usou e o resultado, o modelo, o custo e o tempo. Os mais recentes primeiro.

Permissão

agents:read

Operação

agents.turns

Parâmetros

conversationIdstringobrigatório

limitintegeropcional

list_agent_prompt_versions

Leitura

Histórico do prompt do agente: cada versão salva, quando, por quem e qual está em uso. Com version, traz o texto completo daquela versão (para comparar ou restaurar).

Permissão

agents:read

Operação

agents.prompt_versions

Parâmetros

agentIdstringobrigatório

versionintegeropcional

list_agent_test_cases

Leitura

Casos de teste do agente: a mensagem (ou pequena conversa) do cliente e o que se espera da resposta (frases obrigatórias/proibidas, ferramenta, passar para humano, critério livre), mais o limite de casos do plano.

Permissão

agents:read

Operação

agents.evals.cases.list

Parâmetros

agentIdstringobrigatório

list_agent_test_runs

Leitura

Execuções da suíte de testes do agente: situação, quantos passaram/falharam, nota e a versão do prompt testada.

Permissão

agents:read

Operação

agents.evals.runs.list

Parâmetros

agentIdstringobrigatório

limitintegeropcional

list_agents

Leitura

Agentes de IA da empresa: nome, descrição, time (SUPPORT, SALES, MARKETING, MANAGEMENT), papel, se está ativo, modelo e os módulos que ele usa.

Permissão

agents:read

Operação

agents.list

Parâmetros

Sem parâmetros.

list_ai_models

Leitura

Modelos de IA que um agente pode usar: provedor, value (o que vai em update_agent), faixa (rápido, equilibrado, avançado) e custo relativo ao mais barato.

Permissão

agents:read

Operação

agents.models

Parâmetros

Sem parâmetros.

restore_agent_prompt_version

EscritaPede aprovação

Volta o prompt do agente para uma versão anterior do histórico (desfaz uma mudança). Vindo de chave de API, vai para Aprovações.

Permissão

agents:write

Operação

agents.prompt_versions.restore

As que pedem aprovação não executam na hora: viram um pedido em Para revisar e na aba Aprovações de IA.

Parâmetros

agentIdstringobrigatório

versionintegerobrigatório

run_agent_tests

Escrita

Roda todos os casos de teste ativos do agente com o prompt atual, em segundo plano (gasta créditos de IA). Acompanhe com get_agent_test_run, que compara com a execução anterior.

Permissão

agents:write

Operação

agents.evals.run

Parâmetros

agentIdstringobrigatório

test_agent

Escrita

Conversa de teste com um agente (o playground): o mesmo caminho da produção — prompt, base, módulos e modelo do agente — com cliente fictício e ferramentas de escrita simuladas (nada sai para cliente nem grava dado). Devolve a resposta, o que buscou na base, as ferramentas que chamaria, se passaria para humano e o custo. Para continuar a conversa, mande o sessionId de volta. Gasta créditos de IA.

Permissão

agents:write

Operação

agents.test

Parâmetros

agentIdstringopcional

Sem agentId, testa o agente padrão.

messagestringobrigatório

sessionIdstringopcional

historyobject[]opcional

Conversa anterior fixa (só numa sessão nova).

history[].rolestringobrigatório

userassistant

history[].contentstringobrigatório

update_agent

EscritaPede aprovação

Altera um agente: prompt, modelo, temperatura, tom, nome que assina, base, módulos, time/papel, ligar/desligar (isActive) ou torná-lo o padrão (isDefault: true). Muda o atendimento real, então vindo de chave de API vai para Aprovações. O prompt anterior fica no histórico.

Permissão

agents:write

Operação

agents.update

As que pedem aprovação não executam na hora: viram um pedido em Para revisar e na aba Aprovações de IA.

Parâmetros

agentIdstringobrigatório

namestringopcional

descriptionstringopcional

systemPromptstringopcional

Instruções do agente (até 4.000 caracteres). null = usa o prompt da empresa.

providerstringopcional

modelstringopcional

Um value de list_ai_models (null = o da empresa).

temperaturenumberopcional

voiceTonestringopcional

Tom de voz.

senderNamestringopcional

Nome com que assina as mensagens.

knowledgeBaseIdstringopcional

Base de conhecimento própria (null = todas as bases da empresa).

enabledModulesstring[]opcional

Módulos (ferramentas) que o agente usa; null = os da empresa.

teamstringopcional

SUPPORTSALESMARKETINGMANAGEMENT

rolestringopcional

reception, support, sdr, closer, account_manager, strategist, copywriter, traffic, analyst, manager ou custom.

roleLabelstringopcional

Nome do papel quando custom.

isActivebooleanopcional

isDefaultbooleanopcional

Vira o agente padrão da empresa (o anterior deixa de ser).

update_agent_routing

EscritaPede aprovação

Roteamento por especialidade: em que assuntos este agente é especialista (com exemplos de mensagens), se assume a conversa sozinho, a confiança mínima e para quais agentes pode passar a conversa. Vindo de chave de API, vai para Aprovações.

Permissão

agents:write

Operação

agents.routing.update

As que pedem aprovação não executam na hora: viram um pedido em Para revisar e na aba Aprovações de IA.

Parâmetros

agentIdstringobrigatório

enabledbooleanobrigatório

Liga o roteamento por especialidade deste agente.

specialtiesstring[]obrigatório

examplesstring[]obrigatório

Mensagens de cliente que devem cair neste agente.

autoAcceptbooleanobrigatório

Assume a conversa sozinho quando tiver confiança.

minimumConfidencenumberopcional

minimumConfidenceMarginnumberopcional

fallbackAgentIdstringopcional

allowedHandoffAgentIdsstring[]opcional

update_agent_test_case

Escrita

Edita um caso de teste (nome, mensagens, expectativas ou ligar/desligar).

Permissão

agents:write

Operação

agents.evals.cases.update

Parâmetros

agentIdstringobrigatório

caseIdstringobrigatório

namestringopcional

inputobjectopcional

input.messagesobject[]obrigatório

expectationsobjectopcional

expectations.mustIncludestring[]opcional

expectations.mustNotIncludestring[]opcional

expectations.expectedToolstringopcional

expectations.expectHandoffbooleanopcional

expectations.rubricstringopcional

isActivebooleanopcional