> ## Documentation Index
> Fetch the complete documentation index at: https://tracecat-codex-docs-secrets-oauth-discoverability.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# AI action

> Use `ai.action` to run a single LLM call in a workflow.

Use `ai.action` when you only need a prompt and an output. It runs one model call and does not let the model call tools.

## Capabilities

* Pass task instructions in `instructions` and task data in `user_prompt`.
* Use `output_type` when you need a string, list, or JSON-shaped response for downstream actions.
* Tune provider-specific behavior with `model_settings`.

## Structured outputs

Use `output_type` when a downstream action needs a predictable shape.

* Use a scalar such as `str` or `int` for simple classification or routing.
* Use a JSON schema object when you need named fields.
* Tracecat parses valid JSON before storing it in the action result.

## Reference

### `ai.action`

Call an LLM with a given prompt and model (no tools).

<Warning>
  `ai.action` requires a model selection at runtime. Set `model` with both `model_name` and `model_provider`, or set the deprecated top-level `model_name` and `model_provider` inputs together.
</Warning>

#### Inputs

<ParamField path="user_prompt" type="string" required>
  User prompt to the agent.
</ParamField>

<ParamField path="enable_thinking" type="boolean">
  Whether to enable high thinking for agent runs.

  Default: `true`.
</ParamField>

<ParamField path="instructions" type="string | null">
  Instructions for the agent.

  Default: `null`.
</ParamField>

<ParamField path="max_requests" type="integer">
  Maximum number of requests for the agent.

  Default: `45`.
</ParamField>

<ParamField path="model" type="object | null">
  Model to use. Pick from the list of models enabled for this workspace.

  Default: `null`.
</ParamField>

<ParamField path="model_name" type="string | null">
  Deprecated model name. Use `model` instead.

  Default: `null`.
</ParamField>

<ParamField path="model_provider" type="string | null">
  Deprecated model provider. Use `model` instead.

  Default: `null`.
</ParamField>

<ParamField path="model_settings" type="object | null">
  Model settings for the agent.

  Default: `null`.
</ParamField>

<ParamField path="output_type" type="string | object | null">
  Output type for agent responses. Select from a list of supported types or provide a JSONSchema.

  Default: `null`.
</ParamField>

<ParamField path="retries" type="integer">
  Number of retries for the agent.

  Default: `3`.
</ParamField>

#### Examples

**Extract structured fields from an alert**

```yaml theme={null}
- ref: extract_alert
  action: ai.action
  args:
    model:
      model_name: gpt-4.1-mini
      model_provider: openai
    instructions: |
      Extract the alert into the requested schema.
      Use null for fields that are missing.
    user_prompt: |
      Parse this alert and normalize the key fields:

      ${{ TRIGGER.raw_alert }}
    output_type:
      type: object
      properties:
        severity:
          type: string
        user:
          type:
            - string
            - "null"
        src_ip:
          type:
            - string
            - "null"
        needs_escalation:
          type: boolean
      required:
        - severity
        - needs_escalation
```

**Classify an email triage decision**

```yaml theme={null}
- ref: classify_email
  action: ai.action
  args:
    model:
      model_name: claude-3-5-sonnet-latest
      model_provider: anthropic
    instructions: |
      Return one of: phishing, benign, spam, unknown.
    user_prompt: |
      Subject: ${{ TRIGGER.subject }}
      Sender: ${{ TRIGGER.sender }}
      Body:
      ${{ TRIGGER.body }}
    output_type:
      type: string
      enum:
        - phishing
        - benign
        - spam
        - unknown
```