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.

Timeouts

timeout caps active runtime in seconds. Unset means 1800 seconds, and Tracecat clamps explicit values between 1800 seconds and TRACECAT__AGENT_SANDBOX_TIMEOUT, which defaults to 3600 seconds. See Actions for the clamp rule and the retry_policy shape. A ceiling below 1800 seconds lowers both the default and the floor to the ceiling.

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