---
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
  - `prompt` string

## Response `200`

Sucesso

- object
  - `response` boolean
  - `execution` object
    - `agent_id` string
    - `provider` string
    - `model` string
    - `prompt` string
    - `frame_id` string
    - `updated_at` string, date-time
    - `created_at` string, date-time
    - `id` string

## Other responses

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

## Changes

- **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/b43a04f35145?raw)