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

Open source ai.agent can call tools from saved custom remote or stdio MCP integrations. In open-source deployments, bring your own MCP server and select it in the action’s mcp_integrations input. Enterprise Edition Enterprise includes a catalog of 50+ preconfigured MCP servers with guided connection setup, including Splunk, SentinelOne Purple AI, CrowdStrike Falcon, Microsoft Sentinel, Elastic, Wiz, GreyNoise, and PagerDuty. Enterprise also adds ai.preset_agent, so you can save MCP integrations with reusable instructions and tools. 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.

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

string

required

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

string

required

User prompt to the agent.

array[string] | null

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

string | null

Additional instructions to append to the preset instructions for this run.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

Optional preset version number to pin for this run.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
    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 or saved MCP integrations during the run.
Use ai.preset_agent when you want a reusable Enterprise configuration with shared instructions, approvals, 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?

Create a custom remote or stdio MCP server, then select the saved integration in the mcp_integrations input. This bring-your-own MCP path is available in open source.Enterprise adds the catalog of 50+ preconfigured MCP servers and reusable agent presets.

Overview

Building automations

Building agents

Building custom actions

Self-hosting

Authentication

Security

Capabilities

Structured outputs

MCP servers

Reference

`ai.agent`

Inputs

Examples

`ai.preset_agent`

Inputs

Examples

FAQ

​Capabilities

​Structured outputs

​MCP servers

​Reference

​ai.agent

​Inputs

​Examples

​ai.preset_agent

​Inputs

​Examples

​FAQ

Capabilities

Structured outputs

MCP servers

Reference

`ai.agent`

Inputs

Examples

`ai.preset_agent`

Inputs

Examples

FAQ