agent-sdk-go

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.

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, vector-based retrieval and summarization
• 🔌 MCP Integration: Model Context Protocol servers over streamable HTTP, SSE and stdio
• 📊 Token Usage Tracking: Built-in token counting for cost monitoring, usage analytics, and optimization
• 💬 Session Persistence (NEW): Durable conversations with scoped state, listing and resume — in-memory, Postgres or SQLite. Docs
• 📚 Agent Skills (NEW): SKILL.md capability bundles loaded from disk, with progressive disclosure so a large library stays cheap. Docs
• 🌙 Memory Consolidation (NEW): Distil an idle conversation into durable facts — merges, corrections and generalizations — proposed for review rather than silently written. Docs
• ⚡ Prompt Caching (NEW): Capability-aware caching that tells you which providers honor it, instead of silently doing nothing. Docs

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
• 🪝 Hooks & Plugins (NEW): Intercept every tool call to audit, deny, rewrite or redact — bundled as named plugins, reaching all LLM providers. Docs
• ⏱️ Background Runs (NEW): Run identity, a live registry and cancel-by-ID, so work in flight can be observed and stopped. Docs

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
• 🕸️ Multi-Agent Patterns (NEW): Sequential, parallel, loop and graph composition over a registry of agents. Docs
• 🔀 Agent Transfer (NEW): Let the model hand a conversation to a better-suited agent through a constrained tool call. Docs
• 🧩 Tool Pipeline (NEW): One ordered decorator chain around every tool call, reaching all providers without touching any. Docs
• 🧪 Agent Evaluation (NEW): Versioned datasets, correlated tool traces, deterministic graders, optional model judges, and JSON/JUnit reports. Docs

Upgrading an existing deployment? This line removes remote configuration loading (it allowed the config service to execute local binaries) and fixes several features that were silently not working — most importantly input guardrails, which had no effect whenever memory was configured. See docs/upgrading.md for every behaviour change, removal and migration path.

Getting Started

Prerequisites

• Go 1.26+
• 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)

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 task '%s' with topic '%s'...\n", taskName, variables["topic"])
	result, err := agent.ExecuteTaskFromConfig(context.Background(), taskName, taskConfigs, variables)
	if err != nil {
		log.Fatalf("Failed to execute task: %v", err)
	}

	// Print the result
	fmt.Println("\nTask Result:")
	fmt.Println(result)
}

Example YAML configurations:

agents.yaml:

researcher:
  role: >
    {topic} Senior Data Researcher
  goal: >
    Uncover cutting-edge developments in {topic}
  backstory: >
    You're a seasoned researcher with a knack for uncovering the latest
    developments in {topic}. Known for your ability to find the most relevant
    information and present it in a clear and concise manner.

reporting_analyst:
  role: >
    {topic} Reporting Analyst
  goal: >
    Create detailed reports based on {topic} data analysis and research findings
  backstory: >
    You're a meticulous analyst with a keen eye for detail. You're known for
    your ability to turn complex data into clear and concise reports, making
    it easy for others to understand and act on the information you provide.

tasks.yaml:

research_task:
  description: >
    Conduct a thorough research about {topic}
    Make sure you find any interesting and relevant information given
    the current year is 2025.
  expected_output: >
    A list with 10 bullet points of the most relevant information about {topic}
  agent: researcher

reporting_task:
  description: >
    Review the context you got and expand each topic into a full section for a report.
    Make sure the report is detailed and contains any and all relevant information.
  expected_output: >
    A fully fledged report with the main topics, each with a full section of information.
    Formatted as markdown without '```'
  agent: reporting_analyst
  output_file: "{topic}_report.md"

Structured Output with YAML Configuration

The SDK supports defining structured output (JSON responses) directly in YAML configuration files. This allows you to automatically apply structured output when creating agents from YAML and unmarshal responses directly into Go structs.

agents.yaml with structured output:

researcher:
  role: >
    {topic} Senior Data Researcher
  goal: >
    Uncover cutting-edge developments in {topic}
  backstory: >
    You're a seasoned researcher with a knack for uncovering the latest
    developments in {topic}. Known for your ability to find the most relevant
    information and present it in a clear and concise manner.
  response_format:
    type: "json_object"
    schema_name: "ResearchResult"
    schema_definition:
      type: "object"
      properties:
        findings:
          type: "array"
          items:
            type: "object"
            properties:
              title:
                type: "string"
                description: "Title of the finding"
              description:
                type: "string"
                description: "Detailed description"
              source:
                type: "string"
                description: "Source of the information"
        summary:
          type: "string"
          description: "Executive summary of findings"
        metadata:
          type: "object"
          properties:
            total_findings:
              type: "integer"
            research_date:
              type: "string"

tasks.yaml with structured output:

research_task:
  description: >
    Conduct a thorough research about {topic}
    Make sure you find any interesting and relevant information.
  expected_output: >
    A structured JSON response with findings, summary, and metadata
  agent: researcher
  output_file: "{topic}_report.json"
  response_format:
    type: "json_object"
    schema_name: "ResearchResult"
    schema_definition:
      # Same schema as above

Usage in Go code:

// Define your Go struct to match the YAML schema
type ResearchResult struct {
    Findings []struct {
        Title       string `json:"title"`
        Description string `json:"description"`
        Source      string `json:"source"`
    } `json:"findings"`
    Summary  string `json:"summary"`
    Metadata struct {
        TotalFindings int    `json:"total_findings"`
        ResearchDate  string `json:"research_date"`
    } `json:"metadata"`
}

// Create agent and execute task
agent, err := agent.CreateAgentForTask("research_task", agentConfigs, taskConfigs, variables, agent.WithLLM(llm))
result, err := agent.ExecuteTaskFromConfig(context.Background(), "research_task", taskConfigs, variables)

// Unmarshal structured output
var structured ResearchResult
err = json.Unmarshal([]byte(result), &structured)

For more details, see Structured Output with YAML Configuration.

Auto-Generating Agent Configurations

package main

import (
	"context"
	"fmt"
	"os"

	"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"
)

func main() {
	// Load configuration
	cfg := config.Get()

	// Create LLM client
	openaiClient := openai.NewClient(cfg.LLM.OpenAI.APIKey)

	// Create agent with auto-configuration from system prompt
	agent, err := agent.NewAgentWithAutoConfig(
		context.Background(),
		agent.WithLLM(openaiClient),
		agent.WithSystemPrompt("You are a travel advisor who helps users plan trips and vacations. You specialize in finding hidden gems and creating personalized itineraries based on travelers' preferences."),
		agent.WithName("Travel Assistant"),
	)
	if err != nil {
		panic(err)
	}

	// Access the generated configurations
	agentConfig := agent.GetGeneratedAgentConfig()
	taskConfigs := agent.GetGeneratedTaskConfigs()

	// Print generated agent details
	fmt.Printf("Generated Agent Role: %s\n", agentConfig.Role)
	fmt.Printf("Generated Agent Goal: %s\n", agentConfig.Goal)
	fmt.Printf("Generated Agent Backstory: %s\n", agentConfig.Backstory)

	// Print generated tasks
	fmt.Println("\nGenerated Tasks:")
	for taskName, taskConfig := range taskConfigs {
		fmt.Printf("- %s: %s\n", taskName, taskConfig.Description)
	}

	// Save the generated configurations to YAML files
	agentConfigMap := map[string]agent.AgentConfig{
		"Travel Assistant": *agentConfig,
	}

	// Save agent configs to file
	agentYaml, _ := os.Create("agent_config.yaml")
	defer agentYaml.Close()
	agent.SaveAgentConfigsToFile(agentConfigMap, agentYaml)

	// Save task configs to file
	taskYaml, _ := os.Create("task_config.yaml")
	defer taskYaml.Close()
	agent.SaveTaskConfigsToFile(taskConfigs, taskYaml)

	// Use the auto-configured agent
	response, err := agent.Run(context.Background(), "I want to plan a 3-day trip to Tokyo.")
	if err != nil {
		panic(err)
	}
	fmt.Println(response)
}

The auto-configuration feature uses LLM reasoning to derive a complete agent profile and associated tasks from a simple system prompt. The generated configurations include:

• Agent Profile: Role, goal, and backstory that define the agent's persona
• Task Definitions: Specialized tasks the agent can perform, with descriptions and expected outputs
• Reusable YAML: Save configurations for reuse in other applications

This approach dramatically reduces the effort needed to create specialized agents while ensuring consistency and quality.

Using MCP Servers with an Agent

The SDK supports both eager and lazy MCP server initialization:

• Eager: MCP servers are initialized when the agent is created
• Lazy: MCP servers are initialized only when their tools are first called (recommended)

Lazy MCP Integration (Recommended)

package main

import (
	"context"
	"fmt"
	"log"
	"os"

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

func main() {
	// Create OpenAI LLM client
	apiKey := os.Getenv("OPENAI_API_KEY")
	llm := openai.NewClient(apiKey, openai.WithModel("gpt-4o-mini"))

	// Define lazy MCP configurations
	// Note: The CLI supports dynamic tool discovery, but the SDK requires explicit tool definitions
	lazyMCPConfigs := []agent.LazyMCPConfig{
		{
			Name:    "aws-api-server",
			Type:    "stdio",
			Command: "docker",
			Args:    []string{"run", "--rm", "-i", "public.ecr.aws/awslabs-mcp/awslabs/aws-api-mcp-server:latest"},
			Env:     []string{"AWS_REGION=us-west-2"},
			Tools: []agent.LazyMCPToolConfig{
				{
					Name:        "suggest_aws_commands",
					Description: "Suggest AWS CLI commands based on natural language",
					Schema:      map[string]interface{}{"type": "object", "properties": map[string]interface{}{"query": map[string]interface{}{"type": "string"}}},
				},
			},
		},
		{
			Name:    "kubectl-ai",
			Type:    "stdio",
			Command: "kubectl-ai",
			Args:    []string{"--mcp-server"},
			Tools: []agent.LazyMCPToolConfig{
				{
					Name:        "kubectl",
					Description: "Execute kubectl commands against Kubernetes cluster",
					Schema:      map[string]interface{}{"type": "object", "properties": map[string]interface{}{"command": map[string]interface{}{"type": "string"}}},
				},
			},
		},
	}

	// Create agent with lazy MCP configurations
	myAgent, err := agent.NewAgent(
		agent.WithLLM(llm),
		agent.WithLazyMCPConfigs(lazyMCPConfigs),
		agent.WithMemory(memory.NewConversationBuffer()),
		agent.WithSystemPrompt("You are an AI assistant with access to AWS and Kubernetes tools."),
	)
	if err != nil {
		log.Fatalf("Failed to create agent: %v", err)
	}

	// Use the agent - MCP servers will be initialized on first tool use
	response, err := myAgent.Run(context.Background(), "List my EC2 instances and show cluster pods")
	if err != nil {
		log.Fatalf("Failed to run agent: %v", err)
	}

	fmt.Println("Agent Response:", response)
}

Eager MCP Integration

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/Ingenimax/agent-sdk-go/pkg/agent"
	"github.com/Ingenimax/agent-sdk-go/pkg/interfaces"
	"github.com/Ingenimax/agent-sdk-go/pkg/llm/openai"
	"github.com/Ingenimax/agent-sdk-go/pkg/mcp"
	"github.com/Ingenimax/agent-sdk-go/pkg/memory"
	"github.com/Ingenimax/agent-sdk-go/pkg/multitenancy"
)

func main() {
	logger := log.New(os.Stderr, "AGENT: ", log.LstdFlags)

	// Create OpenAI LLM client
	apiKey := os.Getenv("OPENAI_API_KEY")
	if apiKey == "" {
		logger.Fatal("Please set the OPENAI_API_KEY environment variable.")
	}
	llm := openai.NewClient(apiKey, openai.WithModel("gpt-4o-mini"))

	// Create MCP servers
	var mcpServers []interfaces.MCPServer

	// Connect to HTTP-based MCP server
	httpServer, err := mcp.NewHTTPServer(context.Background(), mcp.HTTPServerConfig{
		BaseURL: "http://localhost:8083/mcp",
	})
	if err != nil {
		logger.Printf("Warning: Failed to initialize HTTP MCP server: %v", err)
	} else {
		mcpServers = append(mcpServers, httpServer)
		logger.Println("Successfully initialized HTTP MCP server.")
	}

	// Connect to stdio-based MCP server
	stdioServer, err := mcp.NewStdioServer(context.Background(), mcp.StdioServerConfig{
		Command: "go",
		Args:    []string{"run", "./server-stdio/main.go"},
	})
	if err != nil {
		logger.Printf("Warning: Failed to initialize STDIO MCP server: %v", err)
	} else {
		mcpServers = append(mcpServers, stdioServer)
		logger.Println("Successfully initialized STDIO MCP server.")
	}

	// Create agent with MCP server support
	myAgent, err := agent.NewAgent(
		agent.WithLLM(llm),
		agent.WithMCPServers(mcpServers),
		agent.WithMemory(memory.NewConversationBuffer()),
		agent.WithSystemPrompt("You are an AI assistant that can use tools from MCP servers."),
		agent.WithName("MCPAgent"),
	)
	if err != nil {
		logger.Fatalf("Failed to create agent: %v", err)
	}

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

	// Run the agent with a query that will use MCP tools
	response, err := myAgent.Run(ctx, "What time is it right now?")
	if err != nil {
		logger.Fatalf("Agent run failed: %v", err)
	}

	fmt.Println("Agent response:", response)
}

Architecture

The SDK follows a modular architecture with these key components:

• Agent: Coordinates the LLM, memory, and tools
• LLM: Interface to language model providers (OpenAI, Anthropic, Google Vertex AI)
• Memory: Stores conversation history and context
• Tools: Extend the agent's capabilities
• Vector Store: For semantic search and retrieval
• Guardrails: Ensures safe and responsible AI usage
• Execution Plan: Manages planning, approval, and execution of complex tasks
• Configuration: YAML-based agent and task definitions

Supported LLM Providers

• OpenAI: GPT-4, GPT-3.5, and other OpenAI models
• Anthropic: Claude 3.5 Sonnet, Claude 3 Haiku, and other Claude models
• DeepSeek: DeepSeek-V3.2 chat and reasoning models
  • Native tool/function calling support
  • Cost-effective pricing with cache optimization
  • 128K token context window
  • Reasoning mode with up to 64K output tokens
  • Full feature parity with OpenAI/Anthropic
• Google Vertex AI: Gemini 1.5 Pro, Gemini 1.5 Flash, Gemini 2.0 Flash, and Gemini Pro Vision
  • Advanced reasoning modes (none, minimal, comprehensive)
  • Multimodal capabilities with vision models
  • Function calling and tool integration
  • Flexible authentication (ADC or service account files)
• Ollama: Local LLM server supporting various open-source models
  • Run models locally without external API calls
  • Support for Llama2, Mistral, CodeLlama, and other models
  • Model management (list, pull, switch models)
  • Local processing for reduced latency and privacy
• vLLM: High-performance local LLM inference with PagedAttention
  • Optimized for GPU inference with CUDA
  • Efficient memory management for large models
  • Support for Llama2, Mistral, CodeLlama, and other models
  • Model management (list, pull, switch models)
  • Local processing for reduced latency and privacy

CLI Tool (Headless SDK)

The Agent SDK includes a powerful command-line interface for headless usage:

CLI Features

• 🤖 Multiple LLM Providers: OpenAI, Anthropic, DeepSeek, Google Vertex AI, Ollama, vLLM
• 💬 Interactive Chat Mode: Real-time conversations with persistent memory
• 📝 Task Execution: Run predefined tasks from YAML configurations
• 🎨 Auto-Configuration: Generate agent configs from simple prompts
• 🔧 Flexible Configuration: JSON-based configuration with environment variables
• 🛠️ Rich Tool Integration: Web search, GitHub, MCP servers, and more
• 🔌 MCP Server Management: Add, list, remove, and test MCP servers
• 📄 .env File Support: Automatic loading of environment variables from .env files

CLI Commands

# Initialize configuration
agent-cli init

# Run agent with a single prompt
agent-cli run "Explain quantum computing in simple terms"

# Direct execution (no setup required)
agent-cli --prompt "What is 2+2?"

# Direct execution with MCP server
agent-cli --prompt "List my EC2 instances" \
  --mcp-config ./aws_api_server.json \
  --allowedTools "mcp__aws__suggest_aws_commands,mcp__aws__call_aws" \
  --dangerously-skip-permissions

# Execute predefined tasks
agent-cli task --agent-config=agents.yaml --task-config=tasks.yaml --task=research_task --topic="AI"

# Start interactive chat
agent-cli chat

# Generate configurations from system prompt
agent-cli generate --prompt="You are a travel advisor" --output=./configs

# List available resources
agent-cli list providers
agent-cli list models
agent-cli list tools

# Manage configuration
agent-cli config show
agent-cli config set provider anthropic

# Manage MCP servers
agent-cli mcp add --type=http --url=http://localhost:8083/mcp --name=my-server
agent-cli mcp list
agent-cli mcp remove --name=my-server

# Import/Export MCP servers from JSON config
agent-cli mcp import --file=mcp-servers.json
agent-cli mcp export --file=mcp-servers.json

# Direct execution with MCP servers and tool filtering
agent-cli --prompt "List my EC2 instances" \
  --mcp-config ./aws_api_server.json \
  --allowedTools "suggest_aws_commands,call_aws" \
  --dangerously-skip-permissions

# Kubernetes management with kubectl-ai
agent-cli --prompt "List all pods in the default namespace" \
  --mcp-config ./kubectl_ai.json \
  --allowedTools "kubectl" \
  --dangerously-skip-permissions

Advanced MCP Features

The CLI now supports dynamic tool discovery and flexible tool filtering:

• No Hardcoded Tools: MCP servers define their own tools and schemas
• Dynamic Discovery: Tools are discovered when MCP servers are first initialized
• Flexible Filtering: Use --allowedTools to specify exactly which tools can be used
• JSON Configuration: Load MCP server configurations from external JSON files
• Environment Variables: Each MCP server can specify custom environment variables

Popular MCP Servers:

• AWS API Server: AWS CLI operations and suggestions
• kubectl-ai: Kubernetes cluster management via natural language
• Filesystem Server: File system operations and management
• Database Server: SQL query execution and database operations

CLI Documentation

For complete CLI documentation, see: CLI README

Examples

Check out the cmd/examples directory for complete examples:

• Simple Agent: Basic agent with system prompt
• YAML Configuration: Defining agents and tasks in YAML
• Auto-Configuration: Generating agent configurations from system prompts
• Agent Config Wizard: Interactive CLI for creating and using agents
• MCP Integration: Using Model Context Protocol servers with agents
• Multi-LLM Support: Examples using OpenAI, Azure OpenAI, Anthropic, and Vertex AI
• Vertex AI Integration: Comprehensive examples with Gemini models, reasoning modes, and tools

LLM Provider Examples

• examples/llm/openai/: OpenAI integration examples
• examples/llm/azureopenai/: Azure OpenAI integration examples with deployment-based configuration
• examples/llm/anthropic/: Anthropic Claude integration examples
• examples/llm/ollama/: Ollama local LLM integration examples
• examples/llm/vllm/: vLLM high-performance local LLM integration examples

Agent GoGo - Deploy an agent based on this SDK quickly

• Self-host or launch your agent with our Cloud Gateway. Visit https://agentgogo.app to learn more

License

This project is licensed under the MIT License - see the LICENSE file for details.

Documentation

📖 Full documentation available at docs.goagents.dev

For more detailed information, you can also refer to the following documents:

• Environment Variables
• Memory
• Tracing
• Vector Store
• DataStore - PostgreSQL and Supabase integration for structured data
• LLM
• Multitenancy
• Task
• Tools
• Agent
• Execution Plan
• Guardrails
• MCP
• Tool Pipeline - interpose on every tool call
• Configuration Loader
• Configuration Merge
• Sub-Agents
• Multi-Agent Patterns - sequential, parallel, loop, graph
• Agent Capabilities - sessions, runs, hooks, skills, consolidation
• Token Usage Tracking
• Agent Evaluation - deterministic checks, model judges, tool trajectories, reports, and CLI execution
• Development
• Upgrading - breaking changes and migration paths

Frequently Asked Questions (FAQ)

What is Agent Go SDK?

Agent Go SDK is a powerful Go framework for building production-ready AI agents. It provides memory management, tool execution, multi-LLM support, and enterprise features in a flexible, extensible architecture.

What are the core capabilities?

What enterprise features are available?

What are the prerequisites?

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

How do I install Agent Go SDK?

As a Go library:

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

As a CLI tool:

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

Or download pre-built binaries from GitHub Releases.

How do I use the CLI?

# Initialize configuration
agent-cli init

# Set environment variables
export OPENAI_API_KEY=your_api_key

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

# Start interactive chat
agent-cli chat

What development features are available?

What LLM models are supported?

How do I configure environment?

Create .env file:

cp env.example .env
# Edit with your API keys

Where can I find documentation?

📖 Full documentation: docs.goagents.dev

Is Agent Go SDK free to use?

Agent Go SDK is open-source. Check repository for license details.

How can I contribute?

Contributions welcome via GitHub issues and pull requests.

Where can I get help?