Skip to content

feat(mcp): let to_mcp_server carry the conversation on an explicit session_id - #8164

Open
Shanmukh-l33t wants to merge 1 commit into
google:mainfrom
Shanmukh-l33t:feat/8161-mcp-explicit-session-id
Open

Shanmukh-l33t wants to merge 1 commit into
google:mainfrom
Shanmukh-l33t:feat/8161-mcp-explicit-session-id

Conversation

@Shanmukh-l33t

Copy link
Copy Markdown

Fixes #8161.

Problem

to_mcp_server keys the ADK session on the MCP connection (_connection_key
reads the session object behind ctx). That holds while one connection carries
one conversation. It does not hold when the connection is not stable:

  • a stateless streamable HTTP deployment, where every POST gets a fresh
    connection;
  • several server instances behind a load balancer or on Cloud Run;
  • an MCP protocol revision that neither performs initialize nor sends an
    Mcp-Session-Id header.

In all three cases every tool call creates a new ADK session and the agent loses
the conversation between turns, even with a persistent session service such as
VertexAiSessionService.

Mechanism

Implemented the mechanism requested in the issue: the host names its own
conversation instead of relying on the connection.

  • to_mcp_server(..., session_id_arg=True) opts in. Default is False, so
    nothing changes for existing callers.
  • The generated tool then takes session_id: str | None = None. When an id is
    passed and it resolves in runner.session_service.get_session, that session
    is reused; otherwise a new one is created, matching the issue's "reuse it if
    it exists, else create".
  • The response carries the id it ran in as structuredContent: {"session_id": ...}, so the host can pass it back on the next call. An unknown or expired id
    starts a new conversation and the host learns the new id from the response.
  • The tool description gains the sentence the issue proposed, so the host model
    knows to reuse the id. Wording: "Pass back the returned session_id on every
    later call of the same conversation. Omit it to start a new one."
  • With the flag on, the per-connection map, its locks, and the orphan reaper are
    not created: the host owns the session lifetime, so ADK does not delete a
    session out from under it.

_run_agent gained an optional session_id that takes precedence over the
per-connection lookup, which keeps the existing path untouched when it is not
passed.

One note on the id: it is the only handle on the conversation, so any caller
that knows it joins that conversation. This is documented on the parameter and
in the guide, and it is part of why the feature is opt-in.

Backward compatibility

With session_id_arg unset, behavior is byte for byte what it was: same tool
schema (request only), same per-connection session reuse, same orphan reaping,
same returned content, no structured content. A test pins that shape.

Testing

python -m pytest -q tests/unittests/tools/mcp_tool/test_agent_to_mcp.py run
against both supported MCP SDK majors (mcp 2.3.0 and mcp 1.24.0): 32 passed
on each.

The new tests, on unmodified main (feature absent), fail:

FAILED tests/unittests/tools/mcp_tool/test_agent_to_mcp.py::test_session_id_arg_can_be_omitted_to_start_a_conversation
FAILED tests/unittests/tools/mcp_tool/test_agent_to_mcp.py::test_session_id_arg_reuses_the_returned_session
FAILED tests/unittests/tools/mcp_tool/test_agent_to_mcp.py::test_session_id_arg_shares_the_conversation_across_connections
FAILED tests/unittests/tools/mcp_tool/test_agent_to_mcp.py::test_session_id_arg_starts_over_for_an_unknown_session_id
FAILED tests/unittests/tools/mcp_tool/test_agent_to_mcp.py::test_session_id_arg_does_not_key_on_the_connection
FAILED tests/unittests/tools/mcp_tool/test_agent_to_mcp.py::test_session_id_arg_leaves_orphan_reaping_to_the_host
FAILED tests/unittests/tools/mcp_tool/test_agent_to_mcp.py::test_session_id_arg_keeps_agent_history_across_calls
7 failed, 1 passed, 24 deselected

(TypeError: to_mcp_server() got an unexpected keyword argument 'session_id_arg' on each. The one that passes is the backward compatibility
test, which asserts the old shape and should pass on both sides.)

With the change, tests/unittests/tools/mcp_tool/test_agent_to_mcp.py: 32
passed. Whole directory: 496 passed, 1 failed
(test_google_auth_async_transport_forwards_env_proxy, a ModuleNotFoundError
from a package missing in this environment, unrelated to the change).

The end to end test uses a real Runner and InMemorySessionService with an
agent that reports how many user turns its session holds. Two calls that pass
the returned id answer turn 1 then turn 2; the same two calls without an id
would both answer turn 1.

Files

  • src/google/adk/tools/mcp_tool/_agent_to_mcp.py: the flag, the tool
    signature, the session resolution, and _tool_result.
  • tests/unittests/tools/mcp_tool/test_agent_to_mcp.py: eight tests (schema,
    reuse within one connection, reuse across a reconnect, unknown id, no
    connection keying, no reaping, unchanged default shape, real runner history).
  • docs/guides/tools/mcp_tool/agent_to_mcp/index.md: option row and a
    paragraph under session continuity.

An MCP host that cannot hold a connection, or speaks a protocol revision
without initialize and Mcp-Session-Id, loses the ADK session on every tool
call, so each turn starts from scratch. Add an opt-in session_id_arg that
makes the tool take an optional session_id and return the id it ran in, so
the host names its own conversation.
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.

to_mcp_server: support explicit session_id to keep multi-turn conversation

2 participants