Secrets and variables

Overview

Preset agents can reference secrets and variables using Tracecat expression syntax. Include ${{ SECRETS.<name>.<key> }} or ${{ VARS.<name>.<key> }} in a preset agent’s saved instructions so the agent passes them as tool arguments at runtime.

Security

Preset agent tool calls go through a secure server-side proxy. The LLM only sees the raw expression placeholder (e.g. ${{ SECRETS.threatintel.API_KEY }}). The actual secret values are injected server-side at the tool execution layer after the model responds, so the LLM never has access to your credentials.

Do not use SECRETS expressions — or any expression that resolves to a value you would not send to your LLM provider — in ai.action or ai.agent inputs. Use ai.preset_agent for secure secrets injection.

Secrets

Use ${{ SECRETS.<secret_name>.<key> }} to reference a secret stored in your workspace credentials. In a workflow action this looks like:

- ref: triage_alert
  action: ai.preset_agent
  args:
    preset: security-triage
    user_prompt: |
      Look up the reputation of this IP address:

      ${{ TRIGGER.source_ip }}

Where the security-triage preset instructions contain:

You are a security triage agent.

When you make HTTP requests to the threat intel API, pass
`${{ SECRETS.threatintel.API_KEY }}` in the Authorization header
as a Bearer token.

Do not print or return secret values in your final answer.

Variables

Use ${{ VARS.<variable_name>.<key> }} for non-sensitive configuration such as base URLs, project IDs, or channel names. In a workflow action:

- ref: triage_alert
  action: ai.preset_agent
  args:
    preset: security-triage
    user_prompt: |
      Investigate this alert and file a ticket with your findings:

      ${{ TRIGGER.alert }}

Where the security-triage preset instructions contain:

You are a security triage agent.

When you call the threat intel API, use `${{ VARS.threatintel.base_url }}`
as the base URL.
When you file tickets, use `${{ VARS.ticketing.project_id }}` as the
project ID and `${{ VARS.ticketing.base_url }}` as the base URL.

Use secrets for credentials and variables for everything else. Full workflow example:

- ref: investigate_and_respond
  action: ai.preset_agent
  args:
    preset: security-triage
    user_prompt: |
      Investigate this alert:

      ${{ TRIGGER.alert }}
    max_tool_calls: 10

Where the security-triage preset instructions contain:

You are a security triage agent. Investigate the alert, enrich it,
and file a ticket.

Credentials:
- Threat intel API key: `${{ SECRETS.threatintel.API_KEY }}`
- Ticketing API key: `${{ SECRETS.ticketing.API_KEY }}`

Configuration:
- Threat intel base URL: `${{ VARS.threatintel.base_url }}`
- Ticketing base URL: `${{ VARS.ticketing.base_url }}`
- Ticketing project ID: `${{ VARS.ticketing.project_id }}`

Steps:
1. Look up the source IP using the threat intel API.
2. File a ticket with your findings in the ticketing system.

Do not print or return secret values in your final answer.

OAuth secrets

OAuth tokens follow a different naming convention. The secret name is <provider_id>_oauth and the key is the provider ID in uppercase plus _USER_TOKEN or _SERVICE_TOKEN.

# authorization_code grant (delegated user access)
${{ SECRETS.<provider_id>_oauth.<PROVIDER_ID_UPPER>_USER_TOKEN }}

# client_credentials grant (service-to-service)
${{ SECRETS.<provider_id>_oauth.<PROVIDER_ID_UPPER>_SERVICE_TOKEN }}

In a workflow action:

- ref: query_sentinel
  action: ai.preset_agent
  args:
    preset: sentinel-analyst
    user_prompt: |
      Query Microsoft Sentinel for recent incidents related to this IP:

      ${{ TRIGGER.source_ip }}

Where the sentinel-analyst preset instructions contain:

You are a security triage agent.

When you make HTTP requests to the Microsoft Sentinel API, pass
`${{ SECRETS.microsoft_sentinel_oauth.MICROSOFT_SENTINEL_USER_TOKEN }}`
in the Authorization header as a Bearer token.

Do not print or return secret values in your final answer.

See OAuth integrations for setup and the full list of built-in providers.

Secrets — create and manage workspace secrets
Variables — create and manage workspace variables
Expressions — full expression syntax reference
AI agent — ai.agent and ai.preset_agent reference
OAuth integrations — OAuth setup and providers

Overview

Building automations

Building agents

Building custom actions

Self-hosting

Authentication

Security

Secrets and variables

Overview

Security

Secrets

Variables