Skip to content

[AI-163] google_adk_agents: support ToolContext session state in activity_tool - #1683

Open
DABH wants to merge 1 commit into
mainfrom
activity-tool-context-state
Open

[AI-163] google_adk_agents: support ToolContext session state in activity_tool#1683
DABH wants to merge 1 commit into
mainfrom
activity-tool-context-state

Conversation

@DABH

@DABH DABH commented Jul 27, 2026

Copy link
Copy Markdown
Contributor

What was changed

Adds ToolContextSnapshot to temporalio.contrib.google_adk_agents.workflow: a frozen, serializable dataclass carrying the session state (as a plain dict) and the function-call id of an ADK ToolContext.

An activity wrapped with activity_tool can now declare a parameter named tool_context annotated with ToolContextSnapshot:

@activity.defn
async def get_weather(query: str, tool_context: ToolContextSnapshot) -> dict:
    db_url = tool_context.state.get("url", "")
    ...

weather_tool = activity_tool(get_weather, start_to_close_timeout=timedelta(seconds=30))

Exactly like a native ADK function tool's tool_context parameter, it is excluded from the LLM-facing tool schema (ADK reserves the parameter name) and filled in at invocation time — the wrapper snapshots the live ToolContext workflow-side before scheduling the activity. Annotating the parameter with a live ADK context type raises an actionable ValueError at wrap time instead of a serialization failure at runtime.

Why

Closes #1470 (JIRA AI-163). The reporter's tools read configuration seeded into session state (tool_context.state.get("key")), which previously required hand-writing a plain tool function around each activity.

The design follows the constraints laid out in the issue discussion:

  • The live ToolContext never crosses the activity boundary — activity inputs go to the server and may run on a different worker, so only the explicitly-called-out serializable subset is passed, extracted workflow-side before invocation.
  • Nothing leaks into the tool schema — the parameter rides ADK's own tool_context name-reservation, so declarations exclude it on both the legacy and JSON-schema paths.
  • Scoped to ToolContext.state (plus the function-call id), as a single input object so more fields can be added later without breaking activity signatures.
  • One-way by design — mutations inside the activity don't propagate; session-state modifications must happen workflow-side from information the activity returns. Documented in the class docstring and README.

Checklist

  1. Closes [Feature Request] Support ToolContext for ADK function tools #1470
  2. How was this tested: new tests/contrib/google_adk_agents/test_adk_tool_context.py — end-to-end workflow run with max_cached_workflows=0 (state read from a seeded session, default parameter handling, populated function-call id, tool_context mid-signature to prove positional slotting), local-ADK-run parity outside a workflow, schema-exclusion assertions for tools with and without the parameter, and wrap-time rejection of ADK-context / unrelated annotations. Full contrib suite: 23 passed, 5 skipped (pre-existing). pyright/basedpyright/mypy/ruff/pydocstyle clean.
  3. Any docs updates needed: contrib README updated in this PR.

@DABH
DABH requested review from a team as code owners July 27, 2026 20:28
@DABH DABH changed the title google_adk_agents: support ToolContext session state in activity_tool [AI-163] google_adk_agents: support ToolContext session state in activity_tool Jul 27, 2026
…pshot

Activities wrapped with activity_tool could not access the ADK ToolContext:
declaring a tool_context parameter put it in the LLM-facing tool schema and
then failed at runtime trying to serialize the live ToolContext as an
activity argument (#1470).

An activity can now declare a parameter named tool_context annotated with
the new ToolContextSnapshot dataclass. Exactly like a native ADK function
tool's tool_context parameter, it is excluded from the tool schema (ADK
reserves the name) and filled at invocation time — with a serializable
snapshot of the live ToolContext (session state as a plain dict, plus the
function-call id) taken workflow-side before the activity is scheduled. The
live ToolContext never crosses the activity boundary. Annotating the
parameter with an ADK context type raises an actionable error at wrap time
instead of failing at serialization time.

The snapshot is one-way by design: activities may run on different workers,
so session-state modifications must happen workflow-side using information
returned from the activity.

Closes #1470
@DABH
DABH force-pushed the activity-tool-context-state branch from f05c905 to 6b80002 Compare July 27, 2026 20:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature Request] Support ToolContext for ADK function tools

1 participant