Nous.AgentRunner (nous v0.15.8)

View Source

Executes agent runs with tool calling loop.

The AgentRunner is responsible for:

  • Building messages with system prompts and instructions
  • Calling the model via the provider
  • Detecting and executing tool calls
  • Looping until needs_response is false
  • Extracting and validating output
  • Executing callbacks and sending process notifications

Context-Based Execution

The runner uses a Context struct to manage all state during execution:

ctx = Context.new(
  deps: %{database: MyDB},
  callbacks: %{on_llm_new_delta: fn _, d -> IO.write(d) end},
  notify_pid: self()
)

Behaviour Integration

Different agent types can customize behavior by implementing Nous.Agent.Behaviour and setting behaviour_module on the agent.

Summary

Functions

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

Run agent to completion.

run_stream(agent, prompt, opts \\ [])

Run agent with streaming.

run_with_context(agent, ctx, opts \\ [])

Run agent with an existing context.

Functions

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

@spec run(Nous.Agent.t(), String.t(), keyword()) :: {:ok, map()} | {:error, term()}

Run agent to completion.

Options

  • :deps - Dependencies for tools
  • :message_history - Previous messages
  • :usage_limits - Usage limits (not implemented yet)
  • :model_settings - Override model settings
  • :max_iterations - Maximum iterations (default: 10)
  • :cancellation_check - Function to check if execution should be cancelled. Under stream: true, also invoked between every streamed chunk; on cancellation the consumer aborts cleanly without partial tool execution.
  • :callbacks - Map of callback functions
  • :notify_pid - PID to receive event messages
  • :context - Existing context to continue from
  • :output_type - Override the agent's output_type for this run
  • :structured_output - Override the agent's structured_output options for this run
  • :stream - When true, the LLM call streams chunks while still running the tool-call loop (default: false). Fires :on_llm_new_delta per text chunk and :on_llm_new_thinking_delta per reasoning chunk. :on_llm_new_message still fires once per iteration with the assembled message, identical in shape to the non-streaming path. Works across all providers (OpenAI-compatible, Anthropic, Gemini) and is compatible with output_type (the synthetic-tool path is honored under streaming).

run_stream(agent, prompt, opts \\ [])

@spec run_stream(Nous.Agent.t(), String.t(), keyword()) ::
  {:ok, Enumerable.t()} | {:error, term()}

Run agent with streaming.

Returns a stream that yields events as they occur.

Events

  • {:text_delta, text} - Incremental text update
  • {:thinking_delta, text} - Thinking content (reasoning models)
  • {:tool_call, call} - Tool is being called
  • {:tool_result, result} - Tool execution completed
  • {:finish, reason} - Stream finished
  • {:complete, result} - Final result

run_with_context(agent, ctx, opts \\ [])

@spec run_with_context(Nous.Agent.t(), Nous.Agent.Context.t(), keyword()) ::
  {:ok, map()} | {:error, term()}

Run agent with an existing context.

Useful for continuing from a previous run or with pre-built context.