Build AI Agents
in Go. Fast.

go get github.com/muhammadhamd/go-agentkit/

import (
    "github.com/muhammadhamd/go-agentkit/pkg/agent"
    "github.com/muhammadhamd/go-agentkit/pkg/runner"
    "github.com/muhammadhamd/go-agentkit/pkg/tool"
    "github.com/muhammadhamd/go-agentkit/pkg/model/providers/openai"
)

go mod tidy

require github.com/muhammadhamd/go-agentkit/ latest

# Create your project
mkdir my-agent && cd my-agent
go mod init github.com/yourname/my-agent

# Install go-agentkit
go get github.com/muhammadhamd/go-agentkit/

# Set your API key
export OPENAI_API_KEY=sk-...

package main

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

    "github.com/muhammadhamd/go-agentkit/pkg/agent"
    "github.com/muhammadhamd/go-agentkit/pkg/model/providers/openai"
    "github.com/muhammadhamd/go-agentkit/pkg/runner"
    "github.com/muhammadhamd/go-agentkit/pkg/tool"
)

func main() {
    // 1. Provider — connects to OpenAI
    provider := openai.NewProvider(os.Getenv("OPENAI_API_KEY"))
    provider.SetDefaultModel("gpt-4o-mini")

    // 2. Tool — a Go function the agent can call
    getWeather := tool.NewFunctionTool(
        "get_weather",
        "Get the current weather for a city",
        func(ctx context.Context, params map[string]interface{}) (interface{}, error) {
            city := params["city"].(string)
            return fmt.Sprintf("Weather in %s: 72°F, sunny.", city), nil
        },
    ).WithSchema(map[string]interface{}{
        "type": "object",
        "properties": map[string]interface{}{
            "city": map[string]interface{}{
                "type": "string",
                "description": "City name",
            },
        },
        "required": []string{"city"},
    })

    // 3. Agent — wraps the LLM with instructions + tools
    assistant := agent.NewAgent("Weather Assistant", "You are a weather assistant.")
    assistant.SetModelProvider(provider)
    assistant.WithModel("gpt-4o-mini")
    assistant.WithTools(getWeather)

    // 4. Runner — executes the agentic loop
    r := runner.NewRunner()
    r.WithDefaultProvider(provider)

    result, err := r.RunSync(assistant, &runner.RunOptions{
        Input: "What's the weather in Tokyo?",
    })
    if err != nil { log.Fatal(err) }

    fmt.Println(result.FinalOutput)
}

export OPENAI_API_KEY=sk-...
go run main.go

// Basic creation
a := agent.NewAgent("My Agent", "You are a helpful assistant.")

// Full configuration
a.SetModelProvider(provider)
a.WithModel("gpt-4o")
a.WithTools(tool1, tool2, tool3)       // multiple tools at once
a.WithHandoffs(billingAgent, supportAgent) // delegation targets
a.SetOutputType(MyStruct{})              // structured output

// Create a runner
r := runner.NewRunner()
r.WithDefaultProvider(provider)

// Synchronous run
result, err := r.RunSync(myAgent, &runner.RunOptions{
    Input:    "Process my request",
    MaxTurns: 10,             // prevent infinite loops
    Context:  myCustomContext,  // shared across agents
    RunConfig: &runner.RunConfig{
        TracingDisabled: false,
    },
})

// Async run with context
result, err := r.Run(ctx, myAgent, &runner.RunOptions{...})

// Streaming
stream, err := r.RunStreaming(ctx, myAgent, &runner.RunOptions{...})

// Access result
fmt.Println(result.FinalOutput)
fmt.Println(result.RunContext.(*runner.RunContext).Usage.TotalTokens)

myTool := tool.NewFunctionTool(
    "search_database",              // tool name (no spaces)
    "Search the user database",      // description for the LLM
    func(ctx context.Context, params map[string]interface{}) (interface{}, error) {
        query := params["query"].(string)
        limit := int(params["limit"].(float64))

        // Access tool call ID for tracing
        if id, ok := ctx.Value("tool_call_id").(string); ok {
            log.Printf("tool_call_id: %s", id)
        }

        results, err := db.Search(query, limit)
        if err != nil { return nil, err }
        return results, nil
    },
).WithSchema(map[string]interface{}{
    "type": "object",
    "properties": map[string]interface{}{
        "query": map[string]interface{}{
            "type": "string",
            "description": "Search query string",
        },
        "limit": map[string]interface{}{
            "type": "integer",
            "description": "Max results to return",
        },
    },
    "required": []string{"query"},
})

// Convert any FunctionTool to OpenAI format
openAITool := tool.ToOpenAITool(myTool)

// Add OpenAI-format definitions directly to an agent
a.AddToolFromDefinition(openAITool)
a.AddToolsFromDefinitions([]map[string]interface{}{tool1, tool2})

// Tools can require human approval before execution
// Approval state is tracked in RunContext.ToolApprovals
// Use NextStepInterruption to pause for user input

// Specialized agents
mathAgent := agent.NewAgent("Math Agent", "You handle math calculations.")
mathAgent.SetModelProvider(provider)
mathAgent.WithTools(calculatorTool)

weatherAgent := agent.NewAgent("Weather Agent", "You provide weather data.")
weatherAgent.SetModelProvider(provider)
weatherAgent.WithTools(weatherTool)

// Coordinator delegates to specialists
coordinator := agent.NewAgent("Coordinator", `
    Delegate math to Math Agent, weather to Weather Agent.
`)
coordinator.SetModelProvider(provider)
coordinator.WithHandoffs(mathAgent, weatherAgent)

result, err := r.RunSync(coordinator, &runner.RunOptions{
    Input:    "What's 42/6 and what's the weather in Paris?",
    MaxTurns: 20,
})

orchestrator := agent.NewAgent("Orchestrator", "Coordinate and analyze.")
worker := agent.NewAgent("Worker", "Process and return results.")
worker.WithTools(processingTool)

// Bidirectional: worker can return to orchestrator
orchestrator.WithHandoffs(worker)
worker.WithHandoffs(orchestrator) // ← the key line

// Key bidirectional primitives in handoff metadata:
//   TaskID:       unique task tracking ID
//   ReturnToAgent: which agent to return to
//   IsTaskComplete: signals task is done

// Filter conversation history during handoffs
// Removes tool calls, trims old messages, passes clean context
// Configured at the handoff level via InputFilter functions

// 1. Define your context type
type AppContext struct {
    UserID    string
    OrderID   string
    SessionID string
    Metadata  map[string]interface{}
}

// 2. Create and pass it to the runner
appCtx := &AppContext{
    UserID:   "user_123",
    SessionID: fmt.Sprintf("session_%d", time.Now().Unix()),
    Metadata: make(map[string]interface{}),
}

result, err := r.Run(ctx, agent, &runner.RunOptions{
    Input:   "Process order",
    Context: appCtx,
})

// 3. Read updated context from result
if rc, ok := result.RunContext.(*runner.RunContext); ok {
    if myCtx, ok := rc.Context.(*AppContext); ok {
        fmt.Println(myCtx.UserID)
        fmt.Println(rc.Usage.TotalTokens)
    }
}

func myToolFn(ctx context.Context, params map[string]interface{}) (interface{}, error) {
    // Get RunContext
    runCtxVal := ctx.Value("run_context")
    if runCtx, ok := runCtxVal.(*runner.RunContext); ok && runCtx != nil {
        if appCtx, ok := runCtx.Context.(*AppContext); ok {
            // Read from context
            userID := appCtx.UserID

            // Modify shared context (visible to ALL agents)
            appCtx.Metadata["last_tool"] = "myToolFn"
            _ = userID
        }
    }
    return "done", nil
}

import "github.com/muhammadhamd/go-agentkit/pkg/model"

streamResult, err := r.RunStreaming(ctx, myAgent, &runner.RunOptions{
    Input: "Tell me a long story",
})
if err != nil { log.Fatal(err) }

for event := range streamResult.Stream {
    switch event.Type {
    case model.StreamEventTypeContent:
        fmt.Print(event.Content)  // stream tokens as they arrive

    case model.StreamEventTypeToolCall:
        fmt.Printf("\n🔧 Calling: %s\n", event.ToolCall.Name)

    case model.StreamEventTypeHandoff:
        fmt.Printf("\n↪ Handoff to: %s\n", event.Handoff.TargetAgent)

    case model.StreamEventTypeDone:
        fmt.Println("\n✓ Complete")
    }
}

# Disable globally via environment variable
export OPENAI_AGENTS_DISABLE_TRACING=1
# or
export OPENAI_AGENTS_DISABLE_TRACING=true

// Per-run: disable tracing
r.RunSync(agent, &runner.RunOptions{
    Input: "hello",
    RunConfig: &runner.RunConfig{
        TracingDisabled: true,
    },
})

// Per-run: enable with custom workflow name
r.RunSync(agent, &runner.RunOptions{
    Input: "hello",
    RunConfig: &runner.RunConfig{
        TracingDisabled: false,
        TracingConfig: &runner.TracingConfig{
            WorkflowName: "my_workflow",
        },
    },
})

# General debug (runner + core)
DEBUG=1 go run .

# Provider-specific debug
OPENAI_DEBUG=1 go run .
ANTHROPIC_DEBUG=1 go run .
LMSTUDIO_DEBUG=1 go run .

# Combine flags
DEBUG=1 OPENAI_DEBUG=1 go run .

import "github.com/muhammadhamd/go-agentkit/test/mocks"

// In-memory state store (swap for DB in production)
stateStore := mocks.NewInMemoryStateStore()

workflowConfig := &runner.WorkflowConfig{
    // Retry configuration
    RetryConfig: &runner.RetryConfig{
        MaxRetries:         2,
        RetryDelay:         time.Second,
        RetryBackoffFactor: 2.0,
    },
    // State persistence
    StateManagement: &runner.StateManagementConfig{
        PersistState:        true,
        StateStore:          stateStore,
        CheckpointFrequency: 5 * time.Second,
    },
    // Pre-handoff validation
    ValidationConfig: &runner.ValidationConfig{
        PreHandoffValidation: []runner.ValidationRule{{
            Name: "StateNotNil",
            Validate: func(data interface{}) (bool, error) {
                state, ok := data.(*runner.WorkflowState)
                return ok && state != nil, nil
            },
            ErrorMessage: "Workflow state must not be nil",
            Severity:     runner.ValidationWarning,
        }},
    },
}

// WorkflowRunner wraps the base runner
wfRunner := runner.NewWorkflowRunner(baseRunner, workflowConfig)

state := &runner.WorkflowState{
    CurrentPhase:    "",
    CompletedPhases: make([]string, 0),
    Artifacts:       make(map[string]interface{}),
    LastCheckpoint:  time.Now(),
    Metadata:        make(map[string]interface{}),
}

result, err := wfRunner.RunWorkflow(ctx, agent, &runner.RunOptions{
    MaxTurns:       10,
    WorkflowConfig: workflowConfig,
    Input:          state,
})

# OpenAI examples
export OPENAI_API_KEY=sk-...
cd examples/openai_multi_agent_example && go run .

# Anthropic examples
export ANTHROPIC_API_KEY=sk-ant-...
cd examples/anthropic_handoff_example && go run .

# Local LLM (LM Studio must be running)
cd examples/multi_agent_example && go run .

# Complex flow test from repo root
go run -tags=store store.go

# 1. Fork & clone
git clone https://github.com/YOUR-USERNAME/go-agentkit.git
cd go-agentkit

# 2. Install tools
./scripts/ci_setup.sh

# 3. Create your branch
git checkout -b feature/my-feature

cd test && make test
# or
./scripts/check_all.sh

require github.com/muhammadhamd/go-agentkit v0.10.2

// Import path (case-insensitive on GitHub, but use lowercase)
import "github.com/muhammadhamd/go-agentkit/pkg/agent"