# AI Actions

The `ai` family runs language-model operations as automation steps. Four operators cover free-form generation, classification, structured extraction, and autonomous agent execution. Provider and model are explicit per action; credentials come from a stored [connection](/en/docs/automation-connections). For self-hosted or custom endpoints (e.g. Ollama), the base URL is configured once via the `AI_BASE_URL` environment variable, not per action.

| Operator   | Purpose                                                            |
| ---------- | ------------------------------------------------------------------ |
| `generate` | Produce free-form text (or JSON) from a prompt.                    |
| `classify` | Assign an input to one of a fixed set of categories.               |
| `extract`  | Pull structured data matching a schema out of unstructured text.   |
| `agent`    | Invoke a configured autonomous agent to perform a multi-step task. |

**Shared provider props:** `provider` is `openai` / `anthropic` / `ollama` / `custom`; `model` is the model id; `connection` references stored credentials. Self-hosted endpoints (e.g. Ollama) are pointed at via the `AI_BASE_URL` environment variable.

## generate

| Prop             | Description                                                 |
| ---------------- | ----------------------------------------------------------- |
| `provider`       | `openai` / `anthropic` / `ollama` / `custom`. **Required.** |
| `model`          | Model id. **Required.**                                     |
| `prompt`         | The user prompt (templatable). **Required.**                |
| `systemPrompt`   | Optional system prompt.                                     |
| `temperature`    | Sampling temperature.                                       |
| `maxTokens`      | Max tokens to generate.                                     |
| `responseFormat` | `text` (default) or `json`.                                 |
| `connection`     | Stored connection providing credentials.                    |

```yaml
- name: draftReply
  type: ai
  operator: generate
  props:
    provider: anthropic
    model: claude-sonnet
    systemPrompt: 'You are a concise support agent.'
    prompt: 'Draft a reply to: {{trigger.comment.body}}'
    responseFormat: text
    connection: anthropic-key
```

## classify

| Prop         | Description                                       |
| ------------ | ------------------------------------------------- |
| `input`      | Text to classify (templatable). **Required.**     |
| `categories` | Array of candidate category labels. **Required.** |
| _(provider)_ | `provider`, `model`, `connection?`                |

```yaml
- name: triage
  type: ai
  operator: classify
  props:
    provider: openai
    model: gpt-4o-mini
    input: '{{trigger.data.message}}'
    categories: [bug, billing, feature-request, spam]
    connection: openai-key
```

## extract

| Prop         | Description                                                    |
| ------------ | -------------------------------------------------------------- |
| `input`      | Unstructured text to extract from (templatable). **Required.** |
| `schema`     | JSON Schema describing the desired output shape. **Required.** |
| _(provider)_ | `provider`, `model`, `connection?`                             |

```yaml
- name: parseInvoice
  type: ai
  operator: extract
  props:
    provider: openai
    model: gpt-4o
    input: '{{extractText.result}}'
    schema:
      total: { type: number }
      due_date: { type: string }
      vendor: { type: string }
    connection: openai-key
```

## agent

Invokes an autonomous agent configured under the app's AI agents. The agent plans and executes multiple steps against its scoped tools.

| Prop             | Description                                       |
| ---------------- | ------------------------------------------------- |
| `agent`          | Name of a configured agent. **Required.**         |
| `task`           | The task instruction (templatable). **Required.** |
| `context`        | Key-value context passed to the agent.            |
| `maxSteps`       | Cap on the agent's reasoning/tool steps.          |
| `responseFormat` | `text` (default) or `json`.                       |
| `timeout`        | Per-invocation timeout in ms.                     |
| `connection`     | Stored connection providing credentials.          |

```yaml
- name: resolve
  type: ai
  operator: agent
  props:
    agent: support-resolver
    task: 'Resolve ticket {{trigger.data.id}} using the knowledge base.'
    context: { customerTier: '{{trigger.data.tier}}' }
    maxSteps: 8
    responseFormat: json
```

:::callout
**Eco-aware provider routing.** AI calls route through the provider-precedence resolver governed by `ECO_AI_PROVIDER_PRECEDENCE` (default `local-first`) — never hard-code a single cloud provider when a local model can serve the request. See [AI Overview](/en/docs/ai-overview).
:::

## Related Pages

- [AI Overview](/en/docs/ai-overview) — providers, models, and eco routing.
- [AI Agents](/en/docs/ai-agents) — configuring the autonomous agents invoked by `ai/agent`.
- [Connections](/en/docs/automation-connections) — credentials for AI providers.
- [Approval & Delay](/en/docs/automation-approval-delay) — human-in-the-loop gates around AI output.