# `PhoenixAI.Agent`
[🔗](https://github.com/franciscpd/phoenix-ai/blob/main/lib/phoenix_ai/agent.ex#L1)

Stateful GenServer that owns one conversation and runs the completion-tool-call loop.

## Modes

- **`manage_history: true`** (default) — Agent accumulates messages between `prompt/2`
  calls. The conversation grows automatically, like Laravel/AI's Agent.
- **`manage_history: false`** — Agent is a stateless runner. Consumer passes `messages:`
  in each `prompt/3` call and manages history externally.

## Usage

    {:ok, pid} = PhoenixAI.Agent.start_link(
      provider: :openai,
      model: "gpt-4o",
      system: "You are a helpful assistant.",
      tools: [MyApp.Weather],
      api_key: "sk-..."
    )

    {:ok, response} = PhoenixAI.Agent.prompt(pid, "What's the weather in Lisbon?")
    response.content
    #=> "The weather in Lisbon is sunny, 22°C!"

    {:ok, response} = PhoenixAI.Agent.prompt(pid, "And in Porto?")

## Supervision

Start under a DynamicSupervisor:

    DynamicSupervisor.start_child(MyApp.AgentSupervisor, {PhoenixAI.Agent, opts})

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `get_messages`

```elixir
@spec get_messages(GenServer.server()) :: [PhoenixAI.Message.t()]
```

Returns the accumulated conversation messages.

# `prompt`

```elixir
@spec prompt(GenServer.server(), String.t(), keyword()) ::
  {:ok, PhoenixAI.Response.t()} | {:error, term()}
```

Sends a prompt to the agent and waits for the response.

Blocks until the provider (and any tool calls) complete.
Default timeout: 60 seconds.

## Options (prompt/3)

- `:messages` — override conversation history (for `manage_history: false`)
- `:timeout` — override call timeout in milliseconds

# `reset`

```elixir
@spec reset(GenServer.server()) :: :ok | {:error, :agent_busy}
```

Clears conversation history, keeps configuration. Returns `{:error, :agent_busy}` if a prompt is in flight.

# `start_link`

```elixir
@spec start_link(keyword()) :: GenServer.on_start()
```

Starts an Agent GenServer. See module docs for options.

---

*Consult [api-reference.md](api-reference.md) for complete listing*