Pass context from the client

Context variables let a client tell the agent about the current user or request: a name, an account tier, a locale, or anything else that should shape the response. They are held in session state and are available to the prompt and to tools. This guide shows how to send and use them.

Send context variables in the run request

In a native run request, include context_vars. Each variable has a description, which is the human-readable label the agent sees, and a value, which is the data:

{
  "messages": [
    { "role": "user", "content": "Help me with my order." }
  ],
  "context_vars": [
    { "description": "Customer name", "value": "Alice" },
    { "description": "Account tier", "value": "premium" },
    { "description": "Locale", "value": "en-US" }
  ]
}

See the run request reference for how later runs keep, replace, or clear the stored list.

Read them in the prompt

Loop over context_vars in the system prompt to fold the values into the agent's instructions:

agent "support" {
  graph {
    type = "react"
  }

  prompt = <<-EOT
    You are a customer support agent.

    {%- if context_vars %}
    Context about the customer you are helping:
    {%- for var in context_vars %}
    - {{ var.description }} is {{ var.value }}
    {%- endfor %}
    {%- endif %}
  EOT
}

The {%- if context_vars %} guard skips the block when the state has no context variables. See Write templated prompts for prompt syntax.

Read them in a tool

Context variables are part of the graph state, so a tool that receives a state snapshot can read them too. This is the right place to put information a tool needs about who the user is, for example to branch on their permissions or account tier.

Where to go next

• Write templated prompts: the templating syntax for the prompt.
• Write a tool: read state, including context, inside a tool.
• Runs: the run request shape that carries context variables.