Install dependencies

go mod download

📋 Requirements

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

Installation

go get github.com/inference-gateway/adk

Quick Setup

```bash

Install pre-commit hook

task precommit:install ```

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.

Basic Redis setup

export QUEUE_PROVIDER=redis export QUEUE_URL=redis://localhost:6379

🐳 Docker Support

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

```dockerfile 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:**

Install pre-commit hook

task precommit:install ```

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

🚀 Quick Start

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
• 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.

🔧 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

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)

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:

```bash

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)

Example Configuration

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

📖 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.

Issues & Questions

• Bug Reports: GitHub Issues
• Documentation: Official Docs