AI agents

create_agent

Write

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.

Permission

agents:write

Operation

agents.create

Parameters

namestringrequired

descriptionstringoptional

systemPromptstringoptional

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

providerstringoptional

modelstringoptional

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

temperaturenumberoptional

voiceTonestringoptional

Tom de voz.

senderNamestringoptional

Nome com que assina as mensagens.

knowledgeBaseIdstringoptional

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

enabledModulesstring[]optional

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

teamstringoptional

SUPPORTSALESMARKETINGMANAGEMENT

rolestringoptional

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

roleLabelstringoptional

Nome do papel quando custom.

create_agent_test_case

Write

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.

Permission

agents:write

Operation

agents.evals.cases.create

Parameters

namestringrequired

inputobjectrequired

input.messagesobject[]required

expectationsobjectrequired

expectations.mustIncludestring[]optional

expectations.mustNotIncludestring[]optional

expectations.expectedToolstringoptional

expectations.expectHandoffbooleanoptional

expectations.rubricstringoptional

isActivebooleanoptional

agentIdstringrequired

delete_agent_test_case

Write

Apaga um caso de teste.

Permission

agents:write

Operation

agents.evals.cases.delete

Parameters

agentIdstringrequired

caseIdstringrequired

get_agent

Read

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.

Permission

agents:read

Operation

agents.get

Parameters

agentIdstringrequired

get_agent_ai_budget

Read

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.

Permission

agents:read

Operation

agents.budget

Parameters

No parameters.

get_agent_performance

Read

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.

Permission

agents:read

Operation

agents.performance

Parameters

agentIdstringoptional

periodstringoptional

MONTHLYQUARTERLYYEARLY

get_agent_test_run

Read

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).

Permission

agents:read

Operation

agents.evals.runs.get

Parameters

agentIdstringrequired

runIdstringrequired

get_conversation_ai_turns

Read

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.

Permission

agents:read

Operation

agents.turns

Parameters

conversationIdstringrequired

limitintegeroptional

list_agent_prompt_versions

Read

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).

Permission

agents:read

Operation

agents.prompt_versions

Parameters

agentIdstringrequired

versionintegeroptional

list_agent_test_cases

Read

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.

Permission

agents:read

Operation

agents.evals.cases.list

Parameters

agentIdstringrequired

list_agent_test_runs

Read

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

Permission

agents:read

Operation

agents.evals.runs.list

Parameters

agentIdstringrequired

limitintegeroptional

list_agents

Read

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.

Permission

agents:read

Operation

agents.list

Parameters

No parameters.

list_ai_models

Read

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.

Permission

agents:read

Operation

agents.models

Parameters

No parameters.

restore_agent_prompt_version

WriteNeeds approval

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.

Permission

agents:write

Operation

agents.prompt_versions.restore

Tools that wait for approval don't run right away: they become a request in To review and in the AI approvals tab.

Parameters

agentIdstringrequired

versionintegerrequired

run_agent_tests

Write

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.

Permission

agents:write

Operation

agents.evals.run

Parameters

agentIdstringrequired

test_agent

Write

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.

Permission

agents:write

Operation

agents.test

Parameters

agentIdstringoptional

Sem agentId, testa o agente padrão.

messagestringrequired

sessionIdstringoptional

historyobject[]optional

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

history[].rolestringrequired

userassistant

history[].contentstringrequired

update_agent

WriteNeeds approval

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.

Permission

agents:write

Operation

agents.update

Tools that wait for approval don't run right away: they become a request in To review and in the AI approvals tab.

Parameters

agentIdstringrequired

namestringoptional

descriptionstringoptional

systemPromptstringoptional

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

providerstringoptional

modelstringoptional

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

temperaturenumberoptional

voiceTonestringoptional

Tom de voz.

senderNamestringoptional

Nome com que assina as mensagens.

knowledgeBaseIdstringoptional

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

enabledModulesstring[]optional

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

teamstringoptional

SUPPORTSALESMARKETINGMANAGEMENT

rolestringoptional

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

roleLabelstringoptional

Nome do papel quando custom.

isActivebooleanoptional

isDefaultbooleanoptional

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

update_agent_routing

WriteNeeds approval

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.

Permission

agents:write

Operation

agents.routing.update

Tools that wait for approval don't run right away: they become a request in To review and in the AI approvals tab.

Parameters

agentIdstringrequired

enabledbooleanrequired

Liga o roteamento por especialidade deste agente.

specialtiesstring[]required

examplesstring[]required

Mensagens de cliente que devem cair neste agente.

autoAcceptbooleanrequired

Assume a conversa sozinho quando tiver confiança.

minimumConfidencenumberoptional

minimumConfidenceMarginnumberoptional

fallbackAgentIdstringoptional

allowedHandoffAgentIdsstring[]optional

update_agent_test_case

Write

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

Permission

agents:write

Operation

agents.evals.cases.update

Parameters

agentIdstringrequired

caseIdstringrequired

namestringoptional

inputobjectoptional

input.messagesobject[]required

expectationsobjectoptional

expectations.mustIncludestring[]optional

expectations.mustNotIncludestring[]optional

expectations.expectedToolstringoptional

expectations.expectHandoffbooleanoptional

expectations.rubricstringoptional

isActivebooleanoptional