Loading repository data…
go-a2a / repository
An open-source, code-first Go toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.
An open-source, code-first Go toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.
Features • Installation • Quick Start • Architecture • Examples
[!IMPORTANT] This project is in the alpha stage.
Flags, configuration, behavior, and design may change significantly.
google.golang.org/genaigo mod init your-project
go get github.com/go-a2a/adk-go
# For Google Gemini
export GEMINI_API_KEY="your-gemini-api-key"
# For Anthropic Claude
export ANTHROPIC_API_KEY="your-anthropic-api-key"
# Optional: For Google Cloud AI Platform
export GOOGLE_APPLICATION_CREDENTIALS="path/to/service-account.json"
package main
import (
"context"
"fmt"
"log"
"github.com/go-a2a/adk-go/agent"
"github.com/go-a2a/adk-go/model"
"github.com/go-a2a/adk-go/session"
"github.com/go-a2a/adk-go/types"
)
func main() {
ctx := context.Background()
// Create a model
m, err := model.NewGoogleModel("gemini-2.0-flash-exp")
if err != nil {
log.Fatal(err)
}
defer m.Close()
// Create an LLM agent
llmAgent := agent.NewLLMAgent(ctx, "assistant",
agent.WithModel(m),
agent.WithInstruction("You are a helpful AI assistant."),
)
// Create session
sessionService := session.NewInMemoryService()
sess, _ := sessionService.CreateSession(ctx, "myapp", "user123", "session456", nil)
// Create invocation context
ictx := types.NewInvocationContext(sess, sessionService, nil, nil)
// Run the agent
for event, err := range llmAgent.Run(ctx, ictx) {
if err != nil {
log.Printf("Error: %v", err)
continue
}
// Handle events
if event.Message != nil {
fmt.Println("Agent:", event.Message.Text)
}
}
}
package main
import (
"context"
"fmt"
"math/rand"
"github.com/go-a2a/adk-go/agent"
"github.com/go-a2a/adk-go/model"
"github.com/go-a2a/adk-go/tool/tools"
"github.com/go-a2a/adk-go/types"
)
// Simple dice rolling function
func rollDice(ctx context.Context, sides int) (int, error) {
if sides <= 0 {
return 0, fmt.Errorf("dice must have at least 1 side")
}
return rand.Intn(sides) + 1, nil
}
func main() {
ctx := context.Background()
// Create model
m, _ := model.NewGoogleModel("gemini-2.0-flash-exp")
defer m.Close()
// Create function tool
diceTool := tools.NewFunctionTool("roll_dice", rollDice,
tools.WithDescription("Roll a dice with specified number of sides"),
tools.WithParameterDescription("sides", "Number of sides on the dice"),
)
// Create agent with tools
agent := agent.NewLLMAgent(ctx, "game_master",
agent.WithModel(m),
agent.WithInstruction("You are a game master. Help users with dice rolls and games."),
agent.WithTools(diceTool),
)
// ... run agent similar to above
}
package main
import (
"context"
"github.com/go-a2a/adk-go/agent"
"github.com/go-a2a/adk-go/model"
)
func main() {
ctx := context.Background()
m, _ := model.NewGoogleModel("gemini-2.0-flash-exp")
defer m.Close()
// Create specialized agents
researcher := agent.NewLLMAgent(ctx, "researcher",
agent.WithModel(m),
agent.WithInstruction("You are a research specialist. Gather and analyze information."),
)
writer := agent.NewLLMAgent(ctx, "writer",
agent.WithModel(m),
agent.WithInstruction("You are a content writer. Create compelling content based on research."),
)
reviewer := agent.NewLLMAgent(ctx, "reviewer",
agent.WithModel(m),
agent.WithInstruction("You are a content reviewer. Ensure quality and accuracy."),
)
// Create sequential workflow
workflow := agent.NewSequentialAgent("content_pipeline",
agent.WithSubAgents(researcher, writer, reviewer),
agent.WithDescription("Complete content creation pipeline"),
)
// ... run workflow
}
ADK Go follows a hierarchical, event-driven architecture with strong type safety and extensibility:
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Agent │ │ Model │ │ Tools │
│ System │◄──►│ Layer │◄──►│ Ecosystem │
│ │ │ │ │ │
├─────────────────┤ ├─────────────────┤ ├─────────────────┤
│ • LLMAgent │ │ • Google Gemini │ │ • Function Tools│
│ • Sequential │ │ • Anthropic │ │ • Agent Tools │
│ • Parallel │ │ • Multi-provider│ │ • Auth Tools │
│ • Loop │ │ • Streaming │ │ • Toolsets │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
└───────────────────────┼───────────────────────┘
│
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Flow │ │ Event │ │ Session │
│ Management │ │ System │ │ Management │
│ │ │ │ │ │
├─────────────────┤ ├─────────────────┤ ├─────────────────┤
│ • LLMFlow │ │ • Streaming │ │ • State Mgmt │
│ • AutoFlow │ │ • Real-time │ │ • Memory │
│ • SingleFlow │ │ • Event Actions │ │ • Persistence │
│ • Processors │ │ • Deltas │ │ • Three-tier │
└─────────────────┘ └─────────────────┘ └─────────────────┘
taskCompleted() flow controliter.Seq2[*Event, error] for real-time processingtypes/ enable extensibilityWithXxx() functionsagent/)// Create different agent types
llmAgent := agent.NewLLMAgent(ctx, "assistant", ...)
seqAgent := agent.NewSequentialAgent("workflow", ...)
parAgent := agent.NewParallelAgent("concurrent", ...)
loopAgent := agent.NewLoopAgent("repeater", ...)
model/)// Multi-provider support
gemini, _ := model.NewGoogleModel("gemini-2.0-flash-exp")
claude, _ := model.NewAnthropicModel("claude-3-5-sonnet-20241022")
// Registry pattern
model.RegisterModel("custom-model", customModelFactory)
m, _ := model.GetModel("custom-model")
tool/)// Function tools with automatic declaration generation
tool := tools.NewFunctionTool("my_function", myFunc,
tools.WithDescription("Description of the function"),
tools.WithParameterDescription("param", "Parameter description"),
)
// Custom tools
type CustomTool struct {
*tool.Tool
}
func (t *CustomTool) Run(ctx context.Context, args map[string]any, toolCtx *types.ToolContext) (any, error) {
// Tool implementation
return result, nil
}
memory/)// In-memory storage
memService := memory.NewInMemoryService()
// Vertex AI RAG (future)
ragService := memory.NewVertexAIRAGService(projectID, location)
// Store and retrieve memories
memService.AddSession(ctx, sessionID, "Important information")
memories, _ := memService.SearchMemories(ctx, "search query")
session/)// Three-tier state management
state := map[string]any{
"app:theme": "dark", // Application-wide
"user:preference": "verbose", // User-specific
"temp:calculation": 42, // Session-temporary
}
sessionService := session.NewInMemoryService()
sess, _ := sessionService.CreateSession(ctx, appName, userID, sessionID, state)
codeAgent := agent.NewLLMAgent(ctx, "coder",
agent.WithModel(model),
agent.WithInstruction("You are a coding assistant. Write and execute code to solve problems."),
agent.WithCodeExecutor(codeexecutor.NewBuiltInExecutor()), // Use model's native execution
)
type APITool struct {
*tool.Tool
}
func (t *APITool) Run(ctx context.Context, args map[string]any, toolCtx *types.ToolContext) (any, error) {
// Request API key if not available
if !toolCtx.HasCredential("api_key") {
toolCtx.RequestCredential("api_key", &types.AuthConfig{
Type: types.AuthTypeAPIKey,
Description: "API key for external service",
})
return "Please provide your API key", nil
}
// Use the API key
apiKey := toolCtx.GetCredential("api_key")
// ... make API call
}
for event, err := range agent.Run(ctx, ictx) {
if err != nil {
if errors.Is(err, context.Canceled) {
log.Println("Operation canceled")
break
}
log.Printf("Error: %v", err)
continue
}
// Process different event types
switch {
case event.Message != nil:
fmt.Printf("Message: %s\n", event.Message.Text)
case event.ToolCall != nil:
fmt.Printf("Tool call: %s\n", event.ToolCall.Name)
case event.Actions != nil && event.Actions.StateDelta != nil:
fmt.Printf("State update: %+v\n", event.Actions.StateDelta)
}
}
Run tests with API keys:
Selected from shared topics, language and repository description—not editorial ratings.
google /
An open-source, code-first Go toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.