Skip to main content
Um agente de IA é a configuração base que os assistentes usam. Ele reúne o modelo, as ferramentas que o modelo pode acionar, as instruções que definem o papel e os documentos de referência. O agente de IA sozinho não executa nada. Quem executa é o assistente de etapa, que aponta para um agente e acrescenta a instrução específica, o momento de rodar e o destino da saída. Essa separação existe para permitir reuso: um agente serve a vários assistentes. O papel, as ferramentas e os contextos ficam no agente; o que muda de um assistente para outro é a instrução.

​
Criar um agente

Os agentes ficam em Ajustes → Agentes de IA. Cada agente tem os campos abaixo.
Escreva as instruções para o agente como definição de papel, não como tarefa. “Você é um analista de suporte experiente; seja conciso; nunca invente informação que não esteja no chamado” é instrução de agente. “Classifique este chamado” é instrução de assistente.
Pela API, PUT /api/management/ai/agents/{agent} altera só os campos enviados. O status do agente não muda por essa rota: o campo é ignorado. Para parar as execuções de um agente, desative os assistentes de etapa que usam esse agente, como mostra Assistentes de etapa pela API.

​
Escolher o modelo

A lista de modelos vem com busca e filtros por capacidade:

Filtros disponíveis

Todos os modelos · Modelos com ferramentas · Modelos com raciocínio · Modelos que realizam buscas na internet.

O que cada modelo aceita

Ícones indicam a entrada aceita (texto, imagem, arquivo) e os recursos (ferramentas, saídas estruturadas, busca na internet, raciocínio).
Cada modelo mostra o preço em créditos por milhão de tokens, o que permite comparar antes de escolher.
Alguns modelos aparecem com Preço variável. São modelos de seleção automática: o modelo real é escolhido em tempo de execução e o preço acompanha essa escolha. Ver perfis de seleção automática.
Nem todo modelo aceita todas as ferramentas. Se o agente precisa de busca na internet ou de chamada de ferramenta, filtre a lista por essa capacidade antes de escolher. Com um modelo sem essa capacidade, a ferramenta configurada não é usada.

​
De onde vem a lista

A lista não é fixa. Ela vem do catálogo do agregador de modelos que a Olie usa, o mesmo que devolve nome, capacidades e preço de cada modelo. A lista se atualiza sozinha conforme os provedores lançam, renomeiam ou aposentam modelos, sem depender de uma nova versão da Olie. Pela API, a mesma lista vem de GET /api/management/ai/available-models. Ao criar ou editar o agente, use o id do modelo em default_model e o internal_provider dele em default_provider. Acima do catálogo ficam os três perfis de seleção automática: automática, baseada em custo e baseada em performance. Eles não são um modelo específico, porque a escolha acontece a cada execução. Ver Seleção automática de modelos.

​
Ferramentas

Ferramentas permitem ao agente consultar e agir na plataforma, em vez de apenas gerar texto. Com elas, o agente pode:
  • buscar os detalhes de um projeto;
  • listar e filtrar projetos;
  • consultar um usuário;
  • mover um projeto de etapa;
  • criar ou clonar um projeto;
  • buscar, consultar, criar, editar e excluir clientes e contatos;
  • consultar e responder formulários dinâmicos;
  • pesquisar na internet.
A lista completa está em GET /api/management/ai/available-tools, que também indica se cada ferramenta apenas lê dados ou também escreve. Pela API, o campo tools do agente recebe o name de cada ferramenta dessa lista, como get-project-details-tool. Um nome fora da lista é recusado com HTTP 422.
Cada ferramenta acionada é uma ida a mais ao modelo. Isso aumenta o tempo e o custo da execução. Habilite apenas o que o agente precisa para a tarefa dele.

​
Com quais permissões o agente age

As permissões do agente não são as da pessoa que o aciona. Leia este ponto antes de habilitar ferramentas que escrevem.
O agente executa as ferramentas com acesso total dentro da empresa, e não com as permissões de quem o acionou. Uma pessoa sem acesso a um projeto continua sem vê-lo na interface. Mesmo assim, o agente que ela acionou pode consultar e alterar esse projeto, se tiver a ferramenta habilitada.A única fronteira é a empresa: um agente nunca alcança dados de outra empresa. Dentro dela, não existe restrição por funil, por etapa nem por projeto.
Esse modelo de acesso é diferente do MCP, que age com as permissões da pessoa conectada, e igual ao token de aplicação, que também é de nível proprietário. A governança disponível hoje é uma só: quais ferramentas o agente pode usar.
A consequência prática: trate a lista de ferramentas como uma concessão de acesso. Um agente que só precisa ler não deve ter ferramenta que move projeto, cria projeto ou responde formulário — deixe as de escrita para agentes com escopo estreito e instrução curta.

​
Contextos

A aba Contextos guarda o material de referência do agente. Cada contexto é de um dos dois tipos:
Um exemplo do formato de saída esperado, anexado como contexto, costuma render mais do que uma instrução longa descrevendo esse formato.

​
Testar antes de usar

Você pode executar o agente avulso para ajustar as instruções sem precisar mover um projeto no funil. No teste, você pode usar o modelo padrão do agente ou escolher um modelo para testar e comparar os resultados antes de trocar o padrão. O teste é uma execução como qualquer outra: ele consome créditos de IA e aparece na lista de execuções.

​
Execuções e auditoria

A Olie registra toda execução, com o que entrou, o que saiu e quanto custou. A lista de execuções mostra, por linha: data, agente, modelo, latência, tokens, créditos e status. O custo de cada execução é debitado do saldo de créditos e aparece no extrato de créditos. O detalhe de cada execução traz ainda:

O que entrou

O prompt completo enviado ao modelo.

O que saiu

A resposta gerada, o status e o erro, quando houver.

Quanto custou

Latência, tokens consumidos e créditos debitados do saldo.

Chamadas de ferramenta

Cada ferramenta acionada, com raciocínio, argumentos, retorno e tokens por etapa.
Em Chamadas de ferramenta, cada chamada aparece marcada como executada, erro ou não executada (uma chamada que o agente pediu, mas que não chegou a rodar). Quando o resultado de um agente não é o esperado, comece a investigação por essa lista.
Uma execução que termina sem resposta, ou que acaba com o agente ainda pedindo ferramentas, é registrada como Falhou. No segundo caso, um aviso acima das chamadas indica que a resposta está incompleta. Os créditos do que o modelo já processou são debitados mesmo assim.

​
Limites de cada execução

Toda execução, de agente ou de assistente de etapa, roda dentro destes limites: Ao estourar o tempo, a execução termina como Falhou. Uma falha do provedor do modelo também encerra a execução como Falhou. Nenhum desses casos ganha nova tentativa automática. Esse registro completo fica com quem administra os agentes. Quem opera o funil vê apenas a saída no formulário ou no conteúdo do projeto: não vê o prompt nem o modelo. Essa pessoa também não consegue alterar a instrução de entrada, porque o prompt do assistente monta essa instrução com sintaxe avançada a partir dos dados do projeto.

​
Executar pela API

Um agente também pode ser acionado de fora da interface, por POST /api/management/ai/agents/{agentId}/execute. A execução é assíncrona: a chamada responde na hora, com a execução ainda pendente, e o processamento acontece em fila. Por isso, o corpo da resposta traz o registro da execução, não o texto gerado pelo agente.

Dispare a execução

Envie o prompt, que é obrigatório e passa pela sintaxe avançada antes de chegar ao modelo. Os campos model e provider são opcionais: quando enviados, substituem os padrões do agente só nesta execução.
A resposta traz a execução criada. Guarde o id, porque é com ele que você consulta o resultado.

Consulte o resultado depois

Consulte GET /api/management/ai/agents/executions/{execution} com o id devolvido. O campo status vale pending enquanto a fila não processa e muda para completed ou failed ao terminar. A execução concluída traz a resposta (response), os tokens (tokens_used), a latência (latency, em milissegundos) e os créditos debitados (credits_debited).
A execução que a API devolve é a mesma que aparece na lista de Execuções da interface. Quem integra e quem audita olham o mesmo registro.

​
Sem saldo, a execução é recusada

Antes de começar, a execução confere o saldo de créditos de IA.
Com o saldo de créditos zerado ou negativo, a execução não chega a começar: a chamada recebe HTTP 402 e nenhum registro de execução é criado. Quando a recarga automática está ligada, a Olie tenta a recarga antes de recusar a chamada. A chamada só falha se a recarga também falhar.
A resposta de erro traz três campos para diagnóstico:
  • message: sempre insufficient_credits.
  • available_credits: o saldo no momento do bloqueio, zero ou negativo.
  • auto_recharge_status: disabled quando a recarga automática está desligada, failed quando a última tentativa falhou.
Para voltar a executar, compre créditos ou ligue a recarga automática. Crédito de IA é uma carteira à parte: o consumo de IA não sai do limite de requisições da API. O que tem limite é a quantidade de agentes e de assistentes configurados na empresa. O quanto eles executam depende só do saldo. Uma conta sem créditos continua usando o resto da plataforma normalmente; só a IA para. Ver Créditos de IA e Limites e tetos.
Uma execução que já começou nunca é interrompida no meio por falta de saldo — o débito acontece no fim e pode deixar o saldo negativo. O bloqueio vale para a próxima execução.

​
Por onde passam os dados

Esta seção é para quem avalia a plataforma ou precisa responder a uma diligência interna sobre o tratamento de dados. A Olie não hospeda os modelos. Cada execução sai da plataforma por um agregador de modelos, o OpenRouter. O agregador encaminha a requisição para o provedor do modelo escolhido: OpenAI, Anthropic, Google, DeepSeek e os demais do catálogo. O que trafega é o que a execução carrega: as instruções do agente, os contextos, o prompt montado e o retorno das ferramentas acionadas. O modelo escolhido define o provedor de destino. Em um perfil de seleção automática, esse destino muda a cada execução, e a execução registra qual modelo acabou sendo usado.
As condições de tratamento de dados da plataforma estão nos Termos de Serviço. Para exigências específicas sobre retenção, região de processamento ou uso dos dados por terceiros, leia os Termos e fale com o time da Olie antes de habilitar a IA.

​
Custo

Cada execução consome créditos de IA. O que faz o consumo variar:
  • O modelo escolhido.
  • O tamanho da entrada e da resposta.
  • Recursos avançados como raciocínio e busca na internet.
  • O número de chamadas de ferramenta, que multiplicam as idas ao modelo.
Um assistente com gatilho automático roda a cada movimentação, então o custo acompanha o volume do funil, e não o número de agentes configurados. Antes de ligar um assistente automático em uma etapa movimentada, faça a conta.

​
Como montar agentes que erram menos

Um agente com escopo estreito e instrução curta erra menos que um agente que faz tudo. Cada um grava a conclusão em um campo, e o próximo lê dali.
Cada projeto que chega é a primeira vez para ele. Tudo o que ele precisa saber tem de vir do prompt, do contexto ou de uma ferramenta.
Quando vários agentes trabalham em sequência, o que decide deve ler apenas as saídas dos anteriores. Reduz a chance de resposta inventada e o custo ao mesmo tempo.
“Responda apenas com uma das opções: baixo, médio, alto” cabe em um campo de seleção. “Analise o caso” não cabe em campo nenhum. Uma resposta fora das opções do campo não é gravada, mesmo com a execução marcada como concluída. O motivo fica no registro da execução do assistente.
Ver Padrões de desenho para a montagem completa de uma esteira de agentes.

​
Próximos passos

Assistentes de etapa

Como o agente é acionado em uma etapa e onde a saída é gravada.

Créditos de IA

O modelo de consumo e como acompanhar o extrato.

MCP

Conectar a Olie ao ChatGPT e ao Claude, com as suas permissões.

Padrões de desenho

A esteira de agentes e outras montagens repetíveis.