AI agent

Use ai.agent when the model needs tool calls. You give the agent a prompt, instructions, and an allowlist of actions it can call during the run.

Capabilities

ai.agent: Prompt plus tool calls. Use the actions list to control which Tracecat actions the agent can use.
EE ai.preset_agent: Prompt plus a saved agent configuration. Use this when you want reusable instructions, tools, and MCP integrations across workflows.
tool_approvals: Require approval before selected tools run. This is an enterprise feature.
max_tool_calls and max_requests: Bound how much work the agent can do in a single run.

Structured outputs

ai.agent also supports output_type.

Use it when the agent should return a final object or typed value after tool use.
Keep the schema focused on the final answer, not the intermediate tool steps.

MCP

Enterprise Edition ai.agent does not take MCP servers directly in the workflow action. If you need MCP, save that configuration in an agent preset and run it with ai.preset_agent. ai.preset_agent supports both remote and stdio MCP servers. Internet access is controlled by the root preset for the shared sandbox process. Subagent presets can define their own tools and MCP integrations, but their internet setting does not grant network access unless the root preset also enables it. See MCP integrations to learn more.

Reference

`ai.agent`

AI agent with tool calling capabilities. Returns the output and full message history.

Inputs

model_name

string

required

Name of the model to use.

model_provider

string

required

Provider of the model to use.

user_prompt

string

required

User prompt to the agent.

actions

array[string] | null

Actions (e.g. ‘tools.slack.post_message’) to include in the agent.Default: null.

base_url

string | null

Base URL of the model to use.Default: null.

instructions

string | null

Instructions for the agent.Default: null.

max_requests

integer

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

max_tool_calls

integer

Maximum number of tool calls for the agent.Default: 15.

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.

tool_approvals

map[string, boolean] | null

Per-tool approval overrides keyed by action name (e.g. ‘core.cases.create_case’). Use true to require approval, false to allow auto-execution.Default: null.

Examples

Investigate an alert with tools

- ref: investigate_alert
  action: ai.agent
  args:
    model_name: gpt-4.1
    model_provider: openai
    instructions: |
      You are a security triage agent.
      Review the alert, gather missing context, and write a concise analyst summary.
    user_prompt: |
      Investigate this alert and explain whether it needs escalation:

      ${{ TRIGGER.alert }}
    actions:
      - tools.slack.lookup_users_by_email
      - tools.github.search_code
      - core.cases.create_comment
    max_tool_calls: 6
    output_type:
      type: object
      properties:
        verdict:
          type: string
        summary:
          type: string
      required:
        - verdict
        - summary

Require approval for sensitive tools

- ref: draft_case_update
  action: ai.agent
  args:
    model_name: claude-3-5-sonnet-latest
    model_provider: anthropic
    instructions: |
      Investigate the incident, then propose the next action.
      Create or update records only if the required approval is granted.
    user_prompt: |
      Review the latest evidence for case ${{ TRIGGER.case_id }} and decide what to do next.
    actions:
      - core.cases.get
      - core.cases.create_comment
      - core.cases.update
    tool_approvals:
      core.cases.update: true
    max_tool_calls: 4

`ai.preset_agent`

Enterprise Edition Run an AI agent using a saved agent preset.

Inputs

preset

string

required

Preset of the agent to run (e.g. ‘security-analyst’).

user_prompt

string

required

User prompt to the agent.

actions

array[string] | null

Optional override for the actions (e.g. ‘tools.slack.post_message’) that the agent should be allowed to call.Default: null.

instructions

string | null

Additional instructions to append to the preset instructions for this run.Default: null.

max_requests

integer

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

max_tool_calls

integer

Maximum number of tool calls for the agent.Default: 15.

preset_version

integer | null

Optional preset version number to pin for this run.Default: null.

Examples

Run a saved agent preset

- ref: run_security_analyst
  action: ai.preset_agent
  args:
    preset: security-analyst
    preset_version: 3
    user_prompt: |
      Review the incident below and decide whether to escalate it:

      ${{ TRIGGER.incident }}
    max_tool_calls: 8

FAQ

When should I use ai.action, ai.agent, or ai.preset_agent?

Use ai.action when you only need one model response and no tools.
Use ai.agent when the model must call Tracecat actions during the run.
Use ai.preset_agent when you want a reusable saved configuration, especially for shared instructions, approvals, or MCP integrations.

- ref: analyze_input
  action: ai.agent
  args:
    model_name: gpt-4.1-mini
    model_provider: openai
    instructions: |
      Investigate the alert and summarize the next step.
    user_prompt: |
      Review this alert:

      ${{ TRIGGER.alert }}
    actions:
      - tools.github.search_code
      - core.cases.create_comment
    max_tool_calls: 4

- ref: analyze_with_preset
  action: ai.preset_agent
  args:
    preset: security-analyst
    user_prompt: |
      Review this alert and write a short analyst summary:

      ${{ TRIGGER.alert }}

Why does ai.agent not accept MCP servers directly, and where do I configure MCP instead?

MCP integrations are configured on the preset, not on the ai.agent workflow action itself. If the run needs MCP tools, create or update an agent preset, attach the MCP integrations there, and execute it with ai.preset_agent.Use ai.agent when Tracecat workflow actions alone are enough. Use ai.preset_agent when the agent needs access to MCP servers in addition to regular Tracecat actions.

Overview

Building automations

Building agents

Building custom actions

Self-hosting

Authentication

Audit logs

Capabilities

Structured outputs

MCP

Reference

`ai.agent`

Inputs

Examples

`ai.preset_agent`

Inputs

Examples

FAQ

​Capabilities

​Structured outputs

​MCP

​Reference

​ai.agent

​Inputs

​Examples

​ai.preset_agent

​Inputs

​Examples

​FAQ

Capabilities

Structured outputs

MCP

Reference

`ai.agent`

Inputs

Examples

`ai.preset_agent`

Inputs

Examples

FAQ