Agent Development Kit (ADK)

Build powerful, interoperable AI agents with the Agent-to-Agent (A2A) protocol

⚠️ Early Stage Warning: This project is in its early stages of development. Breaking changes are expected as the API evolves and improves. Please use pinned versions in production environments and be prepared to update your code when upgrading versions.

Table of Contents

• Overview
  • What is A2A?
• 🚀 Quick Start
  • Installation
  • Examples
• ✨ Key Features
• 🛠️ Development
• 📖 API Reference
  • Core Components
  • Configuration
• 🔧 Advanced Usage
• 🌐 A2A Ecosystem
• 📋 Requirements
• 🐳 Docker Support
• 📄 License
• 🤝 Contributing
• 📞 Support
• 🔗 Resources

Overview

The A2A ADK (Agent Development Kit) is a Go library that simplifies building Agent-to-Agent (A2A) protocol compatible agents. A2A enables seamless communication between AI agents, allowing them to collaborate, delegate tasks, and share capabilities across different systems and providers.

What is A2A?

Agent-to-Agent (A2A) is a standardized protocol that enables AI agents to:

• Communicate with each other using a unified JSON-RPC interface
• Delegate tasks to specialized agents with specific capabilities
• Stream responses in real-time for better user experience
• Authenticate securely using OIDC/OAuth2
• Discover capabilities through standardized agent cards

🚀 Quick Start

Installation

go get github.com/inference-gateway/adk

Examples

For complete working examples, see the examples directory:

• Minimal - Basic A2A server without AI capabilities
• AI-Powered - Full A2A server with LLM integration
• AI-Powered Streaming - AI agent with streaming capabilities
• Callbacks - Lifecycle hooks for guardrails, caching, and logging
• Default Handlers - Built-in task processing
• Static Agent Card - JSON-based agent metadata management
• Streaming - Real-time streaming responses
• Input Required - Interactive conversation with input pausing
• Artifacts - MinIO - MinIO cloud storage with direct/proxy download modes
• Artifacts - Filesystem - Filesystem-based artifact storage
• Artifacts - Autonomous Tool - Autonomous tool for artifact creation
• Artifacts - Default Handlers - Artifacts with default handlers
• Queue Storage - Memory and Redis storage backends
• TLS Server - Secure HTTPS with TLS configuration
• Usage Metadata - Token usage and execution metrics tracking
• MCP - Connect the agent to MCP servers and invoke their tools via a selector
• Protocol Methods - End-to-end walk-through of tasks/cancel, tasks/list, tasks/pushNotificationConfig/{set,get,list,delete}, tasks/resubscribe, and agent/getAuthenticatedExtendedCard

Getting Started

To run any example:

cd examples/minimal/server
go run main.go

Each example includes its own README with setup instructions and usage details.

✨ Key Features

Core Capabilities

• 🤖 A2A Protocol Compliance: Full implementation of the Agent-to-Agent communication standard
• 🔌 Multi-Provider Support: Works with Anthropic (Claude models), Cloudflare Workers AI, Cohere, DeepSeek, Google (Gemini), Groq, llama.cpp, MiniMax, Mistral, Moonshot, Nvidia, Ollama, Ollama Cloud, OpenAI (GPT models)

• 🌊 Real-time Streaming: Stream responses as they're generated from language models
• 🔧 Custom Tools: Easy integration of custom tools and capabilities
• 🧩 MCP Client: Connect to MCP servers and expose their tools to the agent through a selector that keeps only tool metadata in context - see docs/mcp.md
• 🪝 Callback Hooks: Lifecycle hooks for agent, model, and tool execution with flow control
• 📎 File Artifacts: Support for downloadable file artifacts with filesystem and MinIO storage backends
• 🔐 Secure Authentication: Built-in OIDC/OAuth2 authentication support
• 📨 Push Notifications: Webhook notifications for real-time task state updates
• ⏸️ Task Pausing: Built-in support for input-required state pausing and resumption
• 🗄️ Multiple Storage Backends: Support for in-memory and Redis storage with horizontal scaling
• 📊 Usage Metadata: Automatic tracking of LLM token consumption and execution metrics

Developer Experience

• ⚙️ Environment Configuration: Simple setup through environment variables
• 📊 Task Management: Built-in task queuing, polling, and lifecycle management
• 🏗️ Extensible Architecture: Pluggable components for custom business logic
• 📚 Type-Safe: Generated types from A2A schema for compile-time safety
• 🧪 Well Tested: Comprehensive test coverage with table-driven tests

Enterprise Ready

• 🌿 Lightweight: Optimized binary size for efficient deployment
• 🛡️ Production Hardened: Configurable timeouts, TLS support, and error handling
• ☸️ Cloud Native: Ready for cloud-native deployments and orchestration
• 📊 Observability: OpenTelemetry integration for monitoring and tracing

🛠️ Development

Quick Setup

# Clone the repository
git clone https://github.com/inference-gateway/adk.git
cd adk

# Install dependencies
go mod download

# Install pre-commit hook
task precommit:install

Essential Tasks

Build-Time Agent Metadata

The ADK supports injecting agent metadata at build time using Go linker flags (LD flags). This makes agent information immutable and embedded in the binary, which is useful for production deployments.

Available LD Flags

The following build-time metadata variables can be set via LD flags:

• BuildAgentName - The agent's display name
• BuildAgentDescription - A description of the agent's capabilities
• BuildAgentVersion - The agent's version number

Usage Examples

Simple A2A Server Example:

package main

import (
	"context"
	"fmt"
	"log"
	"os"
	"os/signal"
	"syscall"
	"time"

	zap "go.uber.org/zap"

	server "github.com/inference-gateway/adk/server"
	config "github.com/inference-gateway/adk/server/config"
	types "github.com/inference-gateway/adk/types"
)

func main() {
	fmt.Println("🤖 Starting Simple A2A Server...")

	// Initialize logger
	logger, err := zap.NewDevelopment()
	if err != nil {
		log.Fatalf("failed to create logger: %v", err)
	}
	defer logger.Sync()

	// Get port from environment or use default
	port := os.Getenv("PORT")
	if port == "" {
		port = "8080"
	}

	// Configuration
	cfg := config.Config{
		AgentName:        "simple-agent",
		AgentDescription: "A simple A2A server with default handlers",
		AgentVersion:     "0.1.0",
		Debug:            true,
		QueueConfig: config.QueueConfig{
			CleanupInterval: 5 * time.Minute,
		},
		ServerConfig: config.ServerConfig{
			Port: port,
		},
	}

	// Build and start server with default handlers
	a2aServer, err := server.NewA2AServerBuilder(cfg, logger).
		WithDefaultTaskHandlers().
		WithAgentCard(types.AgentCard{
			Name:            cfg.AgentName,
			Description:     cfg.AgentDescription,
			Version:         cfg.AgentVersion,
			URL:             fmt.Sprintf("http://localhost:%s", port),
			ProtocolVersion: "0.3.0",
			Capabilities: types.AgentCapabilities{
				Streaming:              &[]bool{true}[0],
				PushNotifications:      &[]bool{false}[0],
				StateTransitionHistory: &[]bool{false}[0],
			},
			DefaultInputModes:  []string{"text/plain"},
			DefaultOutputModes: []string{"text/plain"},
			Skills:             []types.AgentSkill{},
		}).
		Build()
	if err != nil {
		logger.Fatal("failed to create A2A server", zap.Error(err))
	}

	logger.Info("✅ server created")

	// Start server
	ctx, cancel := context.WithCancel(context.Background())
	defer cancel()

	go func() {
		if err := a2aServer.Start(ctx); err != nil {
			logger.Fatal("server failed to start", zap.Error(err))
		}
	}()

	logger.Info("🌐 server running on port " + port)

	// Wait for shutdown signal
	quit := make(chan os.Signal, 1)
	signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
	<-quit

	logger.Info("🛑 shutting down...")

	// Graceful shutdown
	shutdownCtx, shutdownCancel := context.WithTimeout(context.Background(), 5*time.Second)
	defer shutdownCancel()

	if err := a2aServer.Stop(shutdownCtx); err != nil {
		logger.Error("shutdown error", zap.Error(err))
	} else {
		logger.Info("✅ goodbye!")
	}
}

See the Docker Support section for containerized builds.

For detailed development workflows, testing guidelines, and contribution processes, see the Contributing Guide.

📖 API Reference

Core Components

A2AServer

The main server interface that handles A2A protocol communication. See server examples for complete implementation details.

A2AServerBuilder

Build A2A servers with custom configurations using a fluent interface. The builder provides methods for:

• WithAgent() - Configure AI agent integration
• WithDefaultTaskHandlers() - Use built-in task processing
• WithBackgroundTaskHandler() - Custom background task handling
• WithStreamingTaskHandler() - Custom streaming task handling
• WithAgentCardFromFile() - Load agent metadata from JSON

See examples for complete usage patterns.

Task Handler Interfaces

The ADK provides two distinct interfaces for handling tasks:

• TaskHandler - For background/polling scenarios (message/send)
• StreamableTaskHandler - For real-time streaming scenarios (message/stream)

Streaming handlers require an agent to be configured. See task handler examples for implementation details.

AgentBuilder

Build OpenAI-compatible agents using a fluent interface. Supports:

• Custom LLM clients
• System prompts and conversation limits
• Tool integration
• Callback hooks (BeforeAgent, AfterAgent, BeforeModel, AfterModel, BeforeTool, AfterTool)
• Configuration management

See AI-powered examples and callback examples for complete agent setup.

A2AClient

Client interface for communicating with A2A servers. Supports:

• Task sending and streaming
• Health monitoring
• Agent card retrieval
• Custom configuration

See client examples for usage patterns.

A2A JSON-RPC Methods

Beyond message/send, message/stream, and tasks/get, the client exposes every method in the A2A JSON-RPC surface. Each snippet below is runnable against any ADK-built server; see examples/protocol-methods/ for an end-to-end demo that ties them all together.

tasks/cancel

Cancel an in-flight task. Works for tasks in any non-terminal state (SUBMITTED, WORKING, INPUT_REQUIRED, AUTH_REQUIRED, UNSPECIFIED).

resp, err := a2a.CancelTask(ctx, types.TaskIdParams{ID: taskID})
if err != nil {
    log.Fatalf("cancel failed: %v", err)
}

taskBytes, _ := json.Marshal(resp.Result)
var task types.Task
_ = json.Unmarshal(taskBytes, &task)
log.Printf("cancelled task %s → state=%s", task.ID, task.Status.State)

tasks/list

List tasks the server knows about. Limit controls page size (server caps the limit at 100; default is 50) and Offset controls where the page starts. Iterate until offset >= TotalSize to walk the full result set.

const pageSize = 20
offset := 0
for {
    resp, err := a2a.ListTasks(ctx, types.TaskListParams{
        Limit:  pageSize,
        Offset: offset,
    })
    if err != nil {
        log.Fatalf("list failed: %v", err)
    }

    listBytes, _ := json.Marshal(resp.Result)
    var list types.TaskList
    _ = json.Unmarshal(listBytes, &list)

    for _, t := range list.Tasks {
        log.Printf("  task %s [%s]", t.ID, t.Status.State)
    }

    offset += len(list.Tasks)
    if len(list.Tasks) == 0 || offset >= list.TotalSize {
        break
    }
}

You can also filter by ContextID or by State (e.g. only TASK_STATE_COMPLETED); both fields are optional pointers on TaskListParams.

tasks/pushNotificationConfig/{set,get,list,delete}

Register, inspect, and remove webhook callbacks the server will POST to as a task changes state. The four methods share a common identifier (task.ID) and form a complete CRUD cycle.

configID := uuid.New().String()
authToken := "shared-secret"

// set: register a webhook for the task.
if _, err := a2a.SetTaskPushNotificationConfig(ctx, types.TaskPushNotificationConfig{
    Name: taskID,
    PushNotificationConfig: types.PushNotificationConfig{
        ID:    &configID,
        URL:   "https://example.com/webhook",
        Token: &authToken,
    },
}); err != nil {
    log.Fatalf("set failed: %v", err)
}

// get: read the active config.
if _, err := a2a.GetTaskPushNotificationConfig(ctx, types.GetTaskPushNotificationConfigParams{
    Name: taskID,
}); err != nil {
    log.Fatalf("get failed: %v", err)
}

// list: enumerate every config attached to a task.
if _, err := a2a.ListTaskPushNotificationConfig(ctx, types.ListTaskPushNotificationConfigParams{
    Parent: taskID,
}); err != nil {
    log.Fatalf("list failed: %v", err)
}

// delete: tear the config down.
if _, err := a2a.DeleteTaskPushNotificationConfig(ctx, types.DeleteTaskPushNotificationConfigParams{
    Name: taskID,
}); err != nil {
    log.Fatalf("delete failed: %v", err)
}

Server-side push notifications require CapabilitiesConfig.PushNotifications to be true on the server.

tasks/resubscribe

Re-attach to a streaming task after the original SSE connection has dropped. The server first re-emits the current task state, then forwards any further streaming events as they happen.

events, err := a2a.ResubscribeTask(ctx, types.TaskResubscriptionParams{
    Name: taskID,
})
if err != nil {
    log.Fatalf("resubscribe failed: %v", err)
}
for evt := range events {
    payload, _ := json.Marshal(evt.Result)
    log.Printf("event: %s", string(payload))
}

agent/getAuthenticatedExtendedCard

The JSON-RPC counterpart to the public .well-known/agent-card.json endpoint. The response is the same AgentCard object, but the call passes through the JSON-RPC route and is therefore subject to the server's authentication middleware - useful when the extended card should only be visible to authenticated callers.

resp, err := a2a.GetAuthenticatedExtendedCard(ctx, types.GetAuthenticatedExtendedCardParams{})
if err != nil {
    log.Fatalf("authenticated card fetch failed: %v", err)
}
cardBytes, _ := json.MarshalIndent(resp.Result, "", "  ")
log.Println(string(cardBytes))

Agent Health Monitoring

Monitor agent operational status with three health states:

• healthy: Fully operational
• degraded: Partially operational
• unhealthy: Not operational

See client examples for implementation.

LLM Client

Create OpenAI-compatible LLM clients for agent integration. See AI examples for setup details.

Configuration

Configure your A2A agent using environment variables. All configuration is optional and includes sensible defaults.

Core Server Configuration

Agent & LLM Configuration

Agent Capabilities

Authentication (Optional)

See docs/authentication.md for the full card-driven auth flow: discovery, out-of-band credentials, the authenticated extended card, and authorization via callbacks.

Task Management

Storage Configuration (Optional)

Storage Backends:

• Memory Storage (Default): Fast in-memory storage for development and single-instance deployments
• Redis Storage: Persistent storage with horizontal scaling support for production deployments

Redis Configuration Examples:

# Basic Redis setup
export QUEUE_PROVIDER=redis
export QUEUE_URL=redis://localhost:6379

# Redis with authentication
export QUEUE_URL=redis://:password@localhost:6379
export QUEUE_URL=redis://username:password@localhost:6379

# Redis with specific database
export QUEUE_URL=redis://localhost:6379/1

# Redis with TLS (Redis 6.0+)
export QUEUE_URL=rediss://username:password@redis.example.com:6380/0

MCP Client Configuration (Optional)

Connect the agent to MCP servers and expose their tools through a selector that keeps only tool metadata in the LLM context. Disabled by default and only useful when an LLM is configured. Enable with MCP_ENABLED=true and point MCP_SERVERS at one or more streamable-HTTP MCP servers; the full list of MCP_* variables (timeouts, retry, and polling-backoff tuning) is documented in docs/mcp.md.

Artifacts Configuration (Optional)

Enable file artifacts support for downloadable files generated by your agent:

Storage Backends:

• Filesystem Storage (Default): Store artifacts locally on disk, suitable for single-instance deployments
• MinIO Storage: Cloud-native object storage with S3 compatibility, ideal for distributed deployments

Download Modes:

• Proxy Mode (Default): Downloads go through the artifacts server (port 8081) with authentication and logging
• Direct Mode: Configure ARTIFACTS_STORAGE_BASE_URL to enable direct downloads from storage backend

MinIO Configuration Example:

# Enable artifacts with MinIO storage
export ARTIFACTS_ENABLED=true
export ARTIFACTS_STORAGE_PROVIDER=minio
export ARTIFACTS_STORAGE_ENDPOINT=localhost:9000
export ARTIFACTS_STORAGE_ACCESS_KEY=minioadmin
export ARTIFACTS_STORAGE_SECRET_KEY=minioadmin
export ARTIFACTS_STORAGE_USE_SSL=false

# Optional: Enable direct downloads (bypasses artifacts server)
export ARTIFACTS_STORAGE_BASE_URL=http://localhost:9000

Benefits of Redis Storage:

• ✅ Persistent Tasks - Tasks survive server restarts
• ✅ Distributed Processing - Multiple server instances can share the same queue
• ✅ High Performance - Redis provides fast task queuing and retrieval
• ✅ Task History - Completed and failed tasks are retained based on configuration
• ✅ Horizontal Scaling - Scale to N number of A2A servers processing the same queue

TLS Configuration (Optional)

Telemetry (Optional)

When enabled, the server exports metrics (Prometheus pull or OTLP push) and can export traces via OTLP over HTTP or gRPC. It also participates in W3C Trace Context propagation: incoming traceparent and baggage headers are extracted, a request-scoped a2a.request span is created, and the session.id / gen_ai.tool.call.id baggage items are surfaced as span attributes. Exporters are selected with the standard OTEL_* variables; the original TELEMETRY_* variables remain supported as deprecated aliases. See docs/telemetry.md for the full matrix.

TELEMETRY_ENABLED=true is the master switch; the OTEL_* variables then choose which exporters run per signal.

Attribute keys (default to OTel semantic conventions; used for both the baggage member and the span attribute):

Deprecated aliases (superseded by the OTEL_* variables above, still honored):

The tracing service name is taken from the agent card name (the build-time agent identity), not a separate variable.

Library consumers that already run their own OpenTelemetry setup can inject it with WithTelemetry() instead of letting the ADK build one from the environment. The injected instance activates the middleware, request spans, and /metrics endpoint regardless of TELEMETRY_ENABLED:

srv, err := server.NewA2AServerBuilder(cfg, logger).
    WithTelemetry(myOtel).
    WithAgentCard(card).
    WithDefaultTaskHandlers().
    Build()

Example Configuration

See configuration examples for complete setup patterns, including environment variables, custom config structs, and programmatic overrides.

🔧 Advanced Usage

For detailed implementation examples and patterns, see the examples directory:

• Custom Tools - Creating and integrating custom tools
• Callback Hooks - Lifecycle hooks for guardrails, caching, and flow control
• Agent Configuration - JSON-based agent metadata management
• Task Handling - Built-in and custom task processing
• Streaming - Real-time response handling
• Usage Metadata - Tracking token consumption and execution metrics for cost monitoring and performance analysis

🌐 A2A Ecosystem

This ADK is part of the broader Inference Gateway ecosystem:

Related Projects

• Inference Gateway - Unified API gateway for AI providers
• Go SDK - Go client library for Inference Gateway
• TypeScript SDK - TypeScript/JavaScript client library
• Python SDK - Python client library
• Rust SDK - Rust client library
• Rust ADK - Rust A2A Development Kit

A2A Agents

• Awesome A2A - Curated list of A2A-compatible agents
• Browser Agent - Web browser automation and interaction agent
• Documentation Agent - Documentation generation and management agent
• Google Calendar Agent - Google Calendar integration agent
• n8n Agent - n8n workflow automation integration agent

📋 Requirements

• Go: 1.26 or later
• Dependencies: See go.mod for full dependency list

🐳 Docker Support

Build and run your A2A agent application in a container. Here's an example Dockerfile for an application using the ADK:

FROM golang:1.26-alpine AS builder

# Build arguments for agent metadata
ARG AGENT_NAME="My A2A Agent"
ARG AGENT_DESCRIPTION="A custom A2A agent built with the ADK"
ARG AGENT_VERSION="0.1.0"

WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download

COPY . .
RUN go mod tidy && \
    go build -ldflags "-X 'github.com/inference-gateway/adk/server.BuildAgentName=${AGENT_NAME}' -X 'github.com/inference-gateway/adk/server.BuildAgentDescription=${AGENT_DESCRIPTION}' -X 'github.com/inference-gateway/adk/server.BuildAgentVersion=${AGENT_VERSION}'" -o bin/agent .

FROM alpine:latest
RUN apk --no-cache add ca-certificates && \
    addgroup -g 1001 -S a2a && \
    adduser -u 1001 -S agent -G a2a
WORKDIR /home/agent
COPY --from=builder /app/bin/agent .
RUN chown agent:a2a ./agent
USER agent
CMD ["./agent"]

Build with custom metadata:

docker build \
  --build-arg AGENT_NAME="Weather Assistant" \
  --build-arg AGENT_DESCRIPTION="AI-powered weather forecasting agent" \
  --build-arg AGENT_VERSION="0.1.1" \
  -t my-a2a-agent .

📄 License

This project is licensed under the Apache 2.0 License. See the LICENSE file for details.

🤝 Contributing

Contributions to the A2A ADK are welcome! Whether you're fixing bugs, adding features, improving documentation, or helping with testing, your contributions make the project better for everyone.

Please see the Contributing Guide for:

• 🚀 Getting Started - Development environment setup and prerequisites
• 📋 Development Workflow - Step-by-step development process and tools
• 🎯 Coding Guidelines - Code style, testing patterns, and best practices
• 🛠️ Making Changes - Branch naming, commit format, and submission process
• 🧪 Testing Guidelines - Test structure, mocking, and coverage requirements
• 🔄 Pull Request Process - Review process and submission checklist

Quick Start for Contributors:

# Fork the repo and clone it
git clone https://github.com/your-username/adk.git
cd adk

# Install pre-commit hook
task precommit:install

For questions or help getting started, please open a discussion or check out the contributing guide.

📞 Support

Issues & Questions

• Bug Reports: GitHub Issues
• Documentation: Official Docs

🔗 Resources

Documentation

• A2A Protocol Specification
• API Documentation
• MCP Client Guide
• Artifacts Guide
• Telemetry Guide

GitHub • Documentation