Candil.Agent (Candil v3.0.0)

Copy Markdown View Source

A minimal ReAct-style agent that uses tools.

ReAct (Reason + Act) alternates between:

  1. Reasoning — the model decides what to do next.
  2. Acting — invoke a tool if needed.
  3. Observing — feed the tool's result back as a new message.

The loop continues until either:

  • The model emits a final answer (no tool calls).
  • max_steps is reached (default 8).

Conversation history

The agent maintains its own conversation; pass an optional Candil.Conversation to start with a system prompt.

Stop words

If the model's response contains one of the configured stop words (default "FINAL_ANSWER"), the loop terminates.

Example

defmodule MyApp.WeatherAgent do
  use Candil.Agent,
    name: "weather",
    goal: "Answer weather questions",
    tools: [Candil.MyTools.get_weather],
    max_steps: 6
end

MyApp.WeatherAgent.run("What's the weather in Madrid?")

Summary

Types

result()
step()
trace()

Functions

run(agent, input, opts \\ [])

Run the agent synchronously. Returns {:ok, final_answer, trace} on success or {:error, term()} on failure.

Types

result()

@type result() :: {:ok, String.t(), trace()} | {:error, term()}

step()

@type step() :: %{kind: :thought | :action | :observation | :final, content: term()}

trace()

@type trace() :: [step()]

Functions

run(agent, input, opts \\ [])

@spec run(module() | map(), String.t() | nil, keyword()) :: result()

Run the agent synchronously. Returns {:ok, final_answer, trace} on success or {:error, term()} on failure.

Options

  • :backend — Candil.Backend module to use.
  • :model — model id (string or atom).
  • :max_steps — max loop iterations (default 8).
  • :cancel_ref — cancellation ref from Candil.Cancellation.new_ref/0.
  • :conversation — pre-seeded conversation.