✨ Feature: Pass user context to MCP tools and A2A agents for tool-side authorization

[EDDIWARD]

Summary

Pass the caller's user information (tenant name, user name/account, user groups) through to MCP tools and external A2A agents according to each tool's declaration, so tools can authorize on their own before accessing data. The platform performs no authorization itself — it only forwards the authenticated session identity.

1. Conventional fields: when an MCP tool's inputSchema declares any of tenant_id / tenant_name / user_id / user_name / user_account / user_groups, the platform injects the current caller's values at call time. Undeclared fields are never injected and existing tool parameters stay untouched.
2. Hidden from the model: the conventional fields are removed from the model-visible schema, so the model neither sees nor fills them; injected values come only from the authenticated session and cannot be forged via prompt input.
3. External A2A agents receive the user context in the request metadata.user_context.
4. Conditional build & graceful degradation: the context is built only when the agent tree contains MCP tools or external A2A agents (pure local/builtin tool runs make zero extra DB lookups); any lookup failure degrades to a minimal or absent context and never blocks the conversation.
5. User docs added in both languages (agent-development/agent-configuration: "Pass User Information to Tools (Tool-side Authorization)" / 「向工具透传用户信息（工具侧鉴权）」).

Before / After (payload-level comparison, no UI involved)

MCP tool call — example tool query_sales_data declares user_account and user_groups in its inputSchema for data authorization:

Before — the conventional fields are visible to the model, and whatever arguments the model generates reach the MCP server as-is (a tool needing caller identity gets none):

model-visible inputs : ["query", "user_account", "user_groups"]
call_tool arguments  : {"query": "show Q3 sales"}

After — the conventional fields are hidden from the model; the platform wraps the tool and appends the session-resolved values right before execution:

model-visible inputs : ["query"]
call_tool arguments  : {
  "query": "show Q3 sales",
  "user_account": "bug-admin@qq.com",
  "user_groups": ["Default Group"]
}

External A2A agent request metadata:

Before:

payload.metadata = {}

After:

payload.metadata = {
  "user_context": {
    "tenant_id": "9440214e-...",
    "tenant_name": "bug-repro",
    "user_id": "user-0001",
    "user_name": "bug-admin@qq.com",
    "user_account": "bug-admin@qq.com",
    "user_groups": ["Default Group"]
  }
}

Why

Tools that access tenant/user-scoped data previously had no reliable way to know who is calling — they could only use static, tenant-level credentials configured on the MCP connection. With this change, tools can enforce their own per-user/per-group data authorization using identity that is guaranteed to come from the authenticated session (never from model output), while the platform stays out of the authorization decision itself.

Validation

• Unit tests: 19 new cases covering injection / hiding-from-model / declared-only injection / sync & async forwards / idempotency / non-dict schema guard / per-field lookup degradation / conditional build — all passing locally (test_tool_user_context.py, TestBuildToolUserContext, TestAgentTreeNeedsUserContext, TestResolveToolUserContext, A2A wrapper metadata tests).
• Existing tests unaffected: exact-call assertions updated for the new user_context kwarg (test_run_agent.py, test_create_agent_info.py); full files re-run locally with no regressions.
• CI on latest commit: automated unit tests, CodeQL (actions / javascript-typescript / python), SonarCloud, docs check and all multi-arch image builds green; codecov patch coverage gate passed.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!