AI Agent

1. Visão Geral

O componente AI Agent (ai-agent) executa um agente de inteligência artificial dentro do fluxo, capaz de raciocinar sobre uma ou mais tarefas, decidir o que fazer e, se necessário, usar outros componentes da plataforma como "ferramentas" durante a execução. É indicado quando o fluxo precisa de uma etapa que interprete linguagem natural, tome decisões mais flexíveis ou combine várias sub-tarefas com apoio de um modelo de linguagem (LLM).

Use quando a lógica não pode ser resolvida apenas com regras fixas (Choice, ForEach etc.) e se beneficia da flexibilidade de um modelo de IA — por exemplo, interpretar um pedido em texto livre, resumir documentos, ou orquestrar múltiplas sub-tarefas que dependem de contexto. Não use para lógica determinística simples, onde componentes tradicionais são mais previsíveis, mais baratos e mais rápidos.

Suporta qualquer modelo de linguagem compatível com a URL configurada (permite apontar para provedores customizados/compatíveis, através do campo modelUrl), além do modelo padrão do provedor.

2. Pré-requisitos

Uma chave de API (apiKey) válida para o provedor do modelo de IA escolhido.
Conhecimento do identificador exato do modelo a ser usado (model).
Se for usado um provedor customizado ou compatível (não o padrão), é necessário saber a URL base desse serviço (modelUrl).
Ao menos uma tarefa (tasks) definida com nome, descrição e instrução.

3. Autenticação e Conexão

Campo	Obrigatório	Tipo	Descrição	Exemplo
`apiKey`	Sim	Expressão	Chave de autenticação usada para acessar o modelo de IA.	Uma expressão que busca a chave em uma variável segura
`model`	Sim	Texto	Identificador do modelo de IA a ser usado.	`"gpt-4o"`
`modelUrl`	Não	Texto	URL base customizada do provedor do modelo, usada quando não se está usando o endpoint padrão (por exemplo, um provedor compatível auto-hospedado). Se não informado, usa o padrão do provedor do modelo.	`"https://meu-provedor.exemplo.com/v1"`

4. Configuração / Operações Suportadas

O AI Agent tem uma única operação: executar o agente com um prompt de entrada e devolver a resposta gerada.

Configuração do agente (definida uma vez, ao iniciar o fluxo)

Campo	Obrigatório	Tipo	Descrição	Exemplo
`name`	Sim	Texto	Nome do agente.	`"AgenteAtendimento"`
`description`	Sim	Texto	Descrição do papel do agente, usada internamente para orientar o comportamento dele.	`"Agente responsável por atender dúvidas de clientes"`
`taskOrchestration`	Sim	Texto: `SEQUENTIAL`, `PARALLEL`, `LOOP` ou `DYNAMIC`	Define como as tarefas configuradas serão executadas: em sequência, em paralelo, em loop, ou de forma dinâmica (o próprio agente decide a ordem e delega as tarefas). Valor não reconhecido cai automaticamente em `SEQUENTIAL`.	`"DYNAMIC"`
`tasks`	Sim	Lista de objetos	Lista de tarefas que o agente pode executar (ver tabela abaixo). Não pode ser vazia.	Ver exemplo prático
`instructionPlanTasks`	Não	Texto	Instruções adicionais sobre como coordenar as tarefas, usadas apenas no modo `DYNAMIC`. Valor padrão: vazio.	`"Priorize tarefas relacionadas a pagamentos"`
`temperature`	Não	Texto (número decimal)	Controla a criatividade/aleatoriedade das respostas do modelo. Valor padrão: `"0.7"`. Quanto mais próximo de 0, mais determinístico; quanto mais próximo de 1, mais criativo.	`"0.3"`
`memoryType`	Não	Texto: `NO_MEMORY` ou `IN_LOCAL_MEMORY`	Define se o agente lembra de conversas anteriores do mesmo usuário. `NO_MEMORY` (padrão): cada execução é isolada. `IN_LOCAL_MEMORY`: mantém histórico em memória durante a sessão.	`"IN_LOCAL_MEMORY"`
`sessionTimeoutMinutes`	Não	Texto (número)	Tempo, em minutos, que uma sessão de memória permanece ativa sem uso. Valor padrão: `"30"`.	`"60"`
`maxMessages`	Não	Texto (número)	Número máximo de mensagens mantidas no histórico da sessão. Valor padrão: `"0"` (sem limite definido no exemplo padrão).	`"20"`
`maxOutputTokens`	Não	Texto (número)	Limite de tamanho da resposta gerada pelo modelo, em tokens. Valor padrão: `"4192"`.	`"2000"`
`returnTokens`	Não	Texto ("true"/"false")	Se `true`, inclui informações de consumo de tokens no monitoramento da execução. Valor padrão: `"false"`.	`"true"`

Cada item da lista `tasks`

Campo	Obrigatório	Tipo	Descrição	Exemplo
`name`	Sim	Texto	Nome da tarefa (no modo `DYNAMIC`, corresponde ao nome do agente que a executa).	`"resumirDocumento"`
`description`	Sim	Texto	Descrição do que a tarefa faz.	`"Resume o conteúdo de um documento"`
`instruction`	Sim	Texto	Instrução detalhada de como a tarefa deve ser executada (o "prompt" da tarefa).	`"Leia o texto enviado e produza um resumo de até 5 linhas"`
`outputKey`	Não	Texto	Nome da chave onde o resultado dessa tarefa é guardado, para ser referenciado por outras tarefas.	`"resumo"`
`componentTools`	Não	Lista de objetos	Componentes da plataforma que o agente pode usar como ferramentas durante essa tarefa. Cada item define uma descrição do componente, uma descrição do corpo esperado, e a configuração do componente em si.	Um componente de busca em banco de dados disponibilizado como ferramenta

Entrada de execução (a cada chamada do agente durante o fluxo)

Campo	Obrigatório	Tipo	Descrição	Exemplo
`prompt`	Sim	Expressão	Texto/pergunta enviado ao agente nesta execução.	`"Qual o status do pedido 123?"`
`userId`	Não	Expressão	Identificador do usuário, usado para manter memória por usuário quando `memoryType` está ativado. Se não informado, usa o nome do passo como identificador.	`"cliente-456"`
`files`	Não	Expressão (JSON)	Lista de arquivos a enviar junto com o prompt (por exemplo, para tarefas multimodais). Cada item precisa ter `name` (nome da propriedade na mensagem onde o arquivo está) e `mimeType` (tipo do arquivo).	`[{"name": "comprovante", "mimeType": "application/pdf"}]`

Comportamento em caso de erro: se algum campo obrigatório não for informado (nome, modelo, chave de API, descrição, orquestração, tarefas), o fluxo falha já ao iniciar, antes de processar qualquer execução. Se prompt não for informado numa execução, essa execução falha. Se um arquivo referenciado em files não existir na mensagem, a execução falha.

5. Exemplos Práticos

Exemplo simples: um agente único, com orquestração SEQUENTIAL e uma só tarefa chamada "responderDuvida", configurado para responder perguntas de clientes em texto livre. A cada execução, o fluxo envia o texto da pergunta do cliente no campo prompt e recebe a resposta gerada pelo agente.

Configuração do componente (definida uma vez, ao iniciar o fluxo):

{
  "componentName": "ai-agent",
  "configurations": {
    "name": "AgenteAtendimento",
    "model": "gpt-4o",
    "apiKey": "{$.secrets.openaiApiKey}",
    "description": "Agente responsável por atender dúvidas de clientes",
    "taskOrchestration": "SEQUENTIAL",
    "tasks": [
      {
        "name": "responderDuvida",
        "description": "Responde dúvidas gerais de clientes",
        "instruction": "Responda de forma clara e educada à pergunta do cliente"
      }
    ]
  }
}

Entrada (a cada execução, dentro do fluxo):

{
  "pergunta": "Qual o prazo de entrega para o CEP 01310-000?"
}

Nessa execução, o campo prompt do componente é configurado apontando para o texto da pergunta:

{
  "prompt": "{$.body.pergunta}"
}

Resposta:

{
  "pergunta": "Qual o prazo de entrega para o CEP 01310-000?",
  "response": "O prazo estimado de entrega para esse CEP é de 3 a 5 dias úteis."
}

Exemplo avançado: um agente com orquestração DYNAMIC e três tarefas ("consultarPedido", "consultarEstoque", "gerarResposta"), cada uma com sua própria instrução. A tarefa "consultarPedido" tem uma ferramenta configurada em componentTools que aponta para um componente de consulta a um sistema interno. O agente recebe um prompt em linguagem natural (por exemplo, "meu pedido 123 vai chegar quando?"), decide sozinho quais tarefas executar e em que ordem, usando a ferramenta configurada quando necessário, e devolve a resposta final consolidada. Nesse cenário, também é enviado um arquivo (files) com o comprovante de compra do cliente, para o agente considerar na análise.

Configuração do componente:

{
  "componentName": "ai-agent",
  "configurations": {
    "name": "AgenteSuporte",
    "model": "gpt-4o",
    "apiKey": "{$.secrets.openaiApiKey}",
    "description": "Agente responsável por consultar pedidos e estoque e responder ao cliente",
    "taskOrchestration": "DYNAMIC",
    "tasks": [
      {
        "name": "consultarPedido",
        "description": "Consulta o status de um pedido",
        "instruction": "Use a ferramenta de consulta de pedidos para buscar o status pelo número informado",
        "outputKey": "statusPedido",
        "componentTools": [
          {
            "componentDescription": "Consulta pedidos no sistema interno",
            "bodyDescription": "Recebe o número do pedido e devolve status e previsão de entrega",
            "component": { "componentName": "http", "configurations": { "url": "https://api.interna.exemplo.com/pedidos" } }
          }
        ]
      },
      {
        "name": "consultarEstoque",
        "description": "Consulta disponibilidade em estoque",
        "instruction": "Verifique se o produto do pedido está disponível em estoque"
      },
      {
        "name": "gerarResposta",
        "description": "Monta a resposta final para o cliente",
        "instruction": "Combine as informações de pedido e estoque em uma resposta clara para o cliente"
      }
    ]
  }
}

Entrada (execução):

{
  "pergunta": "meu pedido 123 vai chegar quando?",
  "comprovante": "<arquivo do comprovante de compra, disponibilizado por um passo anterior>"
}

Campos de execução do componente:

{
  "prompt": "{$.body.pergunta}",
  "files": "[{\"name\": \"comprovante\", \"mimeType\": \"application/pdf\"}]"
}

Resposta:

{
  "pergunta": "meu pedido 123 vai chegar quando?",
  "response": "Seu pedido 123 está a caminho e a previsão de entrega é dia 25/07."
}

6. Pontos de atenção

Exige ao menos uma tarefa configurada em tasks.
A memória (IN_LOCAL_MEMORY) fica em memória local da aplicação; não é persistida em banco de dados, então é perdida se a aplicação reiniciar ou a sessão expirar.
O modo DYNAMIC depende da capacidade do modelo de IA escolhido de interpretar corretamente a coordenação entre tarefas — a qualidade do resultado varia conforme o modelo.
maxOutputTokens limita o tamanho da resposta gerada.
Arquivos enviados em files precisam estar disponíveis na mensagem como arquivo, sequência de bytes ou texto.

7. Erros Comuns e Troubleshooting

Erro / Sintoma	Causa provável	Como resolver
"Agent name is required" / "Agent model is required" / "ApiKey is required" / "Agent description is required" / "taskOrchestration is required"	Algum campo obrigatório de configuração do agente não foi preenchido.	Preencher todos os campos obrigatórios listados na seção de configuração.
"Agent tasks are required"	O campo `tasks` está vazio ou não foi informado.	Configurar ao menos uma tarefa em `tasks`.
"Task name are required" / "Task description are required" / "Task instruction are required"	Uma das tarefas em `tasks` está sem `name`, `description` ou `instruction`.	Preencher todos os campos obrigatórios de cada tarefa.
"Prompt not found"	O campo `prompt` não foi informado na execução.	Garantir que a mensagem/expressão de `prompt` resolva para um valor não vazio.
"Failed to parse 'files' as JSON array"	O valor resolvido de `files` não é um JSON de lista válido.	Verificar o formato da expressão usada em `files`.
"File entry requires 'name'" / "File entry '[nome]' requires 'mimeType'"	Um item da lista `files` está sem `name` ou `mimeType`.	Preencher os dois campos em cada item de `files`.
"File [nome] not found inside the execution context."	O arquivo referenciado em `files` não está presente na mensagem com esse nome.	Confirmar que um passo anterior do fluxo disponibilizou o arquivo com esse nome exato.
"Unsupported file type for [nome]: [tipo]. Expected File, byte\[\] or String."	O valor da propriedade referenciada em `files` não é um arquivo, sequência de bytes nem texto.	Garantir que o dado disponibilizado na mensagem esteja em um dos formatos suportados.

1. Visão Geral​

2. Pré-requisitos​

3. Autenticação e Conexão​

4. Configuração / Operações Suportadas​

Configuração do agente (definida uma vez, ao iniciar o fluxo)​

Cada item da lista tasks​

Entrada de execução (a cada chamada do agente durante o fluxo)​

5. Exemplos Práticos​

6. Pontos de atenção​

7. Erros Comuns e Troubleshooting​