---
title: "Criar um assistente da etapa"
method: POST
path: "/api/management/steps/{step}/assistants"
tags: ["step-assistants", "Assistentes"]
---

# Criar um assistente da etapa

`POST /api/management/steps/{step}/assistants`

Cria um assistente na etapa. Se `active` for verdadeiro, ele já entra em operação e passa a disparar no gatilho escolhido em `execute_on`: ao entrar na etapa (`moved`), ao sair dela (`unlinked`) ou somente sob demanda (`manual`).

É obrigatório indicar pelo menos um destino para o resultado: `result_as_media` grava como conteúdo do projeto e `result_as_dynamic_form` grava em um campo de formulário dinâmico. Os dois podem ser usados juntos.

A etapa do assistente é a do corpo (`funnel_step_id`) — é ela que vale, e não a da URL.

Cada execução consome créditos de IA. Veja [Assistentes de etapa](https://docs.olie.ai/guides/funnels/step-assistants) e [Créditos de IA](https://docs.olie.ai/guides/billing/ai-credits).

## Request body

- object — Configuração do assistente. Pelo menos um destino de resultado é obrigatório: `result_as_media` ou `result_as_dynamic_form`.
  - `name` string, required — Nome do assistente. Obrigatório, até 255 caracteres.
  - `active` boolean — Define se o assistente entra em operação. Padrão `true`.
  - `funnel_step_id` integer, required — ID da etapa do funil à qual o assistente pertence. Obrigatório — é este campo que vale, e não o ID da URL.
  - `ai_agent_id` string, uuid, required — ID (UUID) do agente de IA que executa a tarefa. Obrigatório e precisa pertencer à mesma conta.
  - `prompt` string, required — Instrução dada ao agente. Obrigatória. Aceita a sintaxe avançada, com dados do projeto e da etapa.
  - `execute_on` 'moved' | 'unlinked' | 'manual', required — Gatilho do assistente: `moved` ao entrar na etapa, `unlinked` ao sair dela e `manual` só sob demanda.
  - `manual_execution_enabled` boolean — Permite disparar o assistente sob demanda mesmo com gatilho automático. Padrão `false`.
  - `failure_funnel_step_id` integer, nullable — Etapa para onde o projeto vai se a execução falhar. Precisa ser da mesma conta e diferente de `funnel_step_id`. `null` deixa o projeto onde está.
  - `result_as_media` boolean — Grava o resultado como conteúdo do projeto. Obrigatório quando `result_as_dynamic_form` não é enviado.
  - `result_as_dynamic_form` object, nullable — Grava o resultado em um campo de formulário dinâmico. Os identificadores são resolvidos a cada execução pela sintaxe avançada, então aceitam variáveis como `{{ project.id }}` e `{{ step.id }}` em vez de valores fixos. Obrigatório quando `result_as_media` não é enviado.
    - `pivot_class` string, required — Classe do registro que guarda as respostas, no formato `App\Models\<Modelo>`. Define quais chaves de identificação abaixo são exigidas.
    - `form_id` integer, required — ID do formulário dinâmico que receberá a resposta.
    - `edge_id` integer, required — ID do campo do formulário que receberá o resultado gerado pelo assistente.
    - `id` string, nullable — Identificador do registro alvo, quando a classe se identifica por `id` (por exemplo `App\Models\Project`).
    - `project_id` string, nullable — ID do projeto alvo, quando a classe se identifica pelo projeto.
    - `funnel_step_id` string, nullable — ID da etapa alvo, quando a classe se identifica pela etapa.
    - `loose_form_id` string, nullable — ID do formulário avulso alvo, quando a classe se identifica por ele.
    - `project_funnel_id` string, nullable — ID do funil alvo, quando a classe se identifica por ele.

## Response `201`

Criado

- object — Assistente gravado. A etapa e o agente de IA não vêm carregados nesta resposta.
  - `response` boolean, required — Sempre true quando a operação é concluída.
  - `assistant` object, required — Assistente de etapa.
    - `id` string, uuid — ID (UUID) do assistente.
    - `name` string — Nome do assistente, usado nas listas e nos registros de execução.
    - `active` boolean — Indica se o assistente está em operação. Inativo, ele nunca dispara.
    - `funnel_step_id` integer — ID da etapa do funil à qual o assistente pertence.
    - `ai_agent_id` string, uuid — ID (UUID) do agente de IA que executa a tarefa.
    - `prompt` string — Instrução dada ao agente. Aceita a sintaxe avançada, com dados do projeto e da etapa.
    - `execute_on` 'moved' | 'unlinked' | 'manual' — Gatilho do assistente: `moved` ao entrar na etapa, `unlinked` ao sair dela e `manual` só sob demanda.
    - `manual_execution_enabled` boolean — Indica se o assistente também pode ser disparado sob demanda, mesmo tendo gatilho automático.
    - `result_as_media` boolean — Indica se o resultado é gravado como conteúdo do projeto.
    - `result_as_dynamic_form` object, nullable — Destino do resultado em campo de formulário dinâmico. `null` quando o assistente não grava em formulário.
      - `pivot_class` string — Classe do registro que guarda as respostas, no formato `App\Models\<Modelo>`. Define quais chaves de identificação abaixo são exigidas.
      - `form_id` integer — ID do formulário dinâmico que receberá a resposta.
      - `edge_id` integer — ID do campo do formulário que receberá o resultado gerado pelo assistente.
      - `id` string, nullable — Identificador do registro alvo, quando a classe se identifica por `id` (por exemplo `App\Models\Project`).
      - `project_id` string, nullable — ID do projeto alvo, quando a classe se identifica pelo projeto.
      - `funnel_step_id` string, nullable — ID da etapa alvo, quando a classe se identifica pela etapa.
      - `loose_form_id` string, nullable — ID do formulário avulso alvo, quando a classe se identifica por ele.
      - `project_funnel_id` string, nullable — ID do funil alvo, quando a classe se identifica por ele.
    - `failure_funnel_step_id` integer, nullable — Etapa para onde o projeto é movido quando a execução falha. `null` deixa o projeto onde está.
    - `created_at` string, date-time — Data de criação.
    - `updated_at` string, date-time — Data da última alteração.
    - `deleted_at` string, date-time, nullable — Data de exclusão, quando o assistente foi removido.

## Other responses

- `422` — Validação falhou

## Changes

- **2026-08-24** `3c590152d5b5` — 20 breaking, 4 warning, 24 info
  - request property `execute_on` was restricted to a list of enum values
  - the request property `ai_agent_id` became required
  - the request property `execute_on` became required
  - the request property `funnel_step_id` became required
  - …44 more
- **2026-08-19** `d49d48cd1ce0` — 1 info
  - api tag `Assistentes` added
- **2026-08-19** `69f9300dc045` — 1 breaking, 2 info
  - removed the success response with the status `200`
  - added the non-success response with the status `422`
  - added the success response with the status `201`

[Change history](https://skmtc.dev/olie-ai/apis/olie-api/changes/api/management/steps/:step/assistants/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-service-production.skmtc.workers.dev/v1/apis/olie-ai/olie-api/revisions/85cb24130071/schema)