---
title: "Executar agente"
method: POST
path: "/api/management/ai/agents/{agentId}/execute"
tags: ["ai-agents", "agents", "execute"]
---

# Executar agente

`POST /api/management/ai/agents/{agentId}/execute`

Dispara uma execução do agente: o `prompt` passa pelo motor de templates e a execução entra na fila de processamento. A resposta devolve o registro recém-criado, ainda sem resultado — o texto gerado, os tokens, os créditos consumidos e os passos aparecem depois no detalhe da execução. `model` e `provider` são opcionais e, quando enviados, substituem os padrões do agente apenas nesta execução.

## Request body

- object — Entrada da execução do agente.
  - `prompt` string, required — Instrução enviada ao agente. Passa pelo motor de templates antes de chegar ao modelo.
  - `model` string, nullable — Modelo a usar apenas nesta execução; quando ausente ou nulo vale o modelo padrão do agente.
  - `provider` 'openrouter' | 'google' | 'openai' | 'anthropic' | 'null', nullable — Provedor a usar apenas nesta execução; quando ausente ou nulo vale o provedor padrão do agente.

## Response `200`

Sucesso

- object — Execução criada e enfileirada.
  - `response` boolean — Indicador de sucesso da requisição; sempre verdadeiro nesta resposta.
  - `execution` object — Execução recém-enfileirada, ainda sem resultado.
    - `agent_id` string, uuid — ID (UUID) do agente executado.
    - `provider` 'openrouter' | 'google' | 'openai' | 'anthropic' — Provedor de IA que vai processar a execução.
    - `model` string, nullable — Modelo de IA que vai processar a execução.
    - `prompt` string, nullable — Instrução enviada ao agente, já com o template renderizado.
    - `frame_id` string, uuid — ID (UUID) da empresa dona da execução.
    - `updated_at` string, date-time — Data e hora da última alteração do registro.
    - `created_at` string, date-time — Data e hora em que a execução foi enfileirada.
    - `id` string, uuid — ID (UUID) da execução, usado para consultar o resultado depois.

## Other responses

- `402` — Créditos de IA esgotados
- `404` — Agente não encontrado

## Changes

- **2026-09-22** `d71b18b1685d` — 4 breaking, 6 warning, 2 info
  - the request property `prompt` became required
  - the response property `execution/model` became nullable for the status `200`
  - the response property `execution/prompt` became nullable for the status `200`
  - the `available_credits` response's property type changed from `integer` to `number` for status `402`
  - …8 more
- **2026-09-22** `b43a04f35145` — 2 warning
  - removed the request property `model`
  - removed the request property `provider`
- **2026-09-18** `3202abfa17f9` — 4 info
  - added optional request body
  - added the media type `application/json` for the response with the status `200`
  - added the non-success response with the status `402`
  - added the non-success response with the status `404`

[Change history](https://skmtc.dev/olie-ai/apis/olie-api/changes/api/management/ai/agents/:agentId/execute/post.md)

---

[API](https://skmtc.dev/olie-ai/apis/olie-api.md) · [All operations](https://skmtc.dev/olie-ai/apis/olie-api/llms.txt) · [OpenAPI document](https://skmtc.dev/olie-ai/apis/olie-api/revisions/d71b18b1685d?raw)