PhoenixAI.Agent (PhoenixAI v0.1.0)

Copy Markdown View Source

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})

Summary

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

get_messages(server)

Returns the accumulated conversation messages.

prompt(server, text, opts \\ [])

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

reset(server)

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

start_link(opts)

Starts an Agent GenServer. See module docs for options.

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

get_messages(server)

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

Returns the accumulated conversation messages.

prompt(server, text, opts \\ [])

@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(server)

@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(opts)

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

Starts an Agent GenServer. See module docs for options.