Give an agent context about the current user

An agent that looks up orders needs to know whose orders. Rather than hard-coding anything, you put placeholders in the tool's configuration and supply the values at runtime.

Placeholders

In an API tool, you can use {{...}} placeholders in the URL, in any header, and in the request body. They use dot notation, and several roots are available.

• {{context.anything}} — values you pass in from your app. This is the one you control.

• {{session.userId}}, and likewise email, phone, name and customData — the identified contact, with no work on your side.

• {{ticket.id}}, plus title, status, priority, type and formData — the ticket the agent is working on.

• {{params.x}} — the parameters the agent itself filled in.

• {{auth.token}} — a per-user token you supply through the SDK's auth object. Stored server-side and never shown to the AI.

If you identify your users, {{session.userId}} already gives you the current user. You only need your own context values for things Gleap doesn't know — a tenant ID, an account number.

Passing values from your app

When you open an agent, pass a context object:

Gleap.startAgent("YOUR_AGENT_ID", {
  context: { tenantId: "acme-42" }
});

For a headless call the same values go under additionalContext:

const { response } = await Gleap.sendAgentMessage(
  "YOUR_AGENT_ID",
  "Where is my order?",
  { additionalContext: { tenantId: "acme-42" } }
);

The keys you use in the placeholders are the keys you pass here. The agent's SDK panel lists the ones it detected in your tools, so you can see what it expects.

A missing value becomes “null”

This is the behaviour worth knowing before it costs you an afternoon. If a placeholder has no matching value, it isn't left in place and doesn't raise an error — it is replaced with the literal four-character string null.

So a header meant to carry an account ID arrives at your API as the text "null", and your endpoint sees a syntactically valid request with nonsense in it. Whatever error comes back gets handed to the agent, which then tries to explain a failure it has no real information about.

Validate these values at your own endpoint and return a clear error when one is missing or invalid. A precise message travels back to the agent and it can say something sensible instead of guessing.

What not to pass

Context supplied through the SDK is injected into the agent's prompt and comes from the user's own browser or device — so treat it as visible to them and as something they could alter. Don't put an API key or a long-lived secret in it.

For a token that must call your API as the current user, use the SDK's auth object instead of context: auth.token is stored server-side, never shown to the AI, and reaches your tools as {{auth.token}}. For static service credentials, use the tool's own headers — those are stored with the tool and never leave the server. Keep any token you do pass short-lived and scoped to that user.

Never rely on a context value alone to decide what a caller may see. Verify server-side that the authenticated user is entitled to the record being requested — the same rule as any other client-supplied parameter.