---
title: "Criar agente de IA"
method: POST
path: "/api/management/ai/agents"
tags: ["ai-agents", "agents"]
---

# Criar agente de IA

`POST /api/management/ai/agents`

Cria um agente de IA. No modo manual (padrão) informe `name`, `description`, `default_provider` e `default_model`; `tools` aceita apenas os nomes devolvidos pelo endpoint de ferramentas disponíveis. Com `auto_generate: true` basta enviar `description`: o sistema redige nome, prompt base, ferramentas e os contextos iniciais do agente, e nesse modo a criação respeita o limite de agentes contratado, respondendo 402 quando ele já foi atingido.

## Request body

- object — Dados para criar um agente de IA.
  - `name` string — Nome do agente. Obrigatório quando `auto_generate` é falso ou ausente.
  - `description` string, required — Descrição curta do agente. No modo de geração automática é a partir dela que o agente inteiro é redigido.
  - `default_provider` 'openrouter' | 'google' | 'openai' | 'anthropic' — Provedor de IA padrão do agente. Obrigatório quando `auto_generate` é falso ou ausente.
  - `default_model` string — Identificador do modelo padrão, conforme o `id` devolvido pelo catálogo de modelos disponíveis. Obrigatório quando `auto_generate` é falso ou ausente.
  - `base_prompt` string, nullable — Prompt base que define o comportamento do agente.
  - `tools` string[], nullable — Ferramentas que o agente pode usar; nomes fora do catálogo são rejeitados.
  - `auto_generate` boolean — Quando verdadeiro, nome, prompt base, ferramentas e contextos iniciais são gerados a partir de `description` e os demais campos enviados são ignorados.

## Response `200`

Sucesso

- object — Agente criado no modo manual.
  - `response` boolean — Indicador de sucesso da requisição; sempre verdadeiro nesta resposta.
  - `agent` object — Agente recém-criado, ainda sem execuções nem contadores.
    - `name` string — Nome do agente.
    - `description` string, nullable — Descrição curta do agente.
    - `default_model` string, nullable — Identificador do modelo de IA padrão do agente.
    - `default_provider` 'openrouter' | 'google' | 'openai' | 'anthropic' | 'null', nullable — Provedor de IA padrão do agente.
    - `tools` string[], nullable — Ferramentas habilitadas para o agente.
    - `base_prompt` string, nullable — Prompt base que define o comportamento do agente.
    - `frame_id` string, uuid — ID (UUID) da empresa dona do agente.
    - `created_by` string, uuid, nullable — ID (UUID) do usuário que criou o agente.
    - `updated_at` string, date-time — Data e hora da última alteração do agente.
    - `created_at` string, date-time — Data e hora de criação do agente.
    - `id` string, uuid — ID (UUID) do agente.

## Other responses

- `402` — Limite de agentes atingido
- `422` — Erro de validação

## Changes

- **2026-09-22** `d71b18b1685d` — 10 breaking, 30 warning, 28 info
  - request property `default_provider` was restricted to a list of enum values
  - request property `tools/items/` was restricted to a list of enum values
  - the request property `description` became required
  - the `tools/items/` request property type changed from no type to `string`
  - …64 more
- **2026-09-18** `3202abfa17f9` — 3 info
  - 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 `422`

[Change history](https://skmtc.dev/olie-ai/apis/olie-api/changes/api/management/ai/agents/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)