# pkg/agent

> El bucle principal que ejecuta un agente LLM con guardrails.

## Responsabilidad

Coordinar el ciclo iterativo entre el LLM y la ejecución de tools:

```
while iteration < MaxIterations:
    response = llm.Generate(messages, tools)
    if no tool calls: return response
    for tool_call in response.ToolCalls:
        if needs_approval: ask_user()
        result = execute(tool_call)
        append tool result to messages
```

## API pública

```go
type Loop interface {
    Run(ctx context.Context, input string) (Response, error)
    RunStream(ctx context.Context, input string) iter.Seq2[Chunk, error]
}

type Config struct {
    LLM          llm.LLMClient
    Persona      persona.Persona
    Tools        tools.Registry
    Sandbox      Sandbox
    MaxIters     int
    Approver     Approver        // nil = auto-approve all
    OnIteration  func(Iteration) // observability hook
}

type Response struct {
    Content     string
    ToolCalls   []tools.Call
    Iterations  int
    Duration    time.Duration
    TokenUsage  llm.TokenUsage
}
```

## Garantías

- **Termination**: Siempre termina (max iterations, error, o respuesta final)
- **Idempotencia**: Re-ejecutar con el mismo input produce el mismo output (dado el mismo LLM)
- **Observabilidad**: Cada iteración emite un span OpenTelemetry
- **Approval**: Tool destructivos (`Ask` permission) requieren confirmación

## Ver también

- [pkg/tools](../tools/README.md) — Tool execution
- [pkg/llm](../llm/README.md) — LLMClient interface
- [pkg/persona](../persona/README.md) — Persona assembly