Default Variables

Overview

Every agent run comes with a set of default variables: who started the run, how it arrived, where the caller is, which project the agent belongs to, and how many tokens the run has used so far. You read them in the agent’s prompts with {{ bud.<name> }}.

They work in the system prompt and in prompt messages.
The caller sends nothing extra. Bud fills them on the server from the request’s credentials, network address and entry path.
A value that does not apply to a run (for example the trigger fields on an API call) renders as an empty string.

Use them in a prompt

Write the variables into the prompt like any other template variable. This system prompt:

You are the support assistant for Acme.

{% if bud.user_country == "IN" %}
Quote prices in INR.
{% else %}
Quote prices in USD.
{% endif %}

The customer is in {{ bud.city | default("an unknown city", true) }} ({{ bud.timezone }}).
Their local time is {{ bud.local_time }}.

reaches the model like this for an API call from Chennai:

You are the support assistant for Acme.

Quote prices in INR.

The customer is in Chennai (Asia/Kolkata).
Their local time is 2026-10-07T15:41:35+05:30.

Your own prompt variables ({{ customer_name }}) are rendered in the same pass, so you can mix both freely.

Add them in the agent builder

Open the agent and click the System Prompt node.
Click Expand system prompt and stay on the System Prompt tab.
Type {{ bud. — a Governance context list opens with every variable and a short description.
Keep typing to filter, then pick one with the arrow keys and Enter (or click it).
Click Save.

In the Prompt Message tab, type the variable by hand, for example {{ bud.city }}.

Call the agent

Nothing changes in the request. Call the agent as usual and Bud fills the values:

curl https://<gateway>/v1/responses \
  -H "Authorization: Bearer $BUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": {"id": "my-agent"},
    "input": "What is the price of the Pro plan?"
  }'

To see exactly what an agent receives, add a block like this to its system prompt while you test, then ask the agent to repeat it:

user_type: {{ bud.user_type }}
channel: {{ bud.channel }}
client_type: {{ bud.client_type }}
user_country: {{ bud.user_country }}
region: {{ bud.region }}
city: {{ bud.city }}
timezone: {{ bud.timezone }}
continent: {{ bud.continent }}
local_time: {{ bud.local_time }}
principal: {{ bud.principal }}
project_id: {{ bud.project_id }}
trigger_origin: {{ bud.trigger_origin }}
connection_id: {{ bud.connection_id }}
provider: {{ bud.provider }}
recursion_depth: {{ bud.recursion_depth }}
tokens_so_far: {{ bud.tokens_so_far }}
cost_so_far: {{ bud.cost_so_far }}

Variable reference

Variable	What it holds	Example
`bud.user_type`	Who started the run: `end_user`, `agent`, `trigger` or `channel`	`end_user`
`bud.channel`	How the run arrived: `api`, `a2a`, `trigger` or `channel`	`api`
`bud.client_type`	The caller’s `User-Agent` header, trimmed and limited to 512 characters	`my-app/1.4`
`bud.user_country`	Country of the caller’s IP address, as an ISO 3166-1 alpha-2 code	`IN`
`bud.region`	State or region of the caller’s IP address, as its subdivision code (its name when there is no code)	`TN`
`bud.city`	City of the caller’s IP address, in English	`Chennai`
`bud.timezone`	Time zone of the caller’s IP address, as an IANA name	`Asia/Kolkata`
`bud.continent`	Continent code: `AF`, `AN`, `AS`, `EU`, `NA`, `OC` or `SA`	`AS`
`bud.local_time`	The caller’s local time when the request arrived, ISO 8601 to the second with UTC offset	`2026-10-07T15:41:35+05:30`
`bud.principal`	Who invoked the run: your Bud user ID, the event’s actor, or the chat user	`U04ABCD1234`
`bud.project_id`	The ID of the project the agent belongs to	`9b2f7c1a-4d3e-4b8a-9f6e-2c1d0a7b5e43`
`bud.trigger_origin`	The event that started a trigger run	`issues.opened`
`bud.connection_id`	The event connection that delivered the event or chat message	`conn_0192c3d4e5f67a8b9c0d1e2f3a4b5c6d`
`bud.provider`	The platform the event or chat message came from	`github`
`bud.tokens_so_far`	Input and output tokens used by this run’s model calls so far (a number)	`792`
`bud.cost_so_far`	Cost of this run’s model calls so far, in USD at public list prices (a number)	`0.0042`
`bud.recursion_depth`	How deep the run is in a chain of agents calling agents (a number; `0` at the top)	`1`

Values by entry path

What each variable holds depends on how the agent was started.

#	Variable	API key	Studio / Playground	Background (`background: true`)	Sub-agent (A2A)	Trigger	Bot chat
1	`user_type`	`end_user`	`end_user`	`end_user`	`agent`	`trigger`	`channel`
2	`channel`	`api`	`api`	`api`	`a2a`	`trigger`	`channel`
3	`client_type`	Caller’s User-Agent	Playground server’s User-Agent	As submitted	Empty	Empty	Empty
4	`user_country`	From the caller’s IP	From the Playground server’s IP	As submitted	Empty	Empty	Empty
5	`region`	From the caller’s IP	From the Playground server’s IP	As submitted	Empty	Empty	Empty
6	`city`	From the caller’s IP	From the Playground server’s IP	As submitted	Empty	Empty	Empty
7	`timezone`	From the caller’s IP	From the Playground server’s IP	As submitted	Empty	Empty	Empty
8	`continent`	From the caller’s IP	From the Playground server’s IP	As submitted	Empty	Empty	Empty
9	`local_time`	When the request arrived	When the request arrived, in the Playground server’s time zone	When the request was submitted	Empty	Empty	Empty
10	`principal`	Empty	Your Bud user ID	As submitted	Empty	The event actor’s ID on the provider	The chat user’s platform ID
11	`project_id`	Agent’s project	Agent’s project	Agent’s project	Sub-agent’s project	Agent’s project	Agent’s project
12	`trigger_origin`	Empty	Empty	Empty	Empty	Event type	Empty
13	`connection_id`	Empty	Empty	Empty	Empty	Connection ID	Connection ID
14	`provider`	Empty	Empty	Empty	Empty	`github`, `linear`, …	`slack`, `teams`, …
15	`tokens_so_far`	`0`, then live	`0`, then live	`0`, then live	`0`, then live (its own calls only)	`0`, then live	`0`, then live
16	`cost_so_far`	Empty, then live	Empty, then live	Empty, then live	Empty, then live (its own calls only)	Empty, then live	Empty, then live
17	`recursion_depth`	`0`	`0`	`0`	`1` (`2` for a sub-agent’s sub-agent)	`0`	`0`

API key — a /v1/responses call authenticated with an API key. principal is empty because a key is not a person.
Studio / Playground — testing the agent while signed in. The Playground server sends the request to the gateway on your behalf, so the location values and client_type describe that server, not your browser, and the location values can be empty.
Background — a /v1/responses call with background: true. The values are captured when the request is submitted and reused when the run executes, so local_time is the submission time even if the run starts later. principal is your user ID when you submit while signed in, and empty for an API key.
Sub-agent (A2A) — the agent is called by another agent as a tool. It reports its own project and counts only its own model calls; the calling agent’s usage is not included.
Trigger — an event from an event connection starts the run. trigger_origin is the provider’s event, such as issues.opened or pull_request.closed for GitHub and Issue.create for Linear. principal is the actor’s ID on that provider, for example the GitHub user’s numeric ID.
Bot chat — a message to the agent in Slack or Teams. principal is the chat user’s ID on that platform, such as a Slack U… ID.

Every /v1/responses call reports channel as api, including calls from Studio and the Playground. Each turn of a conversation is a separate request: the values are filled again and the counters start from zero.

To try prompts that use location or client_type, call the agent through the API from the client you care about rather than from the Playground.

Location values

user_country, region, city, timezone and continent come from the caller’s public IP address, looked up in the IP location database bundled with the gateway (MaxMind GeoLite2 City). local_time is the current time in that timezone.

Only the fields the database knows are filled; the rest stay empty. Many addresses are known only at country level, which is common for VPNs, mobile networks and cloud or anycast addresses. For example, 8.8.8.8 gives US, America/Chicago and NA with no region or city.
Private and internal addresses are never looked up, so their location values are empty.
region is the code of the state or region within the country, such as TN for Tamil Nadu, not the full name.

Live counters

tokens_so_far and cost_so_far change while the run is in progress. When an agent calls tools, it makes several model calls in one run, and each call sees the totals of the calls before it:

Tokens used so far: {{ bud.tokens_so_far }}

Model call	What the model sees
First call	`Tokens used so far: 0`
Call after a tool result	`Tokens used so far: 792`

The stored conversation and the response’s instructions keep the text from the start of the run. Traces show the text each model call actually received.
The counters cover one request. A new turn of a conversation, and a sub-agent’s run, start from zero.
tokens_so_far counts input and output tokens.
cost_so_far uses public list prices in USD, so it is an estimate, not your bill. It stays empty until a call can be priced, and stays empty for models without a public price.
Very small costs print in scientific notation (1.23e-05). Format them for the model with {{ "%.6f" | format(bud.cost_so_far) if bud.cost_so_far else "n/a" }}.

A common use is a budget guard:

{% if bud.cost_so_far and bud.cost_so_far > 0.05 %}
You are close to this run's budget. Finish the task now and summarise what is left.
{% endif %}

Empty values and safe templates

A value that is missing renders as an empty string. Write templates that still read well when it is.

Give a fallback with default(..., true) or or. The true matters: without it, default leaves an empty value unchanged.
{{ bud.city | default("unknown", true) }} {{ bud.city or "unknown" }}

Branch on a value with {% if %}:

{% if bud.user_type == "channel" %}
Keep replies short; this is a chat conversation.
{% endif %}

{% if bud.recursion_depth >= 2 %}
Do not call other agents.
{% endif %}

Check spelling. A name that is not in the list above, such as {{ bud.citty }}, also renders as an empty string, with no error.

Comparing an empty cost_so_far with a number fails the request with Template rendering failed. It is empty at the start of every run, so always check it first: {% if bud.cost_so_far and bud.cost_so_far > 0.5 %}. tokens_so_far and recursion_depth are always numbers and are safe to compare.

Reserved names

bud, ctx, headers and meta are reserved, including any dotted name that starts with them (such as bud.city). You cannot use them as names for your own input variables; the agent builder marks such a variable as a reserved name and will not save until you rename it. A plain {{ city }} is an ordinary input variable that the caller fills, not the default value. Use {{ bud.city }} for the value Bud provides.

Limits

Default variables are rendered in the system prompt and prompt messages only. The request’s input, tool descriptions and input/output schemas are passed through as written.
client_type is whatever User-Agent the caller sends. Use it to adapt the reply, not to make security decisions.
local_time is fixed when the request arrives and does not advance during a long run.
In background runs, default variables are rendered in plain-text prompt messages only, not in messages that contain images or files.

Next Steps

Version Management

Roll out prompt changes that use default variables safely.

Context Compaction

Keep long agent conversations inside the context window.

Event Connections

Start agents from events and fill the trigger variables.

Create a Response

Call an agent through the Responses API.

Getting Started

Projects

Models

Deployments

Pipelines

Connectors

MCP Foundry

Router

Clusters

API Integration

Playground

Observability

Dashboard

Prompts & Agents

Evaluations

Guardrails

API Keys & Security

User Management

Customer Dashboard

Settings

Overview

Use them in a prompt

Add them in the agent builder

Call the agent

Variable reference

Values by entry path

Location values

Live counters

Empty values and safe templates

Reserved names

Limits

Next Steps

Version Management

Context Compaction

Event Connections

Create a Response

​Overview

​Use them in a prompt

​Add them in the agent builder

​Call the agent

​Variable reference

​Values by entry path

​Location values

​Live counters

​Empty values and safe templates

​Reserved names

​Limits

​Next Steps

Version Management

Context Compaction

Event Connections

Create a Response

Overview

Use them in a prompt

Add them in the agent builder

Call the agent

Variable reference

Values by entry path

Location values

Live counters

Empty values and safe templates

Reserved names

Limits

Next Steps