Agentes de IA

Um agente de IA é um assistente de várias etapas. Ele lê a conversa, planeja, chama ferramentas (suas ferramentas de IA, ferramentas MCP e uma busca na base de conhecimento), analisa os resultados e chama o modelo novamente até ter uma resposta. O nó Criar conclusão de chat com IA faz uma única chamada ao modelo e responde; o nó Agente de IA pode continuar trabalhando em várias chamadas de modelo e de ferramentas, dentro dos limites que você define, antes de responder.

Use um agente quando uma solicitação exigir várias etapas, por exemplo "encontrar o pedido do cliente, verificar o status da entrega e oferecer uma nova data". Para uma resposta direta a partir de instruções e de uma base de conhecimento, o nó de IA é mais simples e mais barato.

Os componentes

Parte	O que é	Onde configurar
Harness de IA	O mecanismo que executa o ciclo do agente: o próprio do MonoChat, um SDK de agentes ou um serviço de agentes hospedado.	Configurações › Automação › Harnesses de IA
Modelos	Os modelos de IA com que o agente raciocina: um modelo principal, um modelo alternativo opcional e um modelo rápido opcional. Harnesses hospedados usam os modelos do próprio provedor.	O nó Agente de IA
Ferramentas	Escopos de IA, funções do tipo Ferramenta de IA e ferramentas MCP.	O nó Agente de IA
Orçamento de execução	Limites de chamadas ao modelo, chamadas de ferramentas, tokens, duração e novas tentativas para cada execução.	O nó Agente de IA
Execução	Uma execução do agente. Toda execução é registrada em Execuções do agente de IA.	Criada pelo nó ou pela API

Harnesses de IA

Configurações › Automação › Harnesses de IA lista os harnesses em que seus agentes podem ser executados: os que o MonoChat oferece a todos os workspaces e os que você adiciona com suas próprias credenciais.

Harness	Onde é executado	Modelos que usa	Quem adiciona
MonoChat Native	Dentro do MonoChat	Seus modelos de IA	MonoChat
OpenAI Agents SDK	Dentro do MonoChat	Seus modelos de IA	MonoChat
Claude Agent SDK	No executor de agentes do MonoChat	Seus modelos de IA	MonoChat
pi	No executor de agentes do MonoChat	Seus modelos de IA	MonoChat
OpenAI Agents API	Na nuvem da OpenAI	Os modelos permitidos do harness	Você, com sua chave de API da OpenAI (o MonoChat também pode oferecer uma)
Claude Managed Agents	Na nuvem da Anthropic	Os modelos permitidos do harness	Você, com sua chave de API da Anthropic (o MonoChat também pode oferecer uma)
Endpoint personalizado	No seu próprio servidor	Seus modelos de IA (opcional)	Você, com seu endpoint e segredo

Os harnesses executados no MonoChat são oferecidos pelo MonoChat; seu workspace só pode adicionar harnesses que usam credenciais próprias. Claude Agent SDK e pi precisam do executor de agentes do MonoChat: onde ele não estiver configurado, uma execução neles falha com "Este harness não está disponível neste servidor."

Seja qual for o harness, o MonoChat mantém o controle: toda chamada de modelo de um harness que usa seus modelos de IA passa pelo MonoChat (portanto o faturamento e o orçamento se aplicam), toda chamada de ferramenta executa suas funções, ferramentas MCP e escopos de IA no seu workspace, e o orçamento é aplicado em todos os harnesses.

Adicionar um harness

1. Acesse Configurações › Automação › Harnesses de IA e clique em + (Criar).
2. Informe um Nome e, se quiser, uma Descrição.
3. Escolha o Harness. Cada opção indica onde é executada.
4. Em Credenciais, informe o que o harness precisa:
   • OpenAI Agents API, Claude Managed Agents: Chave de API.
   • Endpoint personalizado: Endpoint e Chave de API.
5. Para um harness hospedado, preencha Modelos permitidos: informe os nomes dos modelos do provedor (por exemplo, o ID do modelo da OpenAI ou da Anthropic). Use Adicionar modelo para até 10 modelos. Os agentes desse harness só podem escolher nesta lista.
6. Clique em Salvar.

Ao editar um harness, o tipo de Harness não pode ser alterado, e o campo da chave exibe Chave de API (deixe vazio para manter a chave salva).

Claude Managed Agents

Na primeira vez que um harness desse tipo é usado, o MonoChat cria um agente e um ambiente nessa conta da Anthropic e os reutiliza depois.

Endpoint personalizado

Um harness de Endpoint personalizado envia as execuções ao seu próprio serviço, por exemplo um agente hospedado por você. Para cada execução, o MonoChat envia um POST para <Endpoint>/runs com Authorization: Bearer <API Key>. O corpo contém o ID da execução, as instruções, a entrada, as mensagens da conversa, o orçamento, os aliases de modelo (agent-main, agent-fallback, agent-fast) e três URLs com um token para esta execução:

• um gateway de modelos (URLs base compatíveis com OpenAI …/v1 e com Anthropic) que chama os modelos de IA do nó e aplica o orçamento,
• um servidor MCP que expõe as ferramentas da execução,
• uma URL de eventos em que seu serviço informa o resultado (completed com result, ou failed com error).

O token da execução deixa de funcionar quando ela termina.

O nó Agente de IA

Adicione um agente a um fluxo com o nó Agente de IA, entre os nós híbridos no designer de fluxos. Veja Fluxos para saber como adicionar e conectar nós.

Campos

Seção	Campo	Descrição
	Nome	O nome do nó exibido no canvas.
	Harness de IA	Obrigatório. O harness que executa o agente.
	Instruções	As instruções de sistema do agente: seu papel, tom, regras e o que ele pode ou não fazer.
	Tarefa (adicionada às instruções do agente; é possível usar tags)	O que este nó pede ao agente. É adicionada depois das instruções e pode usar as mesmas tags do prompt do nó de IA, por exemplo para incluir dados do cliente.
Modelos	Modelo principal	O modelo que o agente usa. Obrigatório para todos os harnesses, exceto Endpoint personalizado.
	Modelo alternativo (após o limite flexível)	O modelo para o qual o agente muda ao atingir o limite flexível de chamadas ao modelo, normalmente um modelo mais barato ou mais rápido.
	Modelo rápido (tarefas leves em segundo plano)	Um modelo que um harness pode usar para suas chamadas leves em segundo plano.
	Modelo (um dos modelos permitidos do harness)	Exibido no lugar dos três campos acima para um harness hospedado.
Conversa do agente	Conversa	Continuar a sessão de agente existente (padrão) ou Iniciar uma nova sessão de agente. Veja Sessões de agente.
	Chave da tarefa (conversas de agente separadas por tarefa)	Opcional. Mantém uma sessão de agente separada por chave na mesma conversa, por exemplo booking e support.
	Limite do histórico de mensagens	Quantas mensagens da conversa o agente recebe.
	Modelos de IA de fala para texto	Um modelo com Transcrição. As mensagens de voz da conversa chegam ao agente como texto.
Configurações das ferramentas	Escopos de IA	Bases de conhecimento que o agente pode pesquisar. Elas são oferecidas ao agente como uma ferramenta de busca na base de conhecimento.
	Ferramenta de IA	Funções do tipo Ferramenta de IA que o agente pode chamar.
	Definir ferramentas de conteúdo do cliente MCP de IA	Abre o painel em que você adiciona ferramentas MCP. Veja Clientes MCP.
Mensagens	Encaminhar mensagens intermediárias ao cliente	Desativado por padrão. Quando ativado, o que o agente escreve enquanto ainda trabalha (por exemplo, "Vou verificar seu pedido") é enviado ao cliente; quando desativado, é adicionado à conversa como uma mensagem de sussurro que só a sua equipe vê.
	Enviar resposta	Ativado por padrão. Envia a resposta final do agente ao cliente. Desative para usar a resposta apenas dentro do fluxo.
Orçamento de execução	Máx. de chamadas ao modelo	Padrão 4.
	Limite flexível: chamadas ao modelo	Opcional. Depois deste número de chamadas ao modelo, o agente muda para o modelo alternativo. Deve ser menor que Máx. de chamadas ao modelo e exige um modelo alternativo.
	Máx. de chamadas de ferramentas	Padrão 6. Com 0, a execução termina como Orçamento excedido assim que o agente tenta chamar uma ferramenta.
	Máx. total de tokens	Padrão 20000. Tokens de entrada e de saída de todas as chamadas ao modelo na execução.
	Duração máx. (segundos)	Padrão 30.
	Máx. de tentativas	Padrão 2. Quantas vezes uma chamada de modelo com falha é repetida.

dica

Escreva as regras estáveis em Instruções e o trabalho específico desta etapa em Tarefa. Assim, vários nós Agente de IA em um fluxo podem compartilhar as mesmas instruções e diferir apenas na tarefa.

aviso

Harnesses hospedados não oferecem suporte a limite flexível, pois não podem mudar para um modelo alternativo. Deixe Limite flexível: chamadas ao modelo vazio para eles.

O que acontece quando o fluxo chega ao nó

1. O MonoChat verifica seu saldo e as configurações do nó e inicia uma execução. A execução fica Na fila e depois Em execução. A instância do fluxo aguarda no nó.
2. O agente recebe as instruções e a tarefa e, quando o fluxo pertence a uma conversa, as mensagens da conversa até o Limite do histórico de mensagens, com as mensagens de voz transcritas.
3. O agente chama modelos e ferramentas até ter uma resposta ou atingir um limite. O texto que ele escreve entre as chamadas de ferramentas é tratado como mensagem intermediária.
4. Quando a execução termina:
   • se ela foi Concluída e Enviar resposta está ativado, a resposta é enviada ao cliente. Respostas longas são divididas em várias mensagens quando excedem o limite do canal (4096 caracteres no WhatsApp);
   • se terminou de outra forma, uma mensagem de sussurro "Execução do agente de IA encerrada: status. erro" é adicionada à conversa para a sua equipe.
5. O fluxo continua pela saída que corresponde à forma como a execução terminou.

As execuções da mesma sessão de agente são processadas uma por vez, em ordem.

Saídas

Saída	Quando
Concluído	O agente terminou com uma resposta.
Orçamento excedido	A execução esgotou Máx. de chamadas ao modelo, Máx. de chamadas de ferramentas ou Máx. total de tokens.
Tempo esgotado	A execução atingiu Duração máx. (segundos).
Ódio, Jailbreak, Automutilação, Sexual, Violência	O filtro de conteúdo do provedor do modelo interrompeu a execução por esta categoria. São as mesmas saídas que o nó de IA tem.
Em caso de falha	A execução falhou por qualquer outro motivo ou foi cancelada. Uma interrupção pelo filtro de conteúdo também vem para cá em nós salvos antes de essas saídas existirem; abra e salve esse nó para obtê-las.

Conecte pelo menos Concluído e Em caso de falha. Um padrão comum é enviar Orçamento excedido, Tempo esgotado e Em caso de falha para um nó Atribuir conversa, para que um colega assuma o atendimento.

Sessões de agente

Uma sessão de agente é a memória do agente entre execuções. O MonoChat mantém uma sessão de agente ativa por conversa, harness e chave de tarefa.

• Continuar a sessão de agente existente a reutiliza, de modo que o agente retoma de onde parou. Em harnesses hospedados, a sessão do próprio provedor também continua.
• Iniciar uma nova sessão de agente encerra a ativa e começa do zero, por exemplo no início de um novo assunto.
• Uma Chave da tarefa mantém sessões independentes lado a lado na mesma conversa.

Faturamento

• As chamadas em modelos de IA fornecidos pelo MonoChat são cobradas do seu saldo como de costume. As chamadas em seus próprios modelos são cobradas pelo seu provedor.
• Um harness fornecido pelo MonoChat pode acrescentar tarifas próprias por execução, por minuto e por chamada de ferramenta e, para um harness hospedado, os tokens informados pelo provedor. Elas aparecem em Transações como Execução do agente de IA, Duração do agente de IA, Chamada de ferramenta do agente de IA e categorias de tokens de IA.
• Um harness que você adiciona com suas próprias credenciais não tem tarifa do MonoChat; seu provedor cobra de você.
• Uma execução não é iniciada quando seu saldo é insuficiente.

Evento Execução do agente de IA concluída

Execução do agente de IA concluída é um nó de evento. Ele é acionado quando uma execução ligada a um cliente termina, seja iniciada por um fluxo ou pela API com uma conversa. Como outros nós de evento, tem as configurações opcionais Condição e Tempo esgotado. Use-o para iniciar um fluxo separado após as execuções de agentes, por exemplo para registrar resultados ou avisar uma equipe.

Iniciar um agente por código

Funções personalizadas e clientes de API podem executar agentes com estes métodos (permissão Iniciar / Ler / Cancelar execuções de agentes de IA na automação):

Método	O que faz
business.tenants.automation.ai.aiAgentRuns.create	Inicia uma execução. Retorna aiAgentRunId e aiAgentSessionId.
business.tenants.automation.ai.aiAgentRuns.show	Retorna uma execução (_id) com seu status, uso, etapas e resultado.
business.tenants.automation.ai.aiAgentRuns.cancel	Cancela uma execução na fila ou em andamento (_id).

create recebe aiHarnessClientId, input (a tarefa), opcionalmente sessionId (para trabalhar em uma conversa), aiAgentSessionId, taskKey e isNewSession, e options com as mesmas configurações do nó: instructions, aiModelClientId, fallbackAiModelClientId, fastAiModelClientId, harnessModel, toolCustomFunctionIds, aiScopeIds, aiMcpClientDatas, messageHistoryLimit, speechToTextAiModelClientId, forwardIntermediateMessages, willSendAnswer e um budget obrigatório. Pela API, forwardIntermediateMessages e willSendAnswer têm false como padrão.

const { aiAgentRunId } = await sdk.method({ name: 'business.tenants.automation.ai.aiAgentRuns.create' }).callAsync({
  payload: {
    aiHarnessClientId: 'HARNESS_ID',
    input: 'Summarise the open orders of this customer.',
    sessionId: 'SESSION_ID',
    options: {
      instructions: 'You are the order assistant of our store.',
      aiModelClientId: 'MODEL_ID',
      toolCustomFunctionIds: ['FUNCTION_ID'],
      budget: { maxLlmCalls: 4, maxToolCalls: 6, maxTotalTokens: 20000, maxDurationSeconds: 30, maxRetries: 2 },
    },
  },
})

A execução é assíncrona: leia-a depois com show ou reaja a ela com o evento Execução do agente de IA concluída. Sem sessionId, cada chamada inicia uma nova sessão de agente, a menos que você informe o aiAgentSessionId retornado por uma chamada anterior; o agente então vê as execuções concluídas anteriores dessa sessão de agente como histórico. Veja Method para chamar métodos a partir de uma função.

Permissões

Permissão	Permite
Ler / Criar / Atualizar / Excluir harnesses de IA na automação	Gerenciar Harnesses de IA
Ler execuções de agentes de IA na automação	Ver Execuções do agente de IA
Iniciar execuções de agentes de IA na automação	Chamar aiAgentRuns.create
Cancelar execuções de agentes de IA na automação	Chamar aiAgentRuns.cancel

Veja Perfis de acesso.

Relacionados

• Execuções do agente de IA: veja o que cada execução fez
• Modelos de IA
• Clientes MCP
• Escopos de IA
• Fluxos