Legacy API Reference

⚠️ Deprecation Notice: These APIs are deprecated. Please use the current APIs for all new projects.

This section documents the legacy core package APIs that were used in earlier versions of AgenticGoKit. These APIs are maintained for backward compatibility but will be removed in a future release.

---

Migration Recommended

If you're using any of these legacy APIs, we strongly recommend migrating to the current APIs:

• Legacy core.Agent → Use agenticgokit.NewBuilder() instead
• Legacy core.Orchestrator → Use agenticgokit.NewSequentialWorkflow() or similar
• Legacy core.Memory → Use agenticgokit.WithMemory() builder option

See the Migration Guide for detailed upgrade instructions.

---

📚 Legacy API Overview

These APIs are organized around the original core package concepts:

• Agent API - Individual agents that process events and states
• Orchestration API - Multi-agent coordination and workflow patterns
• State & Events - Data flow and communication between agents
• Memory API - Persistent storage, RAG, and knowledge management
• MCP Integration - Tool integration via Model Context Protocol
• Configuration API - System configuration and setup

---

🏗️ Legacy Architecture Overview

🚀 Quick Start

Basic Agent Creation

package main

import (
    "context"
    "fmt"
    "github.com/kunalkushwaha/agenticgokit/core"
)

func main() {
    // Create a simple agent
    agent := core.AgentHandlerFunc(func(ctx context.Context, event core.Event, state core.State) (core.AgentResult, error) {
        msg, _ := event.GetData()["message"].(string)
        return core.AgentResult{Data: map[string]any{"response": fmt.Sprintf("Processed: %s", msg)}}, nil
    })

    // Create a runner from config and register the agent
    runner, _ := core.NewRunnerFromConfig("agentflow.toml")
    _ = runner.RegisterAgent("processor", agent)

    // Start, emit, stop
    _ = runner.Start(context.Background())
    defer runner.Stop()

    _ = runner.Emit(core.NewEvent("processor", map[string]any{"message": "Hello, AgenticGoKit!"}, nil))
}

Multi-Agent Collaboration

func collaborativeExample() {
    agents := map[string]core.AgentHandler{
        "analyzer": core.AgentHandlerFunc(func(ctx context.Context, e core.Event, s core.State) (core.AgentResult, error) {
            text, _ := e.GetData()["text"].(string)
            return core.AgentResult{Data: map[string]any{"analysis": analyzeText(text)}}, nil
        }),
        "summarizer": core.AgentHandlerFunc(func(ctx context.Context, e core.Event, s core.State) (core.AgentResult, error) {
            text, _ := e.GetData()["text"].(string)
            return core.AgentResult{Data: map[string]any{"summary": summarizeText(text)}}, nil
        }),
    }

    runner, _ := core.NewRunnerFromConfig("agentflow.toml")
    _ = runner.Start(context.Background())
    defer runner.Stop()
    _ = runner.Emit(core.NewEvent("all", map[string]any{"text": "Long document text here..."}, nil))
}

🔧 Core Interfaces

Agent vs AgentHandler

AgenticGoKit provides two main interfaces for creating agents:

Agent Interface - Simple, state-based processing:

type Agent interface {
    Run(ctx context.Context, inputState State) (State, error)
    Name() string
}

AgentHandler Interface - Event-driven processing with rich results:

type AgentHandler interface {
    Run(ctx context.Context, event Event, state State) (AgentResult, error)
}

When to use which:

• Use Agent for simple, stateful transformations
• Use AgentHandler for event-driven systems with complex orchestration
• Use AgentHandlerFunc for quick function-based agents

Conversion Between Interfaces

// Convert Agent to AgentHandler
func ConvertAgentToHandler(agent Agent) AgentHandler {
    return core.ConvertAgentToHandler(agent)
}

// Convert function to AgentHandler
func ConvertFuncToHandler(fn func(context.Context, Event, State) (AgentResult, error)) AgentHandler {
    return core.AgentHandlerFunc(fn)
}

📊 Orchestration Patterns

AgenticGoKit supports multiple orchestration patterns:

Pattern	Description	Use Case
Route	Single agent per event (default)	Simple request-response
Collaborate	All agents process in parallel	Analysis, multiple perspectives
Sequential	Agents process in order	Data pipelines, workflows
Mixed	Hybrid collaborative + sequential	Complex business processes
Loop	Single agent iterative processing	Refinement, optimization

Pattern Selection Guide

// Choose orchestration pattern based on your needs
func chooseOrchestration(useCase string) core.OrchestrationMode {
    switch useCase {
    case "simple_processing":
        return core.OrchestrationRoute
    case "parallel_analysis":
        return core.OrchestrationCollaborate
    case "data_pipeline":
        return core.OrchestrationSequential
    case "complex_workflow":
        return core.OrchestrationMixed
    case "iterative_refinement":
        return core.OrchestrationLoop
    default:
        return core.OrchestrationRoute
    }
}

🧠 Memory and RAG

AgenticGoKit provides built-in support for persistent memory and RAG (Retrieval-Augmented Generation):

// Create memory-enabled agent
memoryConfig := core.AgentMemoryConfig{
    Provider:   "pgvector",
    Connection: "postgres://user:pass@localhost:5432/agents",
    AutoEmbed:  true,
}

memory, _ := core.NewMemory(memoryConfig)
llmProvider, _ := core.NewOpenAIProvider()

agent := core.NewMemoryEnabledAgent("assistant", llmProvider, memory)

🔧 Tool Integration

Integrate external tools via MCP (Model Context Protocol):

// Initialize MCP
core.QuickStartMCP()

// Create MCP-aware agent
llmProvider, _ := core.NewOpenAIProvider()
agent, _ := core.NewMCPAgent("assistant", llmProvider)

// Agent can now discover and use MCP tools automatically

Command Line Interface

CLI Reference

Complete reference for the agentcli command-line tool with the new consolidated command structure.

CLI Quick Reference

Quick reference card for the most commonly used CLI commands and patterns.

Key CLI Features:

• Simplified Create Command - Consolidated flags and template system
• Project Templates - Built-in and custom templates for common use cases
• External Template Support - JSON/YAML template definitions
• Interactive Mode - Guided project setup
• Template Management - Create, validate, and manage custom templates

Available commands:

• create - Create new projects with templates and consolidated flags
• template - Manage project templates (list, create, validate)
• trace - View execution traces and debugging information
• mcp - Manage MCP servers and tools
• cache - Cache management and optimization
• memory - Memory system debugging and inspection
• list - List available sessions and resources
• version - Show version information

API Design Principles

AgenticGoKit APIs follow these principles:

• Interface-based design - Clear separation of concerns
• Context-aware - All operations accept Go context
• Error handling - Explicit error returns and handling
• Configuration-driven - Behavior controlled through configuration
• Extensible - Plugin architecture for custom implementations

Type Definitions

All APIs use consistent type definitions:

// Core types
type State map[string]interface{}
type Event struct { /* ... */ }
type AgentResult struct { /* ... */ }

// Configuration types
type Config struct { /* ... */ }
type OrchestrationMode string

Usage Patterns

Common patterns across all APIs:

Context Usage

ctx := context.Background()
result, err := agent.Run(ctx, inputState)

Error Handling

if err != nil {
    log.Printf("Operation failed: %v", err)
    return err
}

Configuration Loading

config, err := core.LoadConfigFromWorkingDir()
if err != nil {
    return fmt.Errorf("failed to load config: %w", err)
}

Versioning

AgenticGoKit follows semantic versioning:

• Major versions - Breaking API changes
• Minor versions - New features, backward compatible
• Patch versions - Bug fixes, backward compatible

Migration Guides

When APIs change between versions, migration guides are provided:

• Breaking changes are documented
• Migration examples are provided
• Deprecation notices give advance warning

Getting Help

For API questions:

1. Check this reference documentation
2. Review code examples in tutorials
3. See how-to guides for specific use cases
4. Check the troubleshooting guide for common issues