> ## Documentation Index
> Fetch the complete documentation index at: https://tracecat-feat-mcp-cred-setup.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# AI agent

> Run tool-calling agents with Tracecat actions, MCP servers, structured outputs, approvals, and reusable presets.

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.
* <Badge icon="lock" color="blue" size="sm" shape="pill">EE</Badge> `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

<Badge icon="github" color="gray" size="lg" shape="pill">Open source</Badge>

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

<Badge icon="lock" color="blue" size="lg" shape="pill">Enterprise Edition</Badge>

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](/automations/integrations/mcp-integrations) to learn more.

## Reference

### `ai.agent`

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

<Warning>
  `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.
</Warning>

#### Inputs

<ParamField path="user_prompt" type="string" required>
  User prompt to the agent.
</ParamField>

<ParamField path="actions" type="array[string] | null">
  Actions (e.g. 'tools.slack.post\_message') to include in the agent.

  Default: `null`.
</ParamField>

<ParamField path="enable_thinking" type="boolean">
  Whether to enable high thinking for agent runs.

  Default: `true`.
</ParamField>

<ParamField path="instructions" type="string | null">
  Instructions for the agent.

  Default: `null`.
</ParamField>

<ParamField path="max_requests" type="integer">
  Maximum number of requests for the agent.

  Default: `45`.
</ParamField>

<ParamField path="max_tool_calls" type="integer">
  Maximum number of tool calls for the agent.

  Default: `15`.
</ParamField>

<ParamField path="mcp_integrations" type="array[string] | null">
  Saved MCP integrations to include in the agent.

  Default: `null`.
</ParamField>

<ParamField path="model" type="object | null">
  Model to use. Pick from the list of models enabled for this workspace.

  Default: `null`.
</ParamField>

<ParamField path="model_name" type="string | null">
  Deprecated model name. Use `model` instead.

  Default: `null`.
</ParamField>

<ParamField path="model_provider" type="string | null">
  Deprecated model provider. Use `model` instead.

  Default: `null`.
</ParamField>

<ParamField path="model_settings" type="object | null">
  Model settings for the agent.

  Default: `null`.
</ParamField>

<ParamField path="output_type" type="string | object | null">
  Output type for agent responses. Select from a list of supported types or provide a JSONSchema.

  Default: `null`.
</ParamField>

<ParamField path="retries" type="integer">
  Number of retries for the agent.

  Default: `3`.
</ParamField>

<ParamField path="session_id" type="string | null">
  Optional existing agent session ID to continue from. If provided, the session must already exist.

  Default: `null`.
</ParamField>

<ParamField path="tool_approvals" type="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`.
</ParamField>

#### Examples

**Investigate an alert with tools**

```yaml theme={null}
- 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**

```yaml theme={null}
- 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`

<Badge icon="lock" color="blue" size="lg" shape="pill">Enterprise Edition</Badge>

Run an AI agent using a saved agent preset.

#### Inputs

<ParamField path="preset" type="string" required>
  Preset of the agent to run (e.g. 'security-analyst').
</ParamField>

<ParamField path="user_prompt" type="string" required>
  User prompt to the agent.
</ParamField>

<ParamField path="actions" type="array[string] | null">
  Optional override for the actions (e.g. 'tools.slack.post\_message') that the agent should be allowed to call.

  Default: `null`.
</ParamField>

<ParamField path="instructions" type="string | null">
  Additional instructions to append to the preset instructions for this run.

  Default: `null`.
</ParamField>

<ParamField path="max_requests" type="integer">
  Maximum number of requests for the agent.

  Default: `45`.
</ParamField>

<ParamField path="max_tool_calls" type="integer">
  Maximum number of tool calls for the agent.

  Default: `15`.
</ParamField>

<ParamField path="preset_version" type="integer | null">
  Optional preset version number to pin for this run.

  Default: `null`.
</ParamField>

<ParamField path="session_id" type="string | null">
  Optional existing agent session ID to continue from. If provided, the session must already exist.

  Default: `null`.
</ParamField>

#### Examples

**Run a saved agent preset**

```yaml theme={null}
- 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

<AccordionGroup>
  <Accordion title="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.

    <CodeGroup>
      ```yaml Use ai.agent for tool calls theme={null}
      - 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
      ```

      ```yaml Use ai.preset_agent for saved configuration theme={null}
      - 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 }}
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>