Agents

An Agent is the core component in AgentKit that handles AI conversations and task execution. Agents combine a language model with tools and instructions to create powerful AI assistants.

Quick Start

// Create an agent with a model and system prompt
model := model.Model("gpt-4o").
    SetAPIKey(os.Getenv("OPENAI_API_KEY"))

agent := agent.New().
    SetModel(model).
    SetSystemPrompt("You are a helpful assistant.")

// Create session and run the agent
session := session.New(agent)
response, err := session.Run(ctx, []agent.ChatMessage{agent.NewUserMessage("Hello!")}, nil)

Agent Configuration

System Prompt

Defines your agent's behavior and personality:

agent := agent.New().
    SetModel(model).
    SetSystemPrompt("You are a code reviewer. Analyze code for bugs and suggest improvements.")

Adding Tools

Give your agent capabilities beyond text generation:

// Create a calculator tool
calcTool := tool.NewFunctionTool(
    "calculator",
    "Perform basic math operations",
    calculatorHandler,
)

agent := agent.New().
    SetModel(model).
    SetSystemPrompt("You are a math tutor. Use the calculator when needed.").
    AddTool(calcTool)

Agent Types

Basic Agent

Simple conversational agent:

model := model.Model("gpt-4o").
    SetAPIKey(os.Getenv("OPENAI_API_KEY"))

agent := agent.New().
    SetModel(model).
    SetSystemPrompt("You are a helpful assistant.")

Specialized Agent

Focused on specific tasks:

model := model.Model("gpt-4o").
    SetAPIKey(os.Getenv("OPENAI_API_KEY")).
    SetTemperature(0.1) // Lower temperature for consistency

agent := agent.New().
    SetModel(model).
    SetSystemPrompt(`You are a code reviewer. Analyze code for:
    • Security vulnerabilities
    • Performance issues  
    • Best practices
    • Potential bugs
    
    Provide specific, actionable feedback.`)

Running Agents

Single Interaction

For one-off conversations:

// Create a new session for each interaction
session := session.New(agent)
response, err := session.Run(ctx, []agent.ChatMessage{agent.NewUserMessage("What is Go programming language?")}, nil)
if err != nil {
    log.Fatal(err)
}
fmt.Println(response.FinalOutput)

Multi-turn Conversations

For ongoing conversations with memory:

// Create session once, reuse for multiple messages
session := session.New(agent)

// First message
response1, _ := session.Run(ctx, []agent.ChatMessage{agent.NewUserMessage("Hi, my name is Alice")}, nil)
fmt.Println("Agent:", response1.FinalOutput)

// Second message - agent remembers the name
response2, _ := session.Run(ctx, []agent.ChatMessage{agent.NewUserMessage("What's my name?")}, nil)
fmt.Println("Agent:", response2.FinalOutput) // "Your name is Alice"

Streaming Responses

For real-time response streaming:

stream, err := session.RunStreamed(ctx, []agent.ChatMessage{agent.NewUserMessage("Tell me a story")}, nil)
if err != nil {
    log.Fatal(err)
}

for event, err := range stream.StreamEvents() {
    if err != nil {
        log.Fatal(err)
    }
    if event.IsTextDelta() {
        fmt.Print(event.GetContent())
    }
}

Best Practices

Writing System Prompts

Be specific and clear about the agent's role:

// ✅ Good - Specific and actionable
SetSystemPrompt(`You are a Python tutor. 
• Explain concepts with code examples
• Test code before sharing
• Ask clarifying questions when needed`)

// ❌ Avoid - Too vague
SetSystemPrompt("Help with programming")

Setting Boundaries

Define what the agent should and shouldn't do:

SetSystemPrompt(`You are a customer support agent.
DO: Answer product questions, help with accounts
DON'T: Provide medical advice or share customer data`)

Temperature Guidelines

Control response randomness:

// Technical tasks - consistent output
model.SetTemperature(0.1)

// General conversation - balanced
model.SetTemperature(0.6)

// Creative tasks - more varied
model.SetTemperature(0.8)

Advanced Patterns

Agent Handoffs

Transfer conversations between specialized agents:

// Create specialized agents
codeReviewer := agent.New().
    SetModel(model).
    SetSystemPrompt("You review code for bugs and improvements.")

tester := agent.New().
    SetModel(model).
    SetSystemPrompt("You generate unit tests for code.")

// Create session and hand off conversation
session := session.New(codeReviewer)
review, _ := session.Run(ctx, []agent.ChatMessage{agent.NewUserMessage("Review this function: "+code)}, nil)

// Hand off to tester (switch agent in session)
session.SetAgent(tester)
tests, _ := session.Run(ctx, []agent.ChatMessage{agent.NewUserMessage("Generate tests based on the review")}, nil)

Tool-Enabled Agents

Agents with external capabilities:

// Create a weather tool
weatherTool := tool.NewFunctionTool(
    "get_weather",
    "Get current weather for a location",
    weatherHandler,
)

// Add to agent
agent := agent.New().
    SetModel(model).
    SetSystemPrompt("You help with weather information.").
    AddTool(weatherTool)

Error Handling

response, err := session.Run(ctx, []agent.ChatMessage{agent.NewUserMessage("user message")}, nil)
if err != nil {
    // Handle different error types
    switch {
    case errors.Is(err, agent.ErrRateLimited):
        // Handle rate limiting
    case errors.Is(err, agent.ErrInvalidInput):
        // Handle invalid input
    default:
        log.Printf("Agent error: %v", err)
    }
}

Next Steps

Models - Configure language models
Tools - Add function calling capabilities
Session Management - Handle conversation state

On this page