Prompt variables

Prompt variables let you embed {{KEY}} placeholders in a hosted agent's system prompt and resolve them at run time — without hardcoding environment-specific values like sheet IDs, API URLs, or tokens directly in the prompt.

---

Defining variables

Open the agent's Settings tab and scroll to Prompt variables. Add one entry per placeholder:

Field	Purpose
Key	Name used in the prompt — write {{KEY}} in the system prompt
Description	Shown in the dashboard and to MCP clients so callers know what to supply
Value	The value substituted into the prompt on every run

Example system prompt:

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

---

How values are resolved

Values are substituted in this priority order:

1. prompt_variables passed at invoke time — highest priority
2. prompt_variables on the schedule — applied on every scheduled run
3. Value set on the variable definition — used for all other invocations

If a placeholder has no value from any of these sources, it is left as-is in the prompt (e.g. {{KEY}} appears literally).

---

Passing values at invoke time

v1 API / SDK

Add prompt_variables to the request body:

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-..."
  }
}

---

Scheduled runs

Set variable values on the agent's Schedule tab under Variable values. They are injected automatically on every scheduled run.

This is the right place for values that are fixed per-deployment but shouldn't be hardcoded in the prompt — for example, a Google Sheet ID that belongs to your workspace.

---

Setting a value in config

If a variable's value is the same for all runs, set it directly in Settings → Prompt variables. It is used whenever no prompt_variables is supplied for that key at invoke time or on the schedule.

---

Troubleshooting

Placeholder not substituted — check the prompt uses double braces ({{KEY}}). Single braces ({KEY}) are not substituted and will appear literally in the prompt.