Struct RuntimeAgentBuilder 

pub struct RuntimeAgentBuilder { /* private fields */ }

Builder for RuntimeAgent with fluent API

Use new() to start building, then chain methods like with_agent(), model(), temperature(), etc. Call build() to get the final runtime agent.

Implementations

impl RuntimeAgentBuilder

pub fn new() -> Self

Start building a new runtime agent from scratch

pub async fn from_overlay( layer: AgentConfigOverlay, registry: &CapabilityRegistry, ctx: &SystemPromptContext, ) -> Self

Build from a pre-merged AgentConfigOverlay.

This is the preferred way to build a RuntimeAgent. The caller merges Harness/Agent/Session into a single AgentConfigOverlay (via AgentConfigOverlay::fold), then this method resolves capabilities and assembles the final config.

Example

let layer = AgentConfigOverlay::fold([
    AgentConfigOverlay::from(&harness),
    AgentConfigOverlay::from(&agent),
    AgentConfigOverlay::from(&session),
]);
let runtime_agent = RuntimeAgentBuilder::from_overlay(layer, &registry, &ctx)
    .await
    .model("gpt-5.2")
    .build();

pub async fn with_harness( self, harness: &Harness, registry: &CapabilityRegistry, ctx: &SystemPromptContext, ) -> Self

Apply a Harness’s configuration to this builder.

Sets the system prompt from the harness and applies harness capabilities. Calls system_prompt_contribution() on each capability for dynamic content. Call this BEFORE with_agent() to establish the base prompt layer.

pub async fn with_agent( self, agent: &Agent, registry: &CapabilityRegistry, ctx: &SystemPromptContext, ) -> Self

Apply an Agent’s configuration to this builder.

Prepends the agent’s system prompt and capabilities on top of the existing prompt (typically from a harness). Call after with_harness().

Example

let ctx = SystemPromptContext::without_file_store(session_id);
let runtime_agent = RuntimeAgentBuilder::new()
    .with_harness(&harness, &registry, &ctx).await
    .with_agent(&agent, &registry, &ctx).await
    .with_capabilities(&session_caps, &registry, &ctx).await
    .model("gpt-4o")
    .build();

pub async fn with_capabilities( self, capability_ids: &[String], registry: &CapabilityRegistry, ctx: &SystemPromptContext, ) -> Self

Apply capabilities to this builder.

Resolves dependencies, then collects contributions from capabilities:

• Dependencies are automatically included (topologically sorted)
• system_prompt_contribution(ctx) called on each (may read from filesystem)
• System prompt additions are prepended to the current system prompt
• Tool definitions are added to the tools list

Arguments

• capability_ids - Ordered list of capability IDs to apply
• registry - The capability registry containing implementations
• ctx - Session context for dynamic prompt resolution

pub async fn with_capability_configs( self, capability_configs: &[AgentCapabilityConfig], registry: &CapabilityRegistry, ctx: &SystemPromptContext, ) -> Self

Apply capability configs to this builder, preserving per-capability configuration.

pub fn system_prompt(self, prompt: impl Into<String>) -> Self

Set the system prompt

pub fn prepend_system_prompt(self, prefix: impl Into<String>) -> Self

Prepend text to the system prompt

pub fn with_locale(self, locale: Option<&str>) -> Self

Prepend locale instructions for session-aware localization.

pub fn model(self, model: impl Into<String>) -> Self

Set the model

pub fn tool(self, tool: ToolDefinition) -> Self

Add a tool

pub fn tools(self, tools: impl IntoIterator<Item = ToolDefinition>) -> Self

Add multiple tools

pub fn max_iterations(self, max: usize) -> Self

Set maximum iterations

pub fn network_access(self, network_access: Option<NetworkAccessList>) -> Self

Set the merged network access list.

pub fn temperature(self, temp: f32) -> Self

Set temperature

pub fn max_tokens(self, tokens: u32) -> Self

Set max tokens

pub fn tool_search(self, config: ToolSearchConfig) -> Self

Set tool_search configuration

pub fn prompt_cache(self, config: PromptCacheConfig) -> Self

Set prompt caching configuration

pub fn build(self) -> RuntimeAgent

Build the runtime agent.

Validates that tool_search is only enabled for models that support it (currently GPT-5.4 and newer). Clears tool_search for unsupported models to prevent 400 errors from the OpenAI API.

tool_search is capability-driven: it is only set when the openai_tool_search capability is explicitly added to the agent or harness. This method does NOT auto-enable it.

Trait Implementations

impl Default for RuntimeAgentBuilder

fn default() -> Self

Returns the “default value” for a type.