# Agents

Create and configure AI agents in AgentKit

URL: https://agentkit.tech/docs/agents.mdx

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

```go
// 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:

```go
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:

```go
// 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:

```go
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:

```go
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:

```go
// 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:

```go
// 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:

```go
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:

```go
// ✅ 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:

```go
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:

```go
// 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:

```go
// 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:

```go
// 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

```go
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](/models) - Configure language models
* [Tools](/tools) - Add function calling capabilities
* [Session Management](/sessions) - Handle conversation state