claude/agent

Types

AgentError

Errors that can occur during the agent loop.

pub type AgentError {
  ApiCallFailed(error.ApiError)
  MaxIterationsReached(
    messages: List(message.MessageParam),
    iterations: Int,
  )
}

Constructors

```
ApiCallFailed(error.ApiError)
```

MaxIterationsReached(
  messages: List(message.MessageParam),
  iterations: Int,
)

AgentEvent

</>

Events emitted during the agent loop execution.

These events allow callers to observe the progress of an agent run, whether via a callback function or via BEAM message passing.

pub type AgentEvent {
  Started(session_id: String)
  AssistantResponse(message: message.Message)
  ToolExecuting(tool_name: String, tool_id: String)
  ToolCompleted(tool_id: String, result: Result(String, String))
  Done(result: AgentResult)
  Failed(error: AgentError)
}

Constructors

```
Started(session_id: String)
```
Agent started processing
```
AssistantResponse(message: message.Message)
```
Assistant sent a response (may include tool calls)

ToolExecuting(tool_name: String, tool_id: String)

Tool execution started

ToolCompleted(tool_id: String, result: Result(String, String))

Tool execution completed

```
Done(result: AgentResult)
```
Agent finished successfully
```
Failed(error: AgentError)
```
Agent encountered an error

AgentResult

</>

The result of a successful agent loop run.

pub type AgentResult {
  AgentResult(
    messages: List(message.MessageParam),
    final_message: message.Message,
    iterations: Int,
    total_input_tokens: Int,
    total_output_tokens: Int,
  )
}

Constructors

AgentResult(
  messages: List(message.MessageParam),
  final_message: message.Message,
  iterations: Int,
  total_input_tokens: Int,
  total_output_tokens: Int,
)

Values

build_tool_results_message

</>

pub fn build_tool_results_message(
  results: List(#(String, Result(String, String))),
) -> message.MessageParam

Build a user message containing tool results.

Each result is a tuple of (tool_use_id, Ok(content) | Error(error_message)).

event_loop

</>

pub fn event_loop(
  config: config.AgentConfig,
  messages: List(message.MessageParam),
  iteration: Int,
  total_input: Int,
  total_output: Int,
  on_event: fn(AgentEvent) -> Nil,
) -> Result(AgentResult, AgentError)

Recursive agent loop that emits events at each step.

This is the single canonical implementation of the agent loop. Both agent.run (with a no-op callback) and actor.run_with_events delegate to this function.

The on_event callback is called at each notable step. Pass fn(_) { Nil } for a silent loop, or a real callback for event-driven usage.

extract_tool_calls

</>

pub fn extract_tool_calls(
  content: List(content.ContentBlock),
) -> List(content.ContentBlock)

Extract tool-use blocks from a list of content blocks.

Starts with the given prompt, sends messages to the API, and automatically handles tool-use responses by executing tools and feeding results back. Continues until the model stops with a non-tool-use reason or max_iterations is reached.

run_with_messages

</>

pub fn run_with_messages(
  config: config.AgentConfig,
  messages_list: List(message.MessageParam),
) -> Result(AgentResult, AgentError)

Run the agent loop with an existing message history.

Like run but allows passing in an existing conversation history.