examples/

README

Go-LLMs Examples

This directory contains example applications demonstrating various features and capabilities of the Go-LLMs library. Each example is self-contained and includes its own documentation.

Example Categories

The examples are organized into the following categories:

• agent-* - Agent-specific features and patterns
• workflow-* - Workflow agent patterns (sequential, parallel, conditional, loop)
• provider-* - Provider-specific features and integrations
• builtins-* - Built-in tool demonstrations
• utils-* - Utility packages and helpers
• structured-* - Structured output and validation features

Quick Start

All examples can be run directly with Go:

# Navigate to any example directory
cd cmd/examples/<example-name>

# Run the example
go run main.go [args...]

# Or build and run the binary
go build -o example .
./example [args...]

Available Examples

Basic Usage

Simple

Basic usage patterns with mock providers. Perfect for getting started without API keys.

Features:

• Mock provider setup
• Basic text generation
• Error handling examples

cd simple && go run main.go

Agent Examples

Agent Simple LLM

Ultra-simple agent creation with string-based provider specification.

Features:

• Minimal agent setup
• Provider/model aliases
• String-based configuration
• State-based interface

export OPENAI_API_KEY="your-key"
cd agent-simple-llm && go run main.go

Agent Structured Output

LLM agents with structured output validation using schemas.

Features:

• Schema-driven LLM interactions
• Type-safe processing
• Complex data structures
• Real-world use cases (tasks, meetings, analysis)

export OPENAI_API_KEY="your-key"
cd agent-structured-output && go run main.go

Agent Calculator

Calculator tool usage with LLM agents.

Features:

• Built-in calculator tool integration
• Mathematical constant handling
• LLM tool calling patterns
• Debugging with conditional logging

cd agent-calculator && go run main.go

Agent Custom Research

Advanced custom agent extending BaseAgentImpl with code-based orchestration.

Features:

• Custom agent extending BaseAgentImpl (not LLMAgent)
• Code-based orchestration without library sub-agent features
• Multi-engine parallel search (Tavily, Brave, Serpapi, Serper.dev, DuckDuckGo)
• LLMAgent instances for intelligent processing (dedup, analysis, report)
• Complex state management between phases
• Comprehensive research report generation

export OPENAI_API_KEY="your-key"  # Optional for real LLM sub-agents
cd agent-custom-research && go run main.go

Agent LLM Built-in Tools

Demonstrates using built-in tools with LLM agents.

Features:

• Tool integration patterns
• Built-in tool usage
• State management with tools

export OPENAI_API_KEY="your-key"
cd agent-llm-builtin-tools && go run main.go

Agent Metrics Tools

Performance monitoring and metrics collection for agents with tools.

Features:

• Real LLM provider support (OpenAI, Anthropic, Gemini)
• ToolContext pattern demonstration
• Response time tracking
• Token usage monitoring
• Tool execution statistics
• Error rate analysis

export OPENAI_API_KEY="your-key"
cd agent-metrics-tools && go run main.go

Agent Tools Conversion

Bidirectional conversion between agents and tools with registry integration.

Features:

• Agent to Tool conversion
• Tool to Agent conversion
• Registry integration
• Event forwarding
• Schema mapping
• Tool chains

cd agent-tools-conversion && go run main.go

Agent Workflow as Tool

Multi-stage research pipeline demonstrating workflow agents wrapped as tools.

Features:

• Sequential workflow as tool
• Parallel workflow as tool
• Custom merge strategies
• LLM agent orchestration
• Real-world use case

export OPENAI_API_KEY="your-key"
cd agent-workflow-as-tool && go run main.go

Agent Advanced Tool Context

Advanced tool context features including state access and event emission.

Features:

• State access from tools
• Event emission
• Tool context patterns

cd agent-advanced-toolcontext && go run main.go

Agent Error Handling

Error handling patterns for agents.

Features:

• Error recovery strategies
• Retry mechanisms
• Graceful degradation

export OPENAI_API_KEY="your-key"
cd agent-error-handling && go run main.go

Agent State Persistence

State persistence and serialization for agents.

Features:

• State saving and loading
• Persistence strategies
• State migration

cd agent-state-persistence && go run main.go

Agent Guardrails

Input and output validation using guardrails.

Features:

• Input validation
• Output filtering
• Safety mechanisms

export OPENAI_API_KEY="your-key"
cd agent-guardrails && go run main.go

Agent Handoff

Agent-to-agent handoff patterns and delegation.

Features:

• Handoff builder pattern
• Agent chain execution
• Conditional routing
• State preservation

export OPENAI_API_KEY="your-key"
cd agent-handoff && go run main.go

Agent Multi-Coordination

Multiple agents coordinating to solve complex tasks.

Features:

• Multi-agent orchestration
• Parallel coordination
• Conditional routing
• Event monitoring

export OPENAI_API_KEY="your-key"
cd agent-multi-coordination && go run main.go

Agent Events

Enhanced event system for agent monitoring and bridge integration.

Features:

• EventBus with pattern-based subscriptions
• Advanced filtering (composite filters)
• Event serialization for bridge layer
• Event storage and replay
• Bridge-specific event types

cd agent-events && go run main.go

Agent Sub-Agents

Orchestrating multiple sub-agents for complex tasks.

Features:

• Sub-agent management
• Task delegation
• Result aggregation
• Hierarchical agent structures

export OPENAI_API_KEY="your-key"
cd agent-sub-agents && go run main.go

Workflow Examples

Workflow Sequential

Step-by-step processing with error handling and state management.

Features:

• Sequential execution
• Error handling strategies
• State passthrough between steps
• Hook integration

cd workflow-sequential && go run main.go

Workflow Parallel

Concurrent processing with configurable merge strategies.

Features:

• Concurrent agent execution
• Multiple merge strategies
• Configurable concurrency limits
• Timeout and error handling

cd workflow-parallel && go run main.go

Workflow Conditional

Branch-based execution with priority evaluation.

Features:

• Condition-based branching
• Priority-based evaluation
• Multiple match support
• Default branch handling

cd workflow-conditional && go run main.go

Workflow Loop

Iterative processing with count, while, and until loops.

Features:

• Count loops for fixed iterations
• While/until loops with conditions
• Result collection
• Iteration delays

cd workflow-loop && go run main.go

Workflow Hooks

Monitoring and instrumentation for workflow agents.

Features:

• Metrics collection
• Logging integration
• Hook composition
• Workflow monitoring

cd workflow-hooks && go run main.go

Workflow Composition

Complex workflow composition patterns.

Features:

• Nested workflows
• Dynamic composition
• Advanced patterns

cd workflow-composition && go run main.go

Workflow Multi-Provider

Agent-level multi-provider patterns using workflows.

Features:

• Agent-based provider strategies
• Consensus at agent level
• Fallback patterns

export OPENAI_API_KEY="your-key"
export ANTHROPIC_API_KEY="your-key"
cd workflow-multi-provider && go run main.go

Workflow Serialization

Workflow serialization for bridge layer integration.

Features:

• JSON/YAML workflow serialization
• Script-based workflow steps
• Multiple scripting language support
• Workflow templates
• Bridge layer deserialization

cd workflow-serialization && go run main.go

Provider Examples

Provider OpenAI

Direct integration with OpenAI's GPT models.

Features:

• Text generation
• Structured output
• Streaming responses
• Organization configuration

export OPENAI_API_KEY="your-key"
cd provider-openai && go run main.go

Provider Anthropic

Direct integration with Anthropic's Claude models.

Features:

• Conversation handling
• System prompts
• Claude-specific optimizations

export ANTHROPIC_API_KEY="your-key"
cd provider-anthropic && go run main.go

Provider Gemini

Direct integration with Google's Gemini models.

Features:

• Google AI integration
• Multimodal capabilities
• Safety settings

export GEMINI_API_KEY="your-key"
cd provider-gemini && go run main.go

Provider OpenAI Compatible

Working with OpenAI-compatible APIs.

Features:

• OpenRouter integration
• Ollama local models
• Custom API endpoints

export OPENROUTER_API_KEY="your-key"
cd provider-openai-compatible && go run main.go

Provider Multimodal

Comparison of multimodal capabilities across providers.

Features:

• Provider-specific multimodal support
• Image processing
• Audio/video handling (Gemini)
• File uploads and URLs

export OPENAI_API_KEY="your-key"
cd provider-multimodal && go run main.go -provider openai -mode image -a image.jpg

Provider Multi

Provider-level multi-provider strategies.

Features:

• Fastest strategy
• Primary with fallback
• Load balancing

Note: For agent-level multi-provider patterns, see workflow-multi-provider example.

export OPENAI_API_KEY="your-key"
export ANTHROPIC_API_KEY="your-key"
cd provider-multi && go run main.go

Provider Consensus

Provider-level consensus strategies.

Features:

• Similarity-based consensus
• Voting mechanisms
• Quality scoring

Note: For agent-level consensus patterns, see workflow-multi-provider example.

export OPENAI_API_KEY="your-key" 
export ANTHROPIC_API_KEY="your-key"
export GEMINI_API_KEY="your-key"
cd provider-consensus && go run main.go

Provider Ollama

Local model integration with Ollama.

Features:

• Local LLM hosting
• Model management
• Streaming support
• No API keys required

# Make sure Ollama is running locally
cd provider-ollama && go run main.go

Provider OpenRouter

Multi-model routing through OpenRouter.

Features:

• Access to 100+ models
• Single API for multiple providers
• Cost optimization
• Model comparison

export OPENROUTER_API_KEY="your-key"
cd provider-openrouter && go run main.go

Provider Vertex AI

Google Cloud Vertex AI integration.

Features:

• Enterprise-grade deployment
• Regional endpoints
• Service account authentication
• Model versioning

export GOOGLE_APPLICATION_CREDENTIALS="path/to/service-account.json"
cd provider-vertexai && go run main.go

Provider Options

Provider configuration options.

Features:

• Common options
• Provider-specific options
• Environment variables

export OPENAI_API_KEY="your-key"
cd provider-options && go run main.go

Provider Convenience

Provider-level utility functions and helpers.

Features:

• Provider pools
• Retry mechanisms
• Configuration helpers

cd provider-convenience && go run main.go

Built-in Tools Examples

The built-in tools system provides pre-made, optimized tools that follow standardized interfaces. All tools are discoverable through the registry system and offer enhanced capabilities over custom implementations.

Using Built-in Tools

All built-in tools follow the same pattern:

1. Import the category to trigger registration:

   import _ "github.com/lexlapax/go-llms/pkg/agent/builtins/tools/file"
   import _ "github.com/lexlapax/go-llms/pkg/agent/builtins/tools/web"
   import _ "github.com/lexlapax/go-llms/pkg/agent/builtins/tools/system"
   import _ "github.com/lexlapax/go-llms/pkg/agent/builtins/tools/data"
   import _ "github.com/lexlapax/go-llms/pkg/agent/builtins/tools/datetime"
   import _ "github.com/lexlapax/go-llms/pkg/agent/builtins/tools/feed"
   

2. Discover available tools:

   tools.Tools.List()                    // All tools
   tools.Tools.ListByCategory("file")    // By category
   tools.Tools.Search("read")            // By search term
   

3. Use the tools:

   tool, _ := tools.GetTool("file_read")
   result, err := tool.Execute(ctx, params)
   

Benefits Over Custom Tools

• Consistency: Standardized interfaces across all projects
• Features: Enhanced capabilities (streaming, timeouts, metadata)
• Discovery: Easy to find and understand available tools
• Maintenance: Updates and fixes handled centrally
• Performance: Optimized implementations with pooling

Built-ins Discovery

Focus: Registry discovery and basic usage

Features:

• How to discover available built-in tools
• Search and filter tools by category/tags
• Basic tool usage with agents
• Migration from custom tools to built-ins

When to use: Start here to understand the registry system and available tools.

cd builtins-discovery && go run main.go

Built-ins File Tools

Focus: Deep dive into file tool capabilities

Features:

• Enhanced file reading (streaming, metadata, line ranges)
• Atomic file writing with backups
• Binary file detection
• Large file handling
• Agent integration for file operations

When to use: When you need to understand the full capabilities of file tools.

cd builtins-file-tools && go run main.go

Built-ins Web Tools

Focus: Web interaction and HTTP operations

Features:

• Web fetching with timeouts and headers
• Web search using DuckDuckGo, Brave, Tavily, Serpapi, and Serper.dev
• Web scraping with CSS selectors
• Advanced HTTP requests (all methods, auth, custom headers)
• Response metadata and timing information

When to use: When you need to interact with web services, APIs, or scrape web content.

cd builtins-web-tools && go run main.go

Built-ins Web API Client

Focus: REST API interaction with authentication

Features:

• All HTTP methods with JSON support
• Multiple authentication methods (API key, Bearer, Basic)
• Path parameter substitution
• Custom headers and timeouts
• Comprehensive error handling

When to use: When you need to interact with REST APIs that require authentication and complex request handling.

cd builtins-web-api-client && go run main.go

Built-ins GraphQL Client

Focus: GraphQL API interaction with introspection and variable support

Features:

• GraphQL query and mutation execution
• Schema introspection and discovery
• Variable support for dynamic queries
• GraphQL-specific error handling
• Support for nested queries and field selection

When to use: When you need to interact with GraphQL APIs like GitHub GraphQL, Shopify, or other modern APIs.

cd builtins-graphql-client && go run main.go

Built-ins API Client Authentication

Focus: Advanced authentication features for API interactions

Features:

• OAuth2 bearer token and access token authentication
• Custom header authentication with prefixes
• Automatic authentication detection from state
• API key in headers, query parameters, or cookies
• Session/cookie management across requests
• OAuth2 configuration and token exchange
• Multiple authentication method fallbacks

When to use: When you need to interact with APIs that require advanced authentication methods beyond basic API keys.

cd builtins-api-client-auth && go run main.go

Built-ins OpenAPI Discovery

Focus: OpenAPI/Swagger specification discovery and validation

Features:

• OpenAPI 3.0/3.1 spec discovery
• Operation enumeration and metadata extraction
• Request validation against OpenAPI schemas
• LLM-friendly operation guidance
• Support for GitHub, PetStore, and custom APIs

When to use: When you need to discover API endpoints, validate requests, or work with OpenAPI-documented APIs.

cd builtins-openapi-discovery && go run main.go

Built-ins Web Search Parallel

Focus: Production web search with explicit API key management

Features:

• Parallel searches across multiple engines
• Explicit API key injection (no environment variables)
• Performance comparison between engines
• Multi-tenant and A/B testing patterns
• Error handling and fallback strategies

When to use: When you need production-grade web search with secure API key management.

cd builtins-web-search-parallel && go run main.go

Built-ins System Tools

Focus: System interaction and management

Features:

• Command execution with safety controls and timeouts
• Environment variable access with pattern matching
• Comprehensive system information gathering
• Process listing and filtering
• Cross-platform compatibility

When to use: When you need to interact with the operating system, run commands, or gather system information.

cd builtins-system-tools && go run main.go

Built-ins Data Tools

Focus: Structured data processing

Features:

• JSON processing with JSONPath queries
• CSV parsing, filtering, and statistics
• XML parsing with XPath and JSON conversion
• Common data transformations (filter, map, reduce, sort, group)
• Type conversions and aggregations

When to use: When you need to process, transform, or analyze structured data in various formats.

cd builtins-data-tools && go run main.go

Built-ins DateTime Tools

Focus: Comprehensive date/time operations

Features:

• Current time in various formats and timezones
• Date parsing with auto-detection and relative dates
• Date arithmetic and business day calculations
• Formatting with localization support
• Timezone conversions with DST handling
• Date comparisons and sorting

When to use: When you need to work with dates, times, and timezones in your applications.

cd builtins-datetime-tools && go run main.go

Built-ins Feed Tools

Focus: Feed processing and syndication

Features:

• Fetching RSS, Atom, and JSON Feed formats
• Auto-discovering feeds from websites
• Filtering feed items by keywords, dates, and categories
• Aggregating multiple feeds into one
• Converting between feed formats
• Extracting specific data for analysis

When to use: When you need to work with RSS/Atom feeds, aggregate news sources, or build feed-based applications.

cd builtins-feed-tools && go run main.go

Structured Output Examples

Structured Schema

Schema generation and validation.

Features:

• Schema generation from Go structs
• Validation patterns
• Custom rules

cd structured-schema && go run main.go

Structured Coercion

Type coercion and data conversion.

Features:

• Type conversions
• Flexible validation
• Data normalization

cd structured-coercion && go run main.go

Structured Output

LLM output parsing with recovery and validation.

Features:

• JSON parsing with recovery from markdown
• Schema validation with detailed errors
• Format conversion (JSON/YAML/XML)
• Bridge integration for go-llmspell

cd structured-output && go run main.go

Schema Management Examples

Schema Generator

Advanced schema generation from Go structs.

Features:

• Reflection-based schema generation
• Tag-based schema generation
• Custom type handlers
• Nested struct support
• Schema versioning

cd schema-generator && go run main.go

Schema Repository

Schema storage and versioning.

Features:

• In-memory repository with thread safety
• File-based persistent storage
• Schema versioning and migration
• Import/export functionality
• Schema discovery and search

cd schema-repository && go run main.go

Bridge Integration Examples

Types Bridge

Type conversion and bridging for scripting engines.

Features:

• Type registry with bidirectional conversions
• Schema to map[string]interface{} conversion
• Custom type converters
• Multi-hop conversion support
• Conversion caching

cd types-bridge && go run main.go

Tools Script Dynamic

Dynamic tool registration for scripting engines.

Features:

• Runtime tool registration
• Script-based tool factories
• Tool persistence and loading
• Multi-tenant tool isolation
• Tool versioning

cd tools-script-dynamic && go run main.go

Error Handling Examples

Provider Metadata

Provider metadata and dynamic registry system.

Features:

• Provider capability discovery
• Model information with pricing
• Dynamic provider registration
• Configuration export/import
• Best model selection by requirements

cd provider-metadata && go run main.go

Errors Serialization

Enhanced error handling with serialization and recovery.

Features:

• JSON serializable errors
• Rich error context with stack traces
• Recovery strategies (exponential backoff, circuit breaker)
• Error aggregation for batch operations
• Error builder pattern

cd errors-serialization && go run main.go

Utility Examples

Utils Model Info

Model discovery and capability assessment.

Features:

• Automatic model discovery
• Capability filtering
• Provider comparison
• Caching

export OPENAI_API_KEY="your-key"
cd utils-modelinfo && go run main.go

Utils Profiling

Performance profiling and optimization.

Features:

• CPU profiling
• Memory analysis
• Benchmarks

cd utils-profiling && go run main.go

Environment Variables

Most examples use these environment variables:

# LLM Provider API Keys
export OPENAI_API_KEY="your-openai-api-key"
export ANTHROPIC_API_KEY="your-anthropic-api-key"
export GEMINI_API_KEY="your-gemini-api-key"
export OPENROUTER_API_KEY="your-openrouter-api-key"

# Optional Configuration
export OPENAI_ORGANIZATION="your-org-id"
export OPENAI_BASE_URL="https://api.openai.com"  # Custom endpoint

Building Examples

You can build all examples at once using the provided Makefile:

# Build all examples
make build-examples

# Build a specific example
make build-example EXAMPLE=agent-simple-llm

# Clean all built examples
make clean-examples

Running Tests

Each example includes tests:

cd <example-directory>
go test ./...

Contributing

When adding new examples:

1. Create a new directory under cmd/examples/
2. Follow the naming convention (agent-, workflow-, provider-*, etc.)
3. Include main.go and README.md
4. Add ABOUTME comments to source files
5. Update this README.md