Skip to main content
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. 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