Prompt variables

Prompt variables let you put {{KEY}} placeholders in a hosted agent's system prompt and fill them in at run time. Use them for values that change per caller or per deployment, such as sheet IDs, API URLs or tokens, instead of hardcoding them in the prompt.

---

Defining variables

Open the agent → Configuration → Brain, expand Advanced settings and find Prompt variables. Add one entry per placeholder, then click Save changes:

Field	Purpose
Key	Name used in the prompt: write {{KEY}} in the system prompt
Description	Tells callers, including MCP clients, what to supply
Value	Optional. Used when a call doesn't pass a value for this key

Keys use uppercase letters, digits and underscores only; the editor converts what you type. There are no built-in variables: only the keys you define (or pass at invoke time) are substituted.

Example system prompt:

Fetch inactive users from {{PRODUCT_API_URL}}/api/v1/users/inactive
using Authorization: Bearer {{PRODUCT_API_TOKEN}}

---

How values are resolved

For each placeholder, AgentOS uses the first value it finds:

1. prompt_variables passed at invoke time
2. Value set on the variable in the agent's configuration

If neither exists, the placeholder stays in the prompt as is (the model sees {{KEY}} literally).

Scheduled runs don't pass prompt_variables, so they use each variable's configured Value.

---

Passing values at invoke time

v1 API / SDK

Add prompt_variables to the request body (SDK: promptVariables in TypeScript, prompt_variables in Python):

curl -X POST https://agentos-ai.dev/api/v1/agents/$AGENT_ID/invoke \
  -H "Authorization: Bearer $AGENTOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": { "task": "run" },
    "prompt_variables": {
      "PRODUCT_API_URL": "https://your-app.com",
      "PRODUCT_API_TOKEN": "sk-..."
    }
  }'

MCP runs_invoke

{
  "agent_id": "...",
  "input": { "task": "run" },
  "prompt_variables": {
    "PRODUCT_API_URL": "https://your-app.com",
    "PRODUCT_API_TOKEN": "sk-..."
  }
}

---

Troubleshooting

Placeholder not substituted. Check that:

• The prompt uses double braces with no spaces: {{KEY}}. {KEY} and {{ KEY }} are left as is.
• The key is uppercase in the prompt. {{key}} is never substituted, even if you pass key or define KEY.
• A value exists for the key, either passed at invoke time or set as the variable's Value. Scheduled runs only have the configured Value.