Agent

An Agent is an autonomous AI entity that can use tools, maintain conversation context, and execute tasks independently.

Overview

import "github.com/rexleimo/agno-Go/pkg/agno/agent"

agent, err := agent.New(agent.Config{
    Name:         "My Agent",
    Model:        model,
    Toolkits:     []toolkit.Toolkit{calculator.New()},
    Instructions: "You are a helpful assistant",
    MaxLoops:     10,
})

output, err := agent.Run(context.Background(), "What is 2+2?")

Configuration

Config Structure

type Config struct {
    Name         string            // Agent name
    Model        models.Model      // LLM model
    Toolkits     []toolkit.Toolkit // Available tools
    Memory       memory.Memory     // Conversation memory
    Instructions string            // System instructions
    MaxLoops     int               // Max tool call loops (default: 10)
    PreHooks     []hooks.Hook      // Pre-execution hooks
    PostHooks    []hooks.Hook      // Post-execution hooks
}

Parameters

• Name (required): Human-readable agent identifier
• Model (required): LLM model instance (OpenAI, Claude, etc.)
• Toolkits (optional): List of available tools
• Memory (optional): Defaults to in-memory storage with 100 message limit
• Instructions (optional): System prompt/persona
• MaxLoops (optional): Prevent infinite tool call loops (default: 10)
• PreHooks (optional): Validation hooks before execution
• PostHooks (optional): Validation hooks after execution

Basic Usage

Simple Agent

package main

import (
    "context"
    "fmt"
    "github.com/rexleimo/agno-Go/pkg/agno/agent"
    "github.com/rexleimo/agno-Go/pkg/agno/models/openai"
)

func main() {
    model, _ := openai.New("gpt-4o-mini", openai.Config{
        APIKey: os.Getenv("OPENAI_API_KEY"),
    })

    ag, _ := agent.New(agent.Config{
        Name:         "Assistant",
        Model:        model,
        Instructions: "You are a helpful assistant",
    })

    output, _ := ag.Run(context.Background(), "Hello!")
    fmt.Println(output.Content)
}

Agent with Tools

import (
    "github.com/rexleimo/agno-Go/pkg/agno/tools/calculator"
    "github.com/rexleimo/agno-Go/pkg/agno/tools/http"
)

ag, _ := agent.New(agent.Config{
    Name:  "Smart Assistant",
    Model: model,
    Toolkits: []toolkit.Toolkit{
        calculator.New(),
        http.New(),
    },
    Instructions: "You can do math and make HTTP requests",
})

output, _ := ag.Run(ctx, "Calculate 15 * 23 and fetch https://api.github.com")

Advanced Features

Custom Memory

import "github.com/rexleimo/agno-Go/pkg/agno/memory"

// Create memory with custom limit
mem := memory.NewInMemory(50) // Keep last 50 messages

ag, _ := agent.New(agent.Config{
    Memory: mem,
    // ... other config
})

Hooks & Guardrails

Validate inputs and outputs with hooks:

import "github.com/rexleimo/agno-Go/pkg/agno/guardrails"

// Built-in prompt injection guard
promptGuard := guardrails.NewPromptInjectionGuardrail()

// Custom validation hook
customHook := func(ctx context.Context, input *hooks.HookInput) error {
    if len(input.Input) > 1000 {
        return fmt.Errorf("input too long")
    }
    return nil
}

ag, _ := agent.New(agent.Config{
    PreHooks:  []hooks.Hook{customHook, promptGuard},
    PostHooks: []hooks.Hook{outputValidator},
    // ... other config
})

Context and Timeouts

import "time"

ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

output, err := ag.Run(ctx, "Complex task...")
if err != nil {
    if ctx.Err() == context.DeadlineExceeded {
        fmt.Println("Timeout!")
    }
}

Run Output

The Run method returns *RunOutput:

type RunOutput struct {
    Content  string                 // Agent's response
    Messages []types.Message        // Full message history
    Metadata map[string]interface{} // Additional data
}

Example:

output, err := ag.Run(ctx, "Tell me a joke")
if err != nil {
    log.Fatal(err)
}

fmt.Println("Response:", output.Content)
fmt.Println("Messages:", len(output.Messages))
fmt.Println("Metadata:", output.Metadata)

Memory Management

Clear Memory

// Clear all conversation history
ag.ClearMemory()

Access Memory

// Get current messages
messages := ag.GetMemory().GetMessages()
fmt.Println("History:", len(messages))

Error Handling

output, err := ag.Run(ctx, input)
if err != nil {
    switch {
    case errors.Is(err, types.ErrInvalidInput):
        // Handle invalid input
    case errors.Is(err, types.ErrRateLimit):
        // Handle rate limit
    case errors.Is(err, context.DeadlineExceeded):
        // Handle timeout
    default:
        // Handle other errors
    }
}

Best Practices

1. Always Use Context

ctx := context.Background()
output, err := ag.Run(ctx, input)

2. Set Appropriate MaxLoops

// For simple tasks
MaxLoops: 5

// For complex reasoning
MaxLoops: 15

3. Provide Clear Instructions

Instructions: `You are a customer support agent.
- Be polite and professional
- Use tools to look up information
- If unsure, ask for clarification`

4. Use Type-Safe Tool Configurations

calc := calculator.New()
httpClient := http.New(http.Config{
    Timeout: 10 * time.Second,
})

ag, _ := agent.New(agent.Config{
    Toolkits: []toolkit.Toolkit{calc, httpClient},
})

Performance Considerations

• Agent Creation: ~180ns average
• Memory Footprint: ~1.2KB per agent
• Concurrent Agents: Fully thread-safe, use goroutines freely

// Concurrent agents
for i := 0; i < 100; i++ {
    go func(id int) {
        ag, _ := agent.New(config)
        output, _ := ag.Run(ctx, input)
        fmt.Printf("Agent %d: %s\n", id, output.Content)
    }(i)
}

Examples

See working examples:

• Simple Agent
• Claude Agent
• Ollama Agent
• Agent with Guardrails

API Reference

For complete API documentation, see Agent API Reference.

Next Steps

• Team - Multi-agent collaboration
• Workflow - Step-based orchestration
• Tools - Built-in and custom tools
• Models - LLM provider configuration