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 actions for Tracecat actions and mcp_integrations for saved MCP servers.
ai.preset_agent: Prompt plus a saved agent configuration. Use this when you want reusable instructions, tools, skills, and MCP integrations across workflows.
EE tool_approvals: Require approval before selected tools run.
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 servers

Open source ai.agent can call tools from saved MCP integrations. Bring your own remote or stdio MCP server, or connect one from the catalog of 50+ preconfigured MCP servers with guided connection setup, including Splunk, SentinelOne Purple AI, CrowdStrike Falcon, Microsoft Sentinel, Elastic, Wiz, GreyNoise, and PagerDuty. Select the saved integration in the action’s mcp_integrations input, or save it on an agent preset with reusable instructions and tools and run it with ai.preset_agent. Enterprise Edition Enterprise adds tool approvals for MCP tools and the agent inbox for reviewing them. 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.

Timeouts

The action’s timeout caps the agent’s 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. A ceiling below 1800 seconds lowers both the default and the floor to the ceiling. A pause for a tool approval does not count toward the timeout, and the resumed run gets the full timeout again. With the default timeout, a run that reaches it fails with Agent execution timed out after 1800s. See Actions for the clamp rule and the retry_policy shape, and Environment variables for the ceiling.

Reference

`ai.agent`

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

ai.agent 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

string

required

User prompt to the agent.

array[string] | null

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

boolean

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

string | null

Instructions for the agent.Default: null.

integer

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

integer

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

array[string] | null

Saved MCP integrations to include in the agent.Default: null.

object | null

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

string | null

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

string | null

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

object | null

Model settings for the agent.Default: null.

string | object | null

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

integer

Number of retries for the agent.Default: 3.

string | null

Optional existing agent session ID to continue from. If provided, the session must already exist.Default: null.

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:
      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:
      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_case
      - core.cases.create_comment
      - core.cases.update_case
    tool_approvals:
      core.cases.update_case: true
    max_tool_calls: 4

`ai.preset_agent`

Run an AI agent using a saved agent preset. Tools come from the preset and its skills.

The actions input replaces the preset’s registry actions for a single run rather than adding to them. See AI preset agent.

Inputs

string

required

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

string

required

User prompt to the agent.

array[string] | null

Optional. Swaps the preset’s registry actions for this run (MCP tools stay; an empty list is ignored). Handy for tests and evals; tools the agent normally needs fit better on the preset or a skill.Default: null.

string | null

Appended to the preset instructions for this run; durable instructions fit better on the preset.Default: null.

integer

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

integer

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

integer | null

Deprecated compatibility input. Preset agents always resolve the current head.Default: null.

string | null

Optional existing agent session ID to continue from. If provided, the session must already exist.Default: null.

Examples

Run a saved agent preset

- ref: run_security_analyst
  action: ai.preset_agent
  args:
    preset: security-analyst
    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 or saved MCP integrations during the run.
Use ai.preset_agent when you want a reusable configuration with shared instructions, skills, tools, or MCP integrations.

- ref: analyze_input
  action: ai.agent
  args:
    model:
      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 }}

How do I use MCP servers with ai.agent?

Connect a server from the MCP catalog or add a custom remote or stdio MCP server, then select the saved integration in the mcp_integrations input. Both paths are available in open source.

Overview

Building automations

Resolve cases

Building agents

Building custom integrations

Self-hosting

Manage platform

Authentication

Security

Capabilities

Structured outputs

MCP servers

Timeouts

Reference

`ai.agent`

Inputs

Examples

`ai.preset_agent`

Inputs

Examples

FAQ

​Capabilities

​Structured outputs

​MCP servers

​Timeouts

​Reference

​ai.agent

​Inputs

​Examples

​ai.preset_agent

​Inputs

​Examples

​FAQ

Capabilities

Structured outputs

MCP servers

Timeouts

Reference

`ai.agent`

Inputs

Examples

`ai.preset_agent`

Inputs

Examples

FAQ