Agent Go SDK

The examples/microservices/ directory contains four distinct patterns for implementing distributed agents:

• Basic Microservice (basic_microservice/): Demonstrates creating a local agent and wrapping it as a gRPC microservice on a specific port.
• Remote Agent Client (remote_client/): Shows how to connect to a remote agent service via URL and use it like a local agent, including handling connection errors and retries.
• Mixed Local and Remote (mixed_agents/): Illustrates building a distributed system by using both local and remote agents together as subagents.
• Microservice Manager (service_manager/): Demonstrates programmatic management of multiple microservices, including starting/stopping services and monitoring health.

The task package is organized into three primary files to separate data structures, core services, and adapter logic:

• models.go: Contains all data structures used throughout the task package.
• service.go: Defines the core Service interface and provides the InMemoryTaskService and AgentTaskService implementations.
• adapter.go: Implements the TaskAdapter interface and the AdapterService used for working with agent-specific models, including the default implementation.

A2A is an open protocol that enables AI agents to discover, communicate, and collaborate across different frameworks (e.g., Google ADK, LangChain, CrewAI).

Key features include:

• Agent discovery: via /.well-known/agent-card.json.
• Message exchange: Synchronous and streaming via JSON-RPC.
• Task lifecycle: Management of working, completed, failed, and canceled states.
• Multi-turn conversations: Managed via context IDs.

The pkg/a2a package in agent-sdk-go provides both server (to expose your agents) and client (to call remote agents) implementations.

The MCP Tool Output Schemas feature provides JSON Schema (Draft 7) validation and type safety for Model Context Protocol (MCP) tool responses. It ensures that tool outputs conform to expected structures, which improves error handling and integration reliability when an Agent interacts with an MCP Server via a ToolManager.

Architecture Flow

1. Agent: Calls tools and validates types.
2. ToolManager: Handles validation and manages schemas.
3. MCP Server: Provides tools and responses.
4. Validator: The underlying engine performing JSON schema validation, type checking, and rule enforcement.

The DataStore component provides a unified interface for storing and retrieving structured data with built-in multi-tenancy support. It allows you to perform CRUD operations, querying, and transactional updates across different database backends using a consistent API.

Key features include:

• Unified Interface: The same API works across different database implementations.
• Multi-Tenancy: Built-in organization-level data isolation via org_id.
• CRUD Operations: Create, Read, Update, and Delete with automatic ID generation.
• Query Support: Filtering, limiting, offsetting, and ordering.
• Transactions: Atomic operations with automatic rollback support.
• Automatic Timestamps: Managed created_at and updated_at fields.

When defining Go structs for structured output, you can use specific struct tags to influence how the LLM interprets and populates the data:

• json:"fieldname": Standard JSON key mapping.
• description:"...": Provides a natural language description of the field. The SDK uses this to generate the JSON schema, which guides the LLM on what information to place in that field.
• omitempty: Used within the JSON tag (e.g., json:"field_name,omitempty") to mark fields as optional. This tells the LLM that the field may be omitted from the response if the information is unavailable.

type Person struct {
    Name        string `json:"name" description:"The person's full name"`
    BirthDate   string `json:"birth_date,omitempty" description:"Date of birth"`
}

When accessing resources via the MCP (Model Context Protocol) manager, use structured URIs with specific schemes to ensure clarity and compatibility.

Recommended Patterns:

• file:///path/to/resource for file system access.
• db://database/table?query=param for database queries.
• api://endpoint/path for API endpoints.
• stream://topic/name for real-time data streams.

Avoid:

• Generic identifiers like resource://unclear-identifier.
• URIs without schemes like data.

// Good URI patterns
"file:///documents/report.pdf"           // File system
"db://inventory/products?category=tech"  // Database query
"api://slack/channels/general/messages"  // API endpoint
"stream://metrics/cpu-usage"             // Real-time data

The example utilizes a Lazy MCP Configuration approach. Instead of starting the MCP server immediately, the server is only initialized when the agent makes its first tool call.

• The MCP server is executed via the command uvx mcp-google-cse as a stdio process.
• The required environment variables (API_KEY and ENGINE_ID) are passed directly to the MCP server process.
• Once initialized, the agent gains access to the google_search tool.