Skip to content

Commit 14fe593

Browse files
committed
adk/mcp: defer tool discovery until invocation
\# Description Slow MCP discovery can exceed router timeouts and fail agent resumes, holding worker reservations and capacity while startup waits. This fixes it by: - Deferring MCP connections and classification until invocation preparation. - Omitting unclassified toolsets for the execution and retrying on later executions. - Preserving app-only filtering and MCP App results across runtime restores. - Covering readiness, discovery failures, recovery, and result preservation. \# Change Type ``` /kind fix ``` \# Changelog ```release-note MCP discovery no longer delays agent startup or resume, and failed classification keeps tools hidden. ``` \# Additional Notes Signed-off-by: Shashank Ram <[email protected]>
1 parent 2e2acf5 commit 14fe593

14 files changed

Lines changed: 1135 additions & 88 deletions

File tree

‎docs/architecture/mcp.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -75,3 +75,34 @@ not protected: registering a name or URI core already uses replaces it.
7575
Authorization inside an added tool stays with the program that adds it.
7676

7777
The implementation is in [`go/core/internal/mcp`](../../go/core/internal/mcp).
78+
79+
## Go ADK runtime discovery
80+
81+
The Go ADK builds lazy MCP toolsets for the root agent and its subagents. Runtime
82+
startup neither connects to HTTP or SSE MCP servers nor starts stdio MCP
83+
processes. Readiness and Actor resume therefore do not wait for remote tool
84+
discovery.
85+
86+
During invocation preparation, the runtime first classifies every page of the
87+
server's `tools/list` response. The resulting filter combines configured tool
88+
allowlists with MCP Apps visibility: app-only tools are excluded from the model.
89+
Only after classification succeeds does ADK discover its executable tools,
90+
using the same advertised Apps capabilities. MCP App result compaction reads
91+
the classified metadata during model preparation, preserving rich results in
92+
chat history for UI rendering.
93+
94+
A successful classification is cached for the runtime process lifetime. A
95+
volume-only restore starts a new process, so classification happens again after
96+
readiness. Classification uses invocation credentials through the existing MCP
97+
transport; the cache does not replace authorization on tool requests.
98+
99+
If classification fails, that server's entire toolset is omitted for the current
100+
A2A execution, including subsequent model steps and subagent calls. A later
101+
execution retries, including an approval continuation with reused invocation
102+
identifiers. There is no fallback to unclassified tools. Cancellation and ADK
103+
discovery errors after successful classification still propagate.
104+
105+
Standalone runners can use `mcp.WithDiscoveryScope(ctx)` for each `runner.Run`
106+
to get the same omission and retry behavior. Without that scope, classification
107+
failure returns an error. Controller-side catalog discovery used by the UI is
108+
independent of runtime discovery.

‎go/adk/examples/oneshot/main.go‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ import (
2727

2828
"github.com/kagent-dev/kagent/go/adk/pkg/agent"
2929
"github.com/kagent-dev/kagent/go/adk/pkg/config"
30+
"github.com/kagent-dev/kagent/go/adk/pkg/mcp"
3031
"github.com/kagent-dev/kagent/go/pkg/logging"
3132
)
3233

@@ -106,7 +107,7 @@ func main() {
106107
streamMode = adkagent.StreamingModeSSE
107108
}
108109

109-
for ev, err := range r.Run(ctx, "user", sess.Session.ID(), content, adkagent.RunConfig{
110+
for ev, err := range r.Run(mcp.WithDiscoveryScope(ctx), "user", sess.Session.ID(), content, adkagent.RunConfig{
110111
StreamingMode: streamMode,
111112
}) {
112113
if err != nil {

‎go/adk/pkg/a2a/executor.go‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ import (
2222
"google.golang.org/genai"
2323

2424
"github.com/kagent-dev/kagent/go/adk/pkg/auth"
25+
"github.com/kagent-dev/kagent/go/adk/pkg/mcp"
2526
"github.com/kagent-dev/kagent/go/adk/pkg/models"
2627
"github.com/kagent-dev/kagent/go/adk/pkg/telemetry"
2728
apia2a "github.com/kagent-dev/kagent/go/api/a2a"
@@ -264,6 +265,7 @@ func (e *KAgentExecutor) Execute(ctx context.Context, reqCtx *a2asrv.ExecutorCon
264265

265266
ctx = context.WithValue(ctx, publicContextIDKey{}, reqCtx.ContextID)
266267
ctx = withBearerToken(ctx)
268+
ctx = mcp.WithDiscoveryScope(ctx)
267269
// The synthetic ADK user ID is only a native session lookup key. Memory
268270
// and outgoing credentials must receive only the passed-through caller.
269271
ctx = auth.WithUserID(ctx, trustedUserID)
Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
package a2a
2+
3+
import (
4+
"context"
5+
"errors"
6+
"log/slog"
7+
"net/http"
8+
"net/http/httptest"
9+
"sync/atomic"
10+
"testing"
11+
12+
a2atype "github.com/a2aproject/a2a-go/v2/a2a"
13+
"github.com/a2aproject/a2a-go/v2/a2asrv"
14+
mcpsdk "github.com/modelcontextprotocol/go-sdk/mcp"
15+
"github.com/stretchr/testify/require"
16+
adkagent "google.golang.org/adk/v2/agent"
17+
18+
"github.com/kagent-dev/kagent/go/adk/pkg/mcp"
19+
configv1 "github.com/kagent-dev/kagent/go/api/gen/kagent/config/v1"
20+
)
21+
22+
func TestKAgentExecutorScopesMCPDiscoveryFailures(t *testing.T) {
23+
// Given a temporarily unavailable MCP catalog, when execution continues and
24+
// later resumes with reused IDs, assert that omission lasts only one execution.
25+
var unavailable atomic.Bool
26+
unavailable.Store(true)
27+
var listings atomic.Int32
28+
server := mcpsdk.NewServer(&mcpsdk.Implementation{Name: "execution-discovery", Version: "1"}, &mcpsdk.ServerOptions{
29+
SupportedProtocolVersions: []string{"2025-11-25"},
30+
})
31+
mcpsdk.AddTool(server, &mcpsdk.Tool{Name: "available_tool"}, func(context.Context, *mcpsdk.CallToolRequest, map[string]any) (*mcpsdk.CallToolResult, map[string]any, error) {
32+
return nil, map[string]any{"result": "ok"}, nil
33+
})
34+
server.AddReceivingMiddleware(func(next mcpsdk.MethodHandler) mcpsdk.MethodHandler {
35+
return func(ctx context.Context, method string, req mcpsdk.Request) (mcpsdk.Result, error) {
36+
if method == "tools/list" {
37+
listings.Add(1)
38+
if unavailable.Load() {
39+
return nil, errors.New("catalog temporarily unavailable")
40+
}
41+
}
42+
return next(ctx, method, req)
43+
}
44+
})
45+
httpServer := httptest.NewServer(mcpsdk.NewStreamableHTTPHandler(func(*http.Request) *mcpsdk.Server { return server }, &mcpsdk.StreamableHTTPOptions{Stateless: true}))
46+
t.Cleanup(httpServer.Close)
47+
toolsets := mcp.CreateToolsets(t.Context(), []*configv1.ADKHTTPMCPServerConfig{{
48+
Params: &configv1.ADKHTTPConnectionParams{Url: httpServer.URL},
49+
}}, nil, nil, false, nil)
50+
require.Len(t, toolsets, 1)
51+
52+
var visible [][]string
53+
builtin := &recordingExecutor{onExecute: func(ctx context.Context) {
54+
readonly := &executionDiscoveryContext{StrictContextMock: adkagent.NewStrictContextMock(ctx)}
55+
for range 2 {
56+
tools, err := toolsets[0].Tools(readonly)
57+
require.NoError(t, err, "discovery failures must leave the execution usable")
58+
names := make([]string, 0, len(tools))
59+
for _, tool := range tools {
60+
names = append(names, tool.Name())
61+
}
62+
visible = append(visible, names)
63+
unavailable.Store(false)
64+
}
65+
}}
66+
executor := &KAgentExecutor{builtin: builtin, logger: slog.New(slog.DiscardHandler)}
67+
request := &a2asrv.ExecutorContext{
68+
TaskID: "reused-task", ContextID: "reused-session",
69+
Message: a2atype.NewMessage(a2atype.MessageRoleUser, a2atype.NewTextPart("continue")),
70+
}
71+
for _, err := range executor.Execute(t.Context(), request) {
72+
require.NoError(t, err)
73+
}
74+
require.Equal(t, [][]string{{}, {}}, visible, "recovery during an execution must not retry its omitted server")
75+
require.EqualValues(t, 1, listings.Load())
76+
77+
visible = nil
78+
for _, err := range executor.Execute(t.Context(), request) {
79+
require.NoError(t, err)
80+
}
81+
require.Equal(t, [][]string{{"available_tool"}, {"available_tool"}}, visible, "a later execution with the same IDs must retry discovery")
82+
require.Greater(t, listings.Load(), int32(1))
83+
}
84+
85+
type executionDiscoveryContext struct {
86+
adkagent.StrictContextMock
87+
}
88+
89+
func (*executionDiscoveryContext) InvocationID() string { return "reused-invocation" }
90+
func (*executionDiscoveryContext) SessionID() string { return "reused-session" }

‎go/adk/pkg/a2a/executor_test.go‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,7 @@ type recordingExecutor struct {
4040
userID string
4141
cleanupCalled bool
4242
events []a2atype.Event
43+
onExecute func(context.Context)
4344
// span, when set, is a span the turn emits, the way ADK does.
4445
span string
4546
}
@@ -48,6 +49,9 @@ func (e *recordingExecutor) Execute(ctx context.Context, reqCtx *a2asrv.Executor
4849
return func(yield func(a2atype.Event, error) bool) {
4950
e.message = reqCtx.Message
5051
e.userID = auth.UserIDFromContext(ctx)
52+
if e.onExecute != nil {
53+
e.onExecute(ctx)
54+
}
5155
if e.span != "" {
5256
_, span := otel.Tracer("adk-test").Start(ctx, e.span)
5357
span.End()
Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
package server
2+
3+
import (
4+
"context"
5+
"io"
6+
"log/slog"
7+
"net"
8+
"net/http"
9+
"net/http/httptest"
10+
"os"
11+
"path/filepath"
12+
"sync/atomic"
13+
"testing"
14+
"time"
15+
16+
a2atype "github.com/a2aproject/a2a-go/v2/a2a"
17+
"github.com/stretchr/testify/require"
18+
"google.golang.org/protobuf/types/known/durationpb"
19+
20+
kagentagent "github.com/kagent-dev/kagent/go/adk/pkg/agent"
21+
configv1 "github.com/kagent-dev/kagent/go/api/gen/kagent/config/v1"
22+
)
23+
24+
func TestReadinessDoesNotWaitForMCPDiscovery(t *testing.T) {
25+
t.Setenv("OPENAI_API_KEY", "test-key")
26+
t.Run("Given slow MCP servers and MCP-bound subagents, when the runtime starts, assert that readiness precedes discovery", func(t *testing.T) {
27+
var requests atomic.Int32
28+
mcpServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
29+
requests.Add(1)
30+
select {
31+
case <-time.After(500 * time.Millisecond):
32+
case <-r.Context().Done():
33+
}
34+
http.Error(w, "slow server", http.StatusServiceUnavailable)
35+
}))
36+
t.Cleanup(mcpServer.Close)
37+
marker := filepath.Join(t.TempDir(), "stdio-started")
38+
config := func(name string) *configv1.ADKAgentConfig {
39+
return &configv1.ADKAgentConfig{
40+
Name: name, Instruction: "Use the configured tools.", SkillsDirectory: t.TempDir(),
41+
Model: &configv1.ADKModelConfig{Model: "test-model", Provider: &configv1.ADKModelConfig_Openai{Openai: &configv1.ADKOpenAI{}}},
42+
HttpTools: []*configv1.ADKHTTPMCPServerConfig{{Params: &configv1.ADKHTTPConnectionParams{Url: mcpServer.URL, Timeout: durationpb.New(time.Second)}}},
43+
SseTools: []*configv1.ADKSSEMCPServerConfig{{Params: &configv1.ADKSSEConnectionParams{Url: mcpServer.URL, Timeout: durationpb.New(time.Second)}}},
44+
}
45+
}
46+
rootConfig := config("root")
47+
rootConfig.StdioTools = []*configv1.ADKStdioMCPServerConfig{{Command: "touch", Args: []string{marker}}}
48+
rootConfig.SubAgents = []*configv1.ADKAgentConfig{config("child")}
49+
_, err := kagentagent.CreateGoogleADKAgent(t.Context(), &configv1.ADKConfig{Agent: rootConfig}, "root", nil)
50+
require.NoError(t, err)
51+
srv, err := NewA2AServer(a2atype.AgentCard{}, substrateExecutor{}, slog.New(slog.DiscardHandler), ServerConfig{Host: "127.0.0.1", Port: "0"})
52+
require.NoError(t, err)
53+
listener, err := net.Listen("tcp", "127.0.0.1:0")
54+
require.NoError(t, err)
55+
srv.readyServer.Addr = listener.Addr().String()
56+
require.NoError(t, listener.Close())
57+
require.NoError(t, srv.Start())
58+
t.Cleanup(func() {
59+
ctx, cancel := context.WithTimeout(context.Background(), time.Second)
60+
defer cancel()
61+
require.NoError(t, srv.httpServer.Shutdown(ctx))
62+
require.NoError(t, srv.readyServer.Shutdown(ctx))
63+
srv.grpcServer.Stop()
64+
})
65+
client := &http.Client{Timeout: time.Second}
66+
resp, err := client.Get("http://" + srv.readyServer.Addr + "/readyz")
67+
require.NoError(t, err)
68+
_, err = io.Copy(io.Discard, resp.Body)
69+
require.NoError(t, err)
70+
require.NoError(t, resp.Body.Close())
71+
require.Equal(t, http.StatusOK, resp.StatusCode)
72+
require.Zero(t, requests.Load(), "root and subagent MCP connections must be deferred")
73+
_, err = os.Stat(marker)
74+
require.ErrorIs(t, err, os.ErrNotExist, "stdio process must not start before readiness")
75+
})
76+
}

‎go/adk/pkg/agent/agent.go‎

Lines changed: 5 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -98,7 +98,6 @@ func createGoogleADKAgent(ctx context.Context, agentConfig *configv1.ADKAgentCon
9898
log.InfoContext(ctx, "wired local skills", "skills_directory", skillsDirectory, "skill_count", len(skills))
9999
}
100100
}
101-
mcpAppToolNames := mcp.MCPAppToolNamesFromToolsets(toolsets)
102101

103102
var remoteAgentTools []tool.Tool
104103
for _, remoteAgent := range agentConfig.RemoteAgents {
@@ -150,12 +149,11 @@ func createGoogleADKAgent(ctx context.Context, agentConfig *configv1.ADKAgentCon
150149
beforeToolCallbacks := []llmagent.BeforeToolCallback{}
151150
beforeModelCallbacks := []llmagent.BeforeModelCallback{}
152151

153-
if len(mcpAppToolNames) > 0 {
154-
// For MCP App-capable tools, keep rich tool payloads in chat history for UI rendering,
155-
// but compact what is sent back to the model to avoid redundant polling/tool churn.
156-
log.InfoContext(ctx, "wiring MCP App model result callback", "tool_count", len(mcpAppToolNames))
157-
beforeModelCallbacks = append(beforeModelCallbacks, MakeMCPAppModelResultCallback(mcpAppToolNames))
158-
}
152+
// Tools are classified before each model request is prepared. Resolve app
153+
// names here rather than capturing an empty snapshot during construction.
154+
beforeModelCallbacks = append(beforeModelCallbacks, makeMCPAppModelResultCallback(func(ctx agent.Context) map[string]bool {
155+
return mcp.MCPAppToolNamesFromToolsets(ctx, toolsets)
156+
}))
159157
beforeToolCallbacks = append(beforeToolCallbacks, makeBeforeToolCallback(log))
160158

161159
llmAgentConfig := llmagent.Config{

‎go/adk/pkg/agent/mcp_apps.go‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,13 +26,18 @@ const mcpAppRenderedNotice = "The interactive UI for this tool has been rendered
2626
// prevents the model from looping on the rendering tool. Errors are passed
2727
// through so the model can still react to and recover from failures.
2828
func MakeMCPAppModelResultCallback(appToolNames map[string]bool) llmagent.BeforeModelCallback {
29-
return func(_ agent.Context, req *adkmodel.LLMRequest) (*adkmodel.LLMResponse, error) {
29+
return makeMCPAppModelResultCallback(func(agent.Context) map[string]bool { return appToolNames })
30+
}
31+
32+
func makeMCPAppModelResultCallback(appToolNames func(agent.Context) map[string]bool) llmagent.BeforeModelCallback {
33+
return func(ctx agent.Context, req *adkmodel.LLMRequest) (*adkmodel.LLMResponse, error) {
34+
names := appToolNames(ctx)
3035
for _, content := range req.Contents {
3136
if content == nil {
3237
continue
3338
}
3439
for _, part := range content.Parts {
35-
if part == nil || part.FunctionResponse == nil || !appToolNames[part.FunctionResponse.Name] {
40+
if part == nil || part.FunctionResponse == nil || !names[part.FunctionResponse.Name] {
3641
continue
3742
}
3843
part.FunctionResponse.Response = compactMCPAppModelResponse(part.FunctionResponse.Response)

0 commit comments

Comments
 (0)