Secrets and variables

Pass Tracecat secrets and workspace variables to preset agent tool calls securely: scope credentials per agent run and inject values without exposing them to the model.

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.

ai.action and ai.agent actions do not support secure secrets injection. Secret and variable expressions are evaluated immediately in workflow action inputs and will be exposed to the LLM.

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.

Secrets and variables

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.

Related pages

• 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