Ability to propagate (http)request-scoped attributes into InvocationContext

[voborl00]

As instances of Runner, Agent and Tool(set) are meant to be long-lived singletons, there seem to be only way how to push some variable into agent's lifecycle which is via Session object into runAsync() method. But Session also seem not to be ideal for this as it lives across many requests, so there goes my question, if is there a way how to propagate request-scoped variable into agent and better into agent's tools (ToolContext?) in order that tool used by agent will have this variable at its disposal for the given runAsync() run? Now i can only (as InvocationContext is constructed inside runAsync() method) push and then remove variable through Session with before/afterToolCallback but its more of a hack than a expected flow I suppose.

[voborl00]

It seems that users of adk-python are also seeking for some support to this functionality: google/adk-python#1746

[Ultroncn]

Short answer: there is no supported way to inject values directly into InvocationContext — the Runner builds it internally for each run, so there is no per-run context object for you to pass in. The supported per-run entry point is the stateDelta parameter on Runner.runAsync:

Map<String, Object> stateDelta = Map.of(
    "temp:request_id", requestId,
    "temp:user_tier", userTier);

runner.runAsync(userId, sessionId, newMessage, runConfig, stateDelta);

(Check the exact overload against the version you use — on current main this is the runAsync(userId, sessionId, newMessage, runConfig, stateDelta) overload, where stateDelta is documented as "Optional map of state updates to merge into the session for this run". The Runner merges it into the session state before the agent runs, so your beforeAgent/beforeTool callbacks and your tools can read it from the state, e.g. toolContext.state().get("temp:request_id").)

One important caveat: stateDelta is not purely request-scoped. It is merged into session.state() and attached to the user-message event, so the values persist in the session after the run — they are session state from then on, not throwaway per-request variables. So use a namespaced temp: prefix, overwrite the key on the next run, and clean it up (or have a callback clear it) when the request is done — otherwise a later request on the same session will still see the previous request's values.

If you need values that must never persist in the session at all, stateDelta is the wrong tool: keep them in your own request-scoped holder on the HTTP layer and read them in a beforeToolCallback (which runs per tool call, inside the invocation). That is still a workaround rather than a framework feature — the same gap is being tracked for ADK Python in google/adk-python#1746, which you linked above.

[Ultroncn]

Hi @voborl00 — following up on my answer from yesterday about propagating request-scoped attributes via the Runner.runAsync(..., stateDelta) overload. Did that approach work for passing your attributes into the session state? If it solved it, marking it as the answer would help others hitting the same wall. If the overload doesn't fit your case, let me know what you tried and I'll look again.