Agent Go SDK

A powerful Go framework for building production-ready AI agents that seamlessly integrates memory management, tool execution, multi-LLM support, and enterprise features into a flexible, extensible architecture.

Documentation

📖 docs.goagents.dev — Full documentation, guides, and reference.

Community

Join our Discord server to collaborate, share what you're building, and get community support for agent-sdk-go!

Features

Core Capabilities

• 🧠 Multi-Model Intelligence: Seamless integration with OpenAI, Anthropic, and Google Vertex AI (Gemini models).
• 🔧 Modular Tool Ecosystem: Expand agent capabilities with plug-and-play tools for web search, data retrieval, and custom operations
• 📝 Advanced Memory Management: Persistent conversation tracking with buffer and vector-based retrieval options
• 🔌 MCP Integration: Support for Model Context Protocol (MCP) servers via HTTP and stdio transports
• 📊 Token Usage Tracking: Built-in token counting for cost monitoring, usage analytics, and optimization

Enterprise-Ready

• 🚦 Built-in Guardrails: Comprehensive safety mechanisms for responsible AI deployment
• 📈 Complete Observability: Integrated tracing and logging for monitoring and debugging
• 🏢 Enterprise Multi-tenancy: Securely support multiple organizations with isolated resources

Development Experience

• 🛠️ Structured Task Framework: Plan, approve, and execute complex multi-step operations
• 📄 Declarative Configuration: Define sophisticated agents and tasks using intuitive YAML definitions
• 🧙 Zero-Effort Bootstrapping: Auto-generate complete agent configurations from simple system prompts

Getting Started

Prerequisites

• Go 1.23+
• Redis (optional, for distributed memory)

Installation

As a Go Library

Add the SDK to your Go project:

go get github.com/Ingenimax/agent-sdk-go

As a CLI Tool (Headless SDK)

Option 1: Download Pre-built Binaries (Recommended)

Download the latest release for your platform from GitHub Releases and add it to your PATH.

Option 2: Install via Go

go install github.com/Ingenimax/agent-sdk-go/cmd/agent-cli@latest

Option 3: Build from Source

# Clone the repository
git clone https://github.com/Ingenimax/agent-sdk-go
cd agent-sdk-go

# Build the CLI tool
make build-cli

# Install to system PATH (optional)
make install

Quick CLI Start:

# Initialize configuration
agent-cli init

# Option 1: Set environment variables
export OPENAI_API_KEY=your_api_key_here

# Option 2: Use .env file (recommended)
cp env.example .env
# Edit .env with your API keys

# Run a simple query
agent-cli run "What's the weather in San Francisco?"

# Start interactive chat
agent-cli chat

Configuration

The SDK uses environment variables for configuration. Key variables include:

• OPENAI_API_KEY: Your OpenAI API key
• OPENAI_MODEL: The model to use (e.g., gpt-4o-mini)
• LOG_LEVEL: Logging level (debug, info, warn, error)
• REDIS_ADDRESS: Redis server address (if using Redis for memory)

See .env.example for a complete list of configuration options.

Get Help with Nina (AI Assistant)

Nina is an AI assistant that knows the agent-sdk-go codebase inside and out. Connect to Nina via MCP (Model Context Protocol) to get help directly in your IDE.

Cursor IDE

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "agent-sdk-go": {
      "url": "https://nina.agentgogo.app/mcp",
      "transport": "sse"
    }
  }
}

Restart Cursor IDE and Nina's tools will be available in your AI assistant.

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "agent-sdk-go": {
      "url": "https://nina.agentgogo.app/mcp",
      "transport": "sse"
    }
  }
}

Restart Claude Desktop and Nina's tools will be available via the 🔌 icon.

Available Tools

Usage Examples

Creating a Simple Agent

package main

import (
    "context"
    "fmt"

    "github.com/Ingenimax/agent-sdk-go/pkg/agent"
    "github.com/Ingenimax/agent-sdk-go/pkg/config"
    "github.com/Ingenimax/agent-sdk-go/pkg/llm/openai"
    "github.com/Ingenimax/agent-sdk-go/pkg/logging"
    "github.com/Ingenimax/agent-sdk-go/pkg/memory"
    "github.com/Ingenimax/agent-sdk-go/pkg/multitenancy"
    "github.com/Ingenimax/agent-sdk-go/pkg/tools"
    "github.com/Ingenimax/agent-sdk-go/pkg/tools/websearch"
)

func main() {
    // Create a logger
    logger := logging.New()

    // Get configuration
    cfg := config.Get()

    // Create a new agent with OpenAI
    openaiClient := openai.NewClient(cfg.LLM.OpenAI.APIKey,
        openai.WithLogger(logger))

    agent, err := agent.NewAgent(
        agent.WithLLM(openaiClient),
        agent.WithMemory(memory.NewConversationBuffer()),
        agent.WithTools(createTools(logger).List()...),
        agent.WithSystemPrompt("You are a helpful AI assistant. When you don't know the answer or need real-time information, use the available tools to find the information."),
        agent.WithName("ResearchAssistant"),
    )
    if err != nil {
        logger.Error(context.Background(), "Failed to create agent", map[string]interface{}{"error": err.Error()})
        return
    }

    // Create a context with organization ID and conversation ID
    ctx := context.Background()
    ctx = multitenancy.WithOrgID(ctx, "default-org")
    ctx = context.WithValue(ctx, memory.ConversationIDKey, "conversation-123")

    // Run the agent
    response, err := agent.Run(ctx, "What's the weather in San Francisco?")
    if err != nil {
        logger.Error(ctx, "Failed to run agent", map[string]interface{}{"error": err.Error()})
        return
    }

    fmt.Println(response)
}

func createTools(logger logging.Logger) *tools.Registry {
    // Get configuration
    cfg := config.Get()

    // Create tools registry
    toolRegistry := tools.NewRegistry()

    // Add web search tool if API keys are available
    if cfg.Tools.WebSearch.GoogleAPIKey != "" && cfg.Tools.WebSearch.GoogleSearchEngineID != "" {
        searchTool := websearch.New(
            cfg.Tools.WebSearch.GoogleAPIKey,
            cfg.Tools.WebSearch.GoogleSearchEngineID,
        )
        toolRegistry.Register(searchTool)
    }

    return toolRegistry
}

Token Usage Tracking

The SDK provides built-in token usage tracking for cost monitoring and usage analytics. You can access token information using the detailed generation methods:

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/Ingenimax/agent-sdk-go/pkg/llm/anthropic"
)

func main() {
    // Create LLM client
    client := anthropic.NewClient("your-api-key",
        anthropic.WithModel("claude-3-haiku-20240307"),
    )

    ctx := context.Background()
    prompt := "Explain quantum computing in one paragraph."

    // Traditional method (backward compatible)
    content, err := client.Generate(ctx, prompt)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Response: %s\n", content)

    // New detailed method with token usage
    response, err := client.GenerateDetailed(ctx, prompt)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Response: %s\n", response.Content)
    fmt.Printf("Model: %s\n", response.Model)

    if response.Usage != nil {
        fmt.Printf("Token Usage:\n")
        fmt.Printf("  Input Tokens: %d\n", response.Usage.InputTokens)
        fmt.Printf("  Output Tokens: %d\n", response.Usage.OutputTokens)
        fmt.Printf("  Total Tokens: %d\n", response.Usage.TotalTokens)

        // Calculate estimated cost (adjust based on actual pricing)
        inputCost := float64(response.Usage.InputTokens) * 0.25 / 1000000
        outputCost := float64(response.Usage.OutputTokens) * 1.25 / 1000000
        fmt.Printf("  Estimated Cost: $%.6f\n", inputCost + outputCost)
    }
}

Available Methods: - Generate() - Traditional method returning string (unchanged) - GenerateDetailed() - New method returning *LLMResponse with usage info - GenerateWithTools() - Traditional method with tools (unchanged) - GenerateWithToolsDetailed() - New method with tools and usage info

Provider Support: - ✅ Anthropic: Full token usage support - ✅ OpenAI: Full support including reasoning tokens - ✅ Azure OpenAI: Full support (similar to OpenAI) - ❌ Ollama/vLLM: Local models don't provide usage data (Usage=nil)

See the token usage example for a complete demonstration.

Advanced YAML Configuration

The SDK now supports comprehensive YAML-based agent configuration with advanced features including behavioral settings, tool configuration, MCP integration, sub-agents, and environment variable expansion.

Example: Complete Agent with YAML Configuration

package main

import (
    "context"
    "log"
    "os"

    "github.com/Ingenimax/agent-sdk-go/pkg/agent"
    "github.com/Ingenimax/agent-sdk-go/pkg/llm/openai"
)

func main() {
    // Create LLM client
    llm := openai.NewClient(os.Getenv("OPENAI_API_KEY"))

    // Load agent configurations from YAML
    configs, err := agent.LoadAgentConfigsFromFile("agents.yaml")
    if err != nil {
        log.Fatal(err)
    }

    // Create agent directly from configuration
    agentInstance, err := agent.NewAgentFromConfig("research_assistant", configs, nil, agent.WithLLM(llm))
    if err != nil {
        log.Fatal(err)
    }

    // Run the agent
    result, err := agentInstance.Run(context.Background(), "What are the latest developments in renewable energy?")
    if err != nil {
        log.Fatal(err)
    }

    println(result)
}

agents.yaml (Advanced Configuration):

research_assistant:
  role: "Advanced Research Assistant"
  goal: "Provide comprehensive research and analysis"
  backstory: "Expert researcher with access to multiple data sources and specialized sub-agents"

  # Behavioral settings
  max_iterations: 15
  require_plan_approval: false

  # LLM configuration
  llm_config:
    temperature: 0.7
    enable_reasoning: true
    reasoning_budget: 20000

  # Built-in and custom tools
  tools:
    - type: "builtin"
      name: "websearch"
      enabled: true
      config:
        api_key: "${SEARCH_API_KEY}"
        engine: "brave"

    - type: "builtin"
      name: "calculator"
      enabled: true

  # MCP server integration
  mcp:
    mcpServers:
      filesystem:
        command: "npx"
        args: ["-y", "@modelcontextprotocol/server-filesystem", "."]

      database:
        command: "python"
        args: ["-m", "mcp_server_database"]
        env:
          DATABASE_URL: "${DATABASE_URL}"

  # Memory configuration
  memory:
    type: "redis"
    config:
      address: "${REDIS_ADDRESS}"
      db: 0

  # Sub-agents for specialized tasks
  sub_agents:
    data_analyzer:
      role: "Data Analysis Specialist"
      goal: "Analyze complex datasets and provide insights"
      backstory: "Expert in statistical analysis and data visualization"
      max_iterations: 8
      llm_config:
        temperature: 0.3

    report_writer:
      role: "Technical Writer"
      goal: "Create comprehensive reports and documentation"
      backstory: "Skilled at converting complex data into clear reports"
      tools:
        - type: "builtin"
          name: "text_processor"
          enabled: true

  # Runtime settings
  runtime:
    log_level: "info"
    enable_tracing: true
    timeout: "300s"

Key Features of Advanced YAML Configuration:

• Environment Variable Expansion: Use ${VAR} syntax for sensitive data
• Behavioral Settings: Configure iterations, plan approval, and runtime behavior
• LLM Configuration: Fine-tune temperature, reasoning, and model-specific settings
• Tool Integration: Configure built-in, custom, MCP, and agent tools declaratively
• Sub-Agents: Create hierarchical agent structures with specialized capabilities
• Memory Backends: Configure buffer, Redis, or vector memory systems
• MCP Integration: Seamless Model Context Protocol server configuration
• Structured Responses: Define JSON schema for consistent output formats

Creating an Agent with YAML Configuration (Basic)

```go package main

import ( "context" "fmt" "log" "os" "path/filepath" "strings"

"github.com/Ingenimax/agent-sdk-go/pkg/agent"
"github.com/Ingenimax/agent-sdk-go/pkg/llm/openai"

)

func main() { // Get OpenAI API key from environment apiKey := os.Getenv("OPENAI_API_KEY") if apiKey == "" { log.Fatal("OpenAI API key not provided. Set OPENAI_API_KEY environment variable.") }

// Create the LLM client
llm := openai.NewClient(apiKey)

// Load agent configurations
agentConfigs, err := agent.LoadAgentConfigsFromFile("agents.yaml")
if err != nil {
    log.Fatalf("Failed to load agent configurations: %v", err)
}

// Load task configurations
taskConfigs, err := agent.LoadTaskConfigsFromFile("tasks.yaml")
if err != nil {
    log.Fatalf("Failed to load task configurations: %v", err)
}

// Create variables map for template substitution
variables := map[string]string{
    "topic": "Artificial Intelligence",
}

// Create the agent for a specific task
taskName := "research_task"
agent, err := agent.CreateAgentForTask(taskName, agentConfigs, taskConfigs, variables, agent.WithLLM(llm))
if err != nil {
    log.Fatalf("Failed to create agent for task: %v", err)
}

// Execute the task
fmt.Printf("Executing