From 8c5fd6946f8d544594d875bbd3ef6d313c981092 Mon Sep 17 00:00:00 2001 From: Varun Nuthalapati Date: Sat, 6 Jun 2026 13:08:41 -0700 Subject: [PATCH] docs: add TSDoc for agent_transfer, tool_filter, context_compactor, content_request, and agent_registry_mcp processors --- .../agent_transfer_llm_request_processor.ts | 14 +++++++++++ .../processors/content_request_processor.ts | 16 +++++++++++++ .../context_compactor_request_processor.ts | 12 ++++++++++ .../tool_filter_request_processor.ts | 13 ++++++++++- .../agent_registry_mcp_toolset.ts | 23 +++++++++++++++++-- 5 files changed, 75 insertions(+), 3 deletions(-) diff --git a/core/src/agents/processors/agent_transfer_llm_request_processor.ts b/core/src/agents/processors/agent_transfer_llm_request_processor.ts index 27408487..d2e6e596 100644 --- a/core/src/agents/processors/agent_transfer_llm_request_processor.ts +++ b/core/src/agents/processors/agent_transfer_llm_request_processor.ts @@ -14,6 +14,13 @@ import {InvocationContext} from '../invocation_context.js'; import {isLlmAgent, LlmAgent} from '../llm_agent.js'; import {BaseLlmRequestProcessor} from './base_llm_processor.js'; +/** + * Augments the {@link LlmRequest} to support agent transfer. When the current + * agent has reachable transfer targets (sub-agents, peer agents, or a parent + * agent), this processor registers a `transfer_to_agent` function tool and + * appends instructions describing each candidate so the model can choose to + * hand off control. + */ export class AgentTransferLlmRequestProcessor extends BaseLlmRequestProcessor { private readonly toolName = 'transfer_to_agent' as const; private readonly tool = new FunctionTool({ @@ -32,6 +39,13 @@ export class AgentTransferLlmRequestProcessor extends BaseLlmRequestProcessor { }, }); + /** + * Appends transfer instructions and registers the `transfer_to_agent` tool + * when the agent has reachable transfer targets. + * + * @param invocationContext - The current invocation context. + * @param llmRequest - The request to augment with transfer instructions and the transfer tool. + */ // eslint-disable-next-line require-yield override async *runAsync( invocationContext: InvocationContext, diff --git a/core/src/agents/processors/content_request_processor.ts b/core/src/agents/processors/content_request_processor.ts index 22d97985..37dbcc19 100644 --- a/core/src/agents/processors/content_request_processor.ts +++ b/core/src/agents/processors/content_request_processor.ts @@ -15,7 +15,23 @@ import { getCurrentTurnContents, } from './content_processor_utils.js'; +/** + * Populates {@link LlmRequest.contents} from the session event history. + * + * When a {@link CompactedEvent} exists in the session, only the most recent + * compacted event and the raw events that follow it are included, eliding + * earlier history. The extent of context included depends on the agent's + * `includeContents` setting: `'default'` sends the full visible history while + * any other value sends only the current-turn context. + */ export class ContentRequestProcessor implements BaseLlmRequestProcessor { + /** + * Fills {@link LlmRequest.contents} based on the session event history and + * agent configuration. + * + * @param invocationContext - The current invocation context. + * @param llmRequest - The request whose contents field will be populated. + */ // eslint-disable-next-line require-yield async *runAsync( invocationContext: InvocationContext, diff --git a/core/src/agents/processors/context_compactor_request_processor.ts b/core/src/agents/processors/context_compactor_request_processor.ts index b348eb58..3ff95bd3 100644 --- a/core/src/agents/processors/context_compactor_request_processor.ts +++ b/core/src/agents/processors/context_compactor_request_processor.ts @@ -21,10 +21,22 @@ import {BaseLlmRequestProcessor} from './base_llm_processor.js'; export class ContextCompactorRequestProcessor implements BaseLlmRequestProcessor { private compactors: BaseContextCompactor[]; + /** + * @param compactors - Ordered list of compactors to evaluate; the first one + * that reports it should compact will perform the compaction. + */ constructor(compactors: BaseContextCompactor[]) { this.compactors = compactors; } + /** + * Evaluates compactors in priority order. The first compactor that indicates + * it should compact will compact the session history, fire plugin hooks, and + * yield any newly generated events. Iteration stops after one compaction. + * + * @param invocationContext - The current invocation context. + * @param _llmRequest - Unused; present to satisfy the {@link BaseLlmRequestProcessor} interface. + */ async *runAsync( invocationContext: InvocationContext, _llmRequest: LlmRequest, diff --git a/core/src/agents/processors/tool_filter_request_processor.ts b/core/src/agents/processors/tool_filter_request_processor.ts index 2818f975..29721f5a 100644 --- a/core/src/agents/processors/tool_filter_request_processor.ts +++ b/core/src/agents/processors/tool_filter_request_processor.ts @@ -13,8 +13,19 @@ import {isLlmAgent} from '../llm_agent.js'; import {ReadonlyContext} from '../readonly_context.js'; import {BaseLlmRequestProcessor} from './base_llm_processor.js'; +/** + * Filters the set of tools on the {@link LlmRequest} by delegating to the + * active plugin manager's `beforeToolSelection` hook. If no plugin restricts + * the tool set, the request is left unchanged. + */ export class ToolFilterRequestProcessor extends BaseLlmRequestProcessor { - /** Filters the set of tools on the request based on plugins. */ + /** + * Invokes plugin-based tool filtering and updates {@link LlmRequest.allowedTools} + * with the reduced tool set if any plugin returns a filtered result. + * + * @param invocationContext - The current invocation context. + * @param llmRequest - The request whose allowed tools may be restricted. + */ // eslint-disable-next-line require-yield override async *runAsync( invocationContext: InvocationContext, diff --git a/core/src/integrations/agent_registry/agent_registry_mcp_toolset.ts b/core/src/integrations/agent_registry/agent_registry_mcp_toolset.ts index 6e9a9727..e78c228d 100644 --- a/core/src/integrations/agent_registry/agent_registry_mcp_toolset.ts +++ b/core/src/integrations/agent_registry/agent_registry_mcp_toolset.ts @@ -36,6 +36,19 @@ export class AgentRegistrySingleMCPToolset extends BaseToolset { readonly authScheme?: AuthScheme; readonly authCredential?: AuthCredential; + /** + * @param options - Configuration for the MCP toolset. + * @param options.destinationResourceId - Telemetry identifier injected as + * `gcp.mcp.server.destination.id` into each resolved tool's custom metadata. + * @param options.connectionParams - HTTP connection parameters for the MCP server. + * @param options.toolFilter - Optional predicate or list of tool names to include. + * When omitted, all tools from the server are returned. + * @param options.prefix - Optional prefix prepended to each tool name (e.g. `myServer_toolName`). + * @param options.headerProvider - Optional async function called immediately before each + * {@link getTools} invocation to supply or refresh request headers (e.g. GCP auth tokens). + * @param options.authScheme - Optional auth scheme forwarded to each resolved tool. + * @param options.authCredential - Optional credential forwarded to each resolved tool. + */ constructor(options: { destinationResourceId?: string; connectionParams: StreamableHTTPConnectionParams; @@ -56,8 +69,14 @@ export class AgentRegistrySingleMCPToolset extends BaseToolset { } /** - * Connects to the underlying MCP server, retrieves tool definitions, prefixes tool names, - * and injects destination telemetry metadata. + * Connects to the underlying MCP server, retrieves tool definitions, prefixes + * tool names, and injects destination telemetry metadata into each tool. + * + * The `headerProvider`, if configured, is invoked immediately before the + * connection is established so that tokens are always fresh. + * + * @param context - Optional readonly agent context passed to the header provider. + * @returns The resolved and optionally filtered list of {@link MCPTool} instances. */ async getTools(context?: ReadonlyContext): Promise { const headers: Record = {};