# Agent

`agent.Agent` is the interface implemented by autonomous agents in the Go AI
SDK. It lives in `github.com/digitallysavvy/go-ai/pkg/agent`, not `pkg/ai`.
The SDK's concrete implementation is [`ToolLoopAgent`](https://goaisdk.com/docs/reference/ai/tool-loop-agent.md),
created with `agent.NewToolLoopAgent`.

## Signature

```go
type Agent interface {
    // Version returns the agent interface specification version.
    Version() string

    // ID returns the optional agent identifier.
    ID() string

    // Tools returns the tools that the agent can use.
    Tools() []types.Tool

    // Generate runs the agent with per-call options and returns the core
    // GenerateText result.
    Generate(ctx context.Context, opts AgentGenerateOptions) (*ai.GenerateTextResult, error)

    // Stream streams the agent with per-call options.
    Stream(ctx context.Context, opts AgentStreamOptions) (*ai.StreamTextResult, error)

    // Execute runs the agent with the given prompt and returns the final result
    Execute(ctx context.Context, prompt string) (*AgentResult, error)

    // ExecuteWithMessages runs the agent with a message history
    ExecuteWithMessages(ctx context.Context, messages []types.Message) (*AgentResult, error)
}
```

## Return Value

### AgentResult

| Field | Type | Description |
|-------|------|-------------|
| Text | string | Final text output |
| Output | interface{} | Parsed/structured final output when an output strategy is configured |
| Steps | []types.StepResult | All steps taken by the agent |
| ToolResults | []types.ToolResult | All tool results from agent execution |
| Delegations | []agent.SubagentDelegation | Subagent delegations during execution |
| FinishReason | types.FinishReason | Final finish reason |
| StopReason | string | Reason string from the `StopCondition` that stopped the loop; empty if the agent ended naturally |
| Usage | types.Usage | Total usage across all steps |
| Warnings | []types.Warning | Warnings from any step |

## Examples

### Basic Agent

```go
package main

import (
    "context"
    "fmt"
    "log"

    "github.com/digitallysavvy/go-ai/pkg/agent"
    "github.com/digitallysavvy/go-ai/pkg/provider/types"
    "github.com/digitallysavvy/go-ai/pkg/providers/openai"
)

func main() {
    p := openai.New(openai.Config{
        APIKey: "your-api-key",
    })
    model, _ := p.LanguageModel("gpt-4")

    searchTool := types.Tool{
        Name:        "search",
        Description: "Search the web for information",
        Parameters: map[string]interface{}{
            "type": "object",
            "properties": map[string]interface{}{
                "query": map[string]interface{}{
                    "type":        "string",
                    "description": "Search query",
                },
            },
            "required": []string{"query"},
        },
        Execute: func(ctx context.Context, input map[string]interface{}, opts types.ToolExecutionOptions) (interface{}, error) {
            query := input["query"].(string)
            return fmt.Sprintf("Search results for: %s", query), nil
        },
    }

    var a agent.Agent = agent.NewToolLoopAgent(agent.AgentConfig{
        Model: model,
        Tools: []types.Tool{searchTool},
    })

    result, err := a.Execute(context.Background(), "Find the current weather in Tokyo")
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Result: %s\n", result.Text)
    fmt.Printf("Steps taken: %d\n", len(result.Steps))
}
```

## See Also

- [ToolLoopAgent](https://goaisdk.com/docs/reference/ai/tool-loop-agent.md) - The SDK's concrete `Agent` implementation
- [Tool](https://goaisdk.com/docs/reference/ai/tool.md) - Tool definition
- [Agents Guide](https://goaisdk.com/docs/agents/overview.md)