Struct AxAgent 

pub struct AxAgent { /* private fields */ }

Implementations

impl AxAgent

pub fn set_signature(&mut self, spec: &str) -> AxResult<&mut Self>

pub fn get_instruction(&self) -> String

pub fn set_instruction(&mut self, instruction: &str) -> AxResult<&mut Self>

pub fn add_actor_instruction(&mut self, addendum: &str) -> AxResult<&mut Self>

pub fn forward<C: AxAIClient>( &mut self, client: &mut C, input: Value, ) -> AxResult<Value>

pub fn forward_with_options<C: AxAIClient>( &mut self, client: &mut C, input: Value, options: Value, ) -> AxResult<Value>

pub fn set_citations_observer<F>(&mut self, observer: F) -> &mut Self

where F: FnMut(Value) + 'static,

pub fn set_playbook_observer<F>(&mut self, observer: F) -> &mut Self

where F: FnMut(Value) + 'static,

pub fn get_usage(&self) -> Value

pub fn get_runtime_contract(&self) -> Value

pub fn get_policy(&self) -> Value

pub fn get_policy_registry(&self) -> Value

pub fn get_callable_inventory(&self) -> Value

pub fn get_discovery_catalog(&self) -> Value

pub fn discover(&mut self, request: Value) -> AxResult<Value>

pub fn recall(&mut self, request: Value) -> AxResult<Value>

pub fn used(&mut self, id: &str, reason: &str, stage: &str) -> AxResult<Value>

pub fn invoke_callable( &mut self, qualified_name: &str, args: Value, options: Value, ) -> AxResult<Value>

pub fn export_runtime_state(&mut self) -> AxResult<Value>

pub fn restore_runtime_state(&mut self, snapshot: Value) -> AxResult<Value>

pub fn get_optimizer_metadata(&self) -> AxResult<Value>

pub fn get_optimizable_components(&self) -> AxResult<Vec<Value>>

pub fn apply_optimized_components( &mut self, component_map: &Value, ) -> AxResult<()>

pub fn replay_trace(&mut self, trace: Value, fixtures: Value) -> AxResult<Value>

pub fn evaluate_optimization_task<C: AxAIClient>( &mut self, client: &mut C, task: Value, options: Value, ) -> AxResult<Value>

pub fn execute_actor_step( &mut self, runtime: &mut dyn AxCodeRuntime, code: &str, input: Value, options: Value, ) -> AxResult<RuntimeEnvelope>

Examples found in repository

examples/runtime_adapter.rs (lines 60-65)

fn main() -> AxResult<()> {
    let mut runtime = DemoRuntime;
    let mut runner = agent("question:string -> answer:string")?;
    let step = runner.execute_actor_step(
        &mut runtime,
        "final()",
        json!({"question": "adapter"}),
        json!({}),
    )?;
    let snapshot = runner.export_session_state()?;
    let timeout = runner.execute_actor_step(
        &mut runtime,
        "timeout()",
        json!({"question": "adapter"}),
        json!({}),
    )?;
    let closed = runner.close_runtime_session()?;
    println!(
        "{}",
        serde_json::to_string_pretty(&json!({
            "stepKind": step.payload["kind"],
            "snapshotAnswer": snapshot["bindings"]["answer"],
            "timeoutCategory": timeout.payload["error_category"],
            "closed": closed
        }))?
    );
    Ok(())
}

examples/runtime_protocol.rs (lines 14-19)

fn main() -> AxResult<()> {
    let repo_root = env::var("AXIR_REPO_ROOT")
        .map_err(|_| axllm::AxError::runtime("AXIR_REPO_ROOT is required"))?;
    let server = env::var("AXIR_AXJS_RUNTIME_SERVER")
        .map_err(|_| axllm::AxError::runtime("AXIR_AXJS_RUNTIME_SERVER is required"))?;
    let mut runtime =
        ProcessCodeRuntime::new(["node".to_string(), "--import=tsx".to_string(), server]);
    env::set_current_dir(repo_root).map_err(axllm::AxError::from)?;
    let mut runner = agent("question:string -> answer:string")?;
    let step = runner.execute_actor_step(
        &mut runtime,
        "answer = inputs.question; await final({ answer })",
        json!({"question": "protocol"}),
        json!({}),
    )?;
    assert_eq!(step.payload["kind"], "final");
    runtime.shutdown()?;
    println!("rust-runtime-protocol-ok");
    Ok(())
}

pub fn test( &mut self, runtime: &mut dyn AxCodeRuntime, code: &str, input: Value, options: Value, ) -> AxResult<RuntimeEnvelope>

pub fn inspect_runtime(&mut self) -> AxResult<Value>

pub fn export_session_state(&mut self) -> AxResult<Value>

Examples found in repository

examples/runtime_adapter.rs (line 66)

fn main() -> AxResult<()> {
    let mut runtime = DemoRuntime;
    let mut runner = agent("question:string -> answer:string")?;
    let step = runner.execute_actor_step(
        &mut runtime,
        "final()",
        json!({"question": "adapter"}),
        json!({}),
    )?;
    let snapshot = runner.export_session_state()?;
    let timeout = runner.execute_actor_step(
        &mut runtime,
        "timeout()",
        json!({"question": "adapter"}),
        json!({}),
    )?;
    let closed = runner.close_runtime_session()?;
    println!(
        "{}",
        serde_json::to_string_pretty(&json!({
            "stepKind": step.payload["kind"],
            "snapshotAnswer": snapshot["bindings"]["answer"],
            "timeoutCategory": timeout.payload["error_category"],
            "closed": closed
        }))?
    );
    Ok(())
}

pub fn restore_session_state(&mut self, snapshot: Value) -> AxResult<Value>

pub fn close_runtime_session(&mut self) -> AxResult<Value>

Examples found in repository

examples/runtime_adapter.rs (line 73)

fn main() -> AxResult<()> {
    let mut runtime = DemoRuntime;
    let mut runner = agent("question:string -> answer:string")?;
    let step = runner.execute_actor_step(
        &mut runtime,
        "final()",
        json!({"question": "adapter"}),
        json!({}),
    )?;
    let snapshot = runner.export_session_state()?;
    let timeout = runner.execute_actor_step(
        &mut runtime,
        "timeout()",
        json!({"question": "adapter"}),
        json!({}),
    )?;
    let closed = runner.close_runtime_session()?;
    println!(
        "{}",
        serde_json::to_string_pretty(&json!({
            "stepKind": step.payload["kind"],
            "snapshotAnswer": snapshot["bindings"]["answer"],
            "timeoutCategory": timeout.payload["error_category"],
            "closed": closed
        }))?
    );
    Ok(())
}

pub fn get_state(&self) -> AxResult<Value>

pub fn set_state(&mut self, state: Value) -> AxResult<Value>

pub fn export_trace(&self) -> AxResult<Value>

pub fn get_chat_log(&self) -> Vec<Value>

pub fn get_action_log(&self) -> Vec<Value>

pub fn with_runtime(self, runtime: Box<dyn AxCodeRuntime>) -> AxResult<Self>

Attach a code runtime so forward() can execute the actor’s code in a real engine. Wraps the runtime as a host value with full capabilities and stores it under options.runtime (the same wiring the conformance runner uses), enabling the Python/Go-style agent(...).with_runtime(rt).forward(...).

Examples found in repository

examples/agent_playbook.rs (line 83)

fn main() -> AxResult<()> {
    // agent.playbook() binds an evolving context playbook to an agent stage. The
    // "responder" target grows the user-facing answer stage; ACE remains an
    // implementation detail behind playbook(), just as optimize() hides GEPA.
    let mut agent = agent_with_options(
        "question:string -> answer:string",
        json!({"name": "qa", "description": "Answer the question.", "runtime": {"language": "Python"}}),
    )?
    .with_runtime(Box::new(Runtime))?;

    let student = Rc::new(RefCell::new(ScriptedClient));
    let mut pb = agent.playbook(
        student,
        None::<Rc<RefCell<ScriptedClient>>>,
        json!({"target": "responder", "maxEpochs": 1}),
    )?;

    let dataset = json!({"train": [{"input": {"question": "Answer briefly."}, "score": 0}]});
    let mut eval_client = ScriptedClient;

    // A zero minimum gain exercises verified acceptance. A positive minimum gain
    // rejects the same flat score and must restore the exact pre-proposal snapshot.
    let accepted = pb.evolve_agent(
        &mut agent,
        &mut eval_client,
        &dataset,
        &json!({"verify": true, "minHeldInGain": 0, "maxProposals": 1, "maxMetricCalls": 2}),
    )?;
    let before_rejection = serde_json::to_string(&pb.to_json())?;
    let rejected = pb.evolve_agent(
        &mut agent,
        &mut eval_client,
        &dataset,
        &json!({"verify": true, "minHeldInGain": 0.1, "maxProposals": 1, "maxMetricCalls": 2}),
    )?;
    let after_rejection = serde_json::to_string(&pb.to_json())?;

    assert_eq!(
        accepted["metricCallsUsed"].as_u64(),
        Some(2),
        "bad metric budget: {accepted}"
    );
    assert_eq!(
        accepted["outcomes"][0]["accepted"].as_bool(),
        Some(true),
        "verified acceptance failed: {accepted}"
    );
    assert_eq!(
        rejected["metricCallsUsed"].as_u64(),
        Some(2),
        "bad metric budget: {rejected}"
    );
    assert_eq!(
        rejected["outcomes"][0]["accepted"].as_bool(),
        Some(false),
        "verified rejection failed: {rejected}"
    );
    assert_eq!(
        after_rejection, before_rejection,
        "rejected proposal was not rolled back exactly"
    );
    assert!(
        pb.to_json().get("playbook").is_some(),
        "missing playbook: {}",
        pb.to_json()
    );
    println!("accepted: {}", accepted["outcomes"][0]);
    println!("rejected: {}", rejected["outcomes"][0]);
    println!("rust-agent-playbook-ok");
    Ok(())
}

pub fn apply_optimization(&mut self, artifact: &Value) -> AxResult<Value>

Apply an optimizer artifact to the agent’s stages: validate (or deserialize) it against the current components, then push the component map into the distiller/executor/responder stages. Mirrors AxGen::apply_optimization (agents carry no few-shot demos, so the demo branch is omitted).

pub fn evaluate_optimization<C: AxAIClient>( &mut self, client: &mut C, dataset: &Value, candidate_map: &Value, options: &Value, ) -> AxResult<Value>

Evaluate a candidate component map over a dataset by running the agent end to end for each task and scoring the predictions. The original component map is always restored afterwards. Mirrors AxAgent.evaluate_optimization in the other ports (per-row delegation to evaluate_optimization_task).

pub fn optimize_with<C: AxAIClient>( &mut self, engine: &mut dyn OptimizerEngine, dataset: &Value, options: &Value, client: Option<Rc<RefCell<C>>>, ) -> AxResult<Value>

Run an optimizer engine against the agent. Builds the optimizer request from the agent’s components + trace, drives the engine (scoring candidates with a live client when one is supplied), normalizes the artifact, and applies it unless options.apply == false. Mirrors AxGen::optimize_with with the "axagent" program kind.

pub fn optimize<C: AxAIClient>( &mut self, engine: &mut dyn OptimizerEngine, dataset: &Value, options: &Value, client: Option<Rc<RefCell<C>>>, ) -> AxResult<Value>

Optimize the agent with the engine carried in options.engine/options.optimizer. Thin wrapper over optimize_with matching the Python/ Java/C++ agent.optimize(dataset, options) surface.

pub fn playbook<S: AxAIClient + 'static, T: AxAIClient + 'static>( &mut self, student: Rc<RefCell<S>>, teacher: Option<Rc<RefCell<T>>>, options: Value, ) -> AxResult<AxPlaybook<S, T>>

Build an evolving-context AxPlaybook bound to a live agent stage (the actor/task stage by default; pass {"target":"responder"} for the responder). The playbook SHARES the stage’s AxGen, so as it evolves the composed instruction is written straight into the live stage prompt — unless options.apply == false, in which case injection is disabled. The evolution engine (ACE) is an implementation detail.

Examples found in repository

examples/agent_playbook.rs (lines 86-90)

fn main() -> AxResult<()> {
    // agent.playbook() binds an evolving context playbook to an agent stage. The
    // "responder" target grows the user-facing answer stage; ACE remains an
    // implementation detail behind playbook(), just as optimize() hides GEPA.
    let mut agent = agent_with_options(
        "question:string -> answer:string",
        json!({"name": "qa", "description": "Answer the question.", "runtime": {"language": "Python"}}),
    )?
    .with_runtime(Box::new(Runtime))?;

    let student = Rc::new(RefCell::new(ScriptedClient));
    let mut pb = agent.playbook(
        student,
        None::<Rc<RefCell<ScriptedClient>>>,
        json!({"target": "responder", "maxEpochs": 1}),
    )?;

    let dataset = json!({"train": [{"input": {"question": "Answer briefly."}, "score": 0}]});
    let mut eval_client = ScriptedClient;

    // A zero minimum gain exercises verified acceptance. A positive minimum gain
    // rejects the same flat score and must restore the exact pre-proposal snapshot.
    let accepted = pb.evolve_agent(
        &mut agent,
        &mut eval_client,
        &dataset,
        &json!({"verify": true, "minHeldInGain": 0, "maxProposals": 1, "maxMetricCalls": 2}),
    )?;
    let before_rejection = serde_json::to_string(&pb.to_json())?;
    let rejected = pb.evolve_agent(
        &mut agent,
        &mut eval_client,
        &dataset,
        &json!({"verify": true, "minHeldInGain": 0.1, "maxProposals": 1, "maxMetricCalls": 2}),
    )?;
    let after_rejection = serde_json::to_string(&pb.to_json())?;

    assert_eq!(
        accepted["metricCallsUsed"].as_u64(),
        Some(2),
        "bad metric budget: {accepted}"
    );
    assert_eq!(
        accepted["outcomes"][0]["accepted"].as_bool(),
        Some(true),
        "verified acceptance failed: {accepted}"
    );
    assert_eq!(
        rejected["metricCallsUsed"].as_u64(),
        Some(2),
        "bad metric budget: {rejected}"
    );
    assert_eq!(
        rejected["outcomes"][0]["accepted"].as_bool(),
        Some(false),
        "verified rejection failed: {rejected}"
    );
    assert_eq!(
        after_rejection, before_rejection,
        "rejected proposal was not rolled back exactly"
    );
    assert!(
        pb.to_json().get("playbook").is_some(),
        "missing playbook: {}",
        pb.to_json()
    );
    println!("accepted: {}", accepted["outcomes"][0]);
    println!("rejected: {}", rejected["outcomes"][0]);
    println!("rust-agent-playbook-ok");
    Ok(())
}

pub fn get_playbook_state(&self) -> Option<Value>

Trait Implementations

impl AxProgram for AxAgent

fn program_kind(&self) -> &'static str