Agent Tools

Purpose

Agent Tools address the need for agent composition and delegation within the broader Tooling System. While the parent topic defines modular tools like function wrappers, artifact loaders, and search tools that an agent can invoke, Agent Tools introduce a unique capability: wrapping entire sub-agents as callable tools. This allows an agent to delegate part of its processing to another specialized agent, enabling hierarchical and compositional AI workflows.

This subtopic solves problems where:

• Different specialized agents need to collaborate or be chained.

• Complex tasks are decomposed into sub-agents with distinct skills or toolsets.

• Agents need to reuse existing agent logic dynamically instead of reimplementing tool functionality.

By encapsulating sub-agents as tools that can be called synchronously within agent workflows, Agent Tools enable flexible, composable agent architectures that improve modularity and reuse.

Functionality

The core functionality of Agent Tools revolves around a tool implementation that wraps a sub-agent instance and exposes it as a callable function tool. Key aspects include:

Agent Wrapping and Invocation

• The agentTool struct holds a reference to a sub-agent (agent.Agent).

• The tool exposes the sub-agent's function declaration based on its input schema, allowing the parent agent's LLM to invoke it with typed parameters.

• When called (Run method), the tool:

  • Validates input arguments against the sub-agent's input schema.

  • Creates a new session context for the sub-agent invocation, inheriting relevant state from the parent tool context.

  • Instantiates an agent runner internally to execute the sub-agent asynchronously.

  • Collects events from the sub-agent run, capturing the final LLM response.

  • Validates and parses the sub-agent's output against its output schema, returning structured results.

  • Supports skipping result summarization based on configuration to control downstream processing.

Integration with LLM Requests

• During LLM request preparation, the tool appends the sub-agent's function declaration into the request's tools list.

• This allows the LLM to generate function calls that trigger the sub-agent tool, enabling nested agent calls transparently.

Input and Output Schema Validation

• Inputs are validated strictly against the sub-agent's declared input schema, catching errors early.

• Outputs from the sub-agent are parsed and validated against its output schema, ensuring consistent structured data flow between agents.

• If no schemas are defined, the tool falls back to a default string-based input and free-form string output.

Session and State Management

• Each sub-agent call runs in its own isolated session created dynamically.

• The state from the calling context is selectively copied to the sub-agent session, excluding internal keys.

• This isolation allows independent conversation histories and memory management per sub-agent call.

Skip Summarization Control

• The tool supports a SkipSummarization flag in its config.

• When set, it signals upstream workflow components to skip automatic summarization after sub-agent execution, giving finer control over session event handling.

Code Illustration: Running a Sub-Agent as a Tool

func (t *agentTool) Run(toolCtx tool.Context, args any) (map[string]any, error) {
	// Validate input arguments against sub-agent input schema
	if err := utils.ValidateMapOnSchema(argsMap, agentInputSchema, true); err != nil {
		return nil, err
	}

	// Create a new session for the sub-agent with inherited state
	subSession, err := sessionService.Create(toolCtx, &session.CreateRequest{ ... })

	// Instantiate runner and execute sub-agent
	eventCh := runner.Run(toolCtx, subSession.UserID, subSession.ID, content, ...)

	// Collect final sub-agent response event
	// Parse and validate output against output schema
	return parsedOutput, nil
}

Integration

Agent Tools integrate tightly within the Modular Tool Framework and complement other subtopics:

• They extend the concept of tools by enabling agent composition rather than just function or artifact-based tools.

• They leverage the Agent Framework interfaces and the Agent Execution Runner to manage sub-agent lifecycle and invocation.

• They interact with the Session Management system to create isolated sub-agent sessions, facilitating independent state and memory.

• They contribute to complex workflows orchestrated by Agent Workflow Management, allowing nested agent calls within sequential, parallel, or looping agents.

• They fit into LLM integration patterns by exposing sub-agents as callable functions with explicit JSON schemas, similar to Function Tools but wrapping entire agents.

• Their control flags, like SkipSummarization, provide finer control in multi-agent layered workflows, coordinating with session summarization and event handling.

By wrapping sub-agents as tools, Agent Tools enable hierarchical agent delegation and modular AI workflows that scale beyond single-agent or flat tool invocation patterns.

sequenceDiagram
participant ParentAgent as Parent Agent
participant AgentTool as Agent Tool
participant Runner as Agent Runner
participant SubAgent as Sub Agent
participant SessionSvc as Session Service
ParentAgent->>AgentTool: Call Run(args)
AgentTool->>SessionSvc: Create sub-agent session (with inherited state)
SessionSvc-->>AgentTool: New sub-agent session
AgentTool->>Runner: Run sub-agent with session and input
Runner->>SubAgent: Execute sub-agent
SubAgent-->>Runner: Emit events & final response
Runner-->>AgentTool: Stream events channel
AgentTool->>AgentTool: Collect last LLM response
AgentTool->>AgentTool: Validate and parse output schema
AgentTool-->>ParentAgent: Return output map