AI action

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).

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.

Inputs

user_prompt

string

required

User prompt to the agent.

enable_thinking

boolean

Whether to enable high thinking for agent runs.Default: true.

instructions

string | null

Instructions for the agent.Default: null.

max_requests

integer

Maximum number of requests for the agent.Default: 45.

model

object | null

Model to use. Pick from the list of models enabled for this workspace.Default: null.

model_name

string | null

Deprecated model name. Use model instead.Default: null.

model_provider

string | null

Deprecated model provider. Use model instead.Default: null.

model_settings

object | null

Model settings for the agent.Default: null.

output_type

string | object | null

Output type for agent responses. Select from a list of supported types or provide a JSONSchema.Default: null.

retries

integer

Number of retries for the agent.Default: 3.

Examples

Extract structured fields from an alert

- 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

- 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

Overview

Building automations

Building agents

Building custom actions

Self-hosting

Authentication

Audit logs

Capabilities

Structured outputs

Reference

`ai.action`

Inputs

Examples

​Capabilities

​Structured outputs

​Reference

​ai.action

​Inputs

​Examples

Capabilities

Structured outputs

Reference

`ai.action`

Inputs

Examples