Crate funera_orchestrate 

funera-orchestrate

Easy-to-use orchestration layer for [funera-core].

This crate provides a high-level agent API (Agent) and a runtime container (AgentRuntime) that together let you integrate funera’s LLM agent runtime into your own projects with minimal boilerplate.

Features

Feature	Default	Description
deepseek	✅	DeepSeek provider
openai	❌	OpenAI provider
tool	✅	Tool system (trait, registry, executor)
funera-builtin-tools	❌	Built-in tools (Read, Write, Edit, Shell)
security	❌	Tool policy enforcement
middleware	❌	Event interception pipeline (Inspector + Mutator)
skill	❌	Skill loading and prompt injection
sandbox	❌	Kernel-level subprocess isolation

---

Quick Start

use funera_orchestrate::{Agent, AgentRuntime, DeepSeekProvider};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let runtime = AgentRuntime::<DeepSeekProvider>::builder()
        .api_key(std::env::var("DEEPSEEK_API_KEY")?)
        .model("deepseek-v4-flash")
        .build()?;

    let agent = Agent::builder()
        .system_prompt("You are a helpful assistant.")
        .build();

    let resp = agent.fire("Hello!", &runtime).await?;
    println!("{}", resp.content);
    Ok(())
}

Core Concepts

Concept	Type	Description
Runtime	AgentRuntime	Shared infrastructure + conversation session
Agent	Agent	Behavioural config (system prompt, callbacks)
One-shot	Agent::fire	Temporary session, discarded after call
Multi-turn	Agent::send	Persistent session across calls
Streaming	fire_stream / send_stream	Token-by-token streaming

Examples

One-shot query with stream

let runtime = AgentRuntime::<DeepSeekProvider>::builder()
    .api_key(std::env::var("DEEPSEEK_API_KEY")?)
    .model("deepseek-v4-flash")
    .build()?;

let agent = Agent::builder()
    .on_token(|t| print!("{t}"))
    .build();

let mut rx = agent.fire_stream("Explain Rust's ownership model", &runtime).await?;
while let Some(event) = rx.recv().await {
    if let AgentEvent::Text(t) = event {
        print!("{t}");
    }
}

Multi-turn conversation with callbacks

let runtime = AgentRuntime::<DeepSeekProvider>::builder()
    .api_key(std::env::var("DEEPSEEK_API_KEY")?)
    .model("deepseek-v4-flash")
    .build()?;

let agent = Agent::builder()
    .system_prompt("You are helpful.")
    .on_tool_call(|name, _| eprintln!("[tool] {name}"))
    .on_turn_start(|| eprintln!("--- turn ---"))
    .build();

let handle = agent.send("Hi, I'm Alice.", runtime).await?;
let (runtime, _resp) = handle.await?;
let handle = agent.send("What's my name?", runtime).await?;
let (_runtime, _resp) = handle.await?;

Switching models on the same provider

let fast = AgentRuntime::<DeepSeekProvider>::builder()
    .api_key(std::env::var("DEEPSEEK_API_KEY")?)
    .model("deepseek-v4-flash")
    .build()?;

let powerful = AgentRuntime::<DeepSeekProvider>::builder()
    .api_key(std::env::var("DEEPSEEK_API_KEY")?)
    .model("deepseek-r1")
    .build()?;

let agent = Agent::builder().build();

let (fast, _) = agent.send("Hello", fast).await?.await?;              // fast model
agent.fire("What is Rust?", &powerful).await?;                        // powerful model (temp)
let (_fast, _) = agent.send("Tell me more", fast).await?.await?;       // back to fast

Security configuration

Requires the security feature (and optionally funera-builtin-tools, sandbox).

let runtime = AgentRuntime::<DeepSeekProvider>::builder()
    .api_key(std::env::var("DEEPSEEK_API_KEY")?)
    .model("deepseek-v4-flash")
    .with_builtin_tools()
    .with_tool_policy(
        ToolPolicy {
            denied_tools: ["shell".into()].into_iter().collect(),
            shell_policy: Some(ShellPolicy::with_allowed(
                vec!["git".into(), "cargo".into()],
            )),
            ..Default::default()
        },
    )
    .build()?;

Module Structure

• runtime — AgentRuntimeBuilder and AgentRuntime
• agent — AgentBuilder and Agent
• dispatcher — Event bus subscription and callback dispatch
• event — AgentEvent enum
• response — ChatResponse and ToolCallInfo
• error — OrchestrateError

Re-exports

pub use agent::Agent;

pub use agent::AgentBuilder;

pub use dispatcher::CallbackRegistry;

pub use error::OrchestrateError;

pub use event::AgentEvent;

pub use event::RawAgentEvent;

pub use response::ChatResponse;

pub use response::ToolCallInfo;

pub use runtime::Acquired;

pub use runtime::AgentRuntime;

pub use runtime::AgentRuntimeBuilder;

pub use runtime::Idle;

pub use send_handle::FireStreamHandle;

pub use send_handle::SendHandle;

pub use send_handle::SendStreamHandle;

Modules

agent

dispatcher

error

event

response

runtime

send_handle

Structs

DeepSeekProvider

ToolCallErrorInfo

ToolCallRequest

ToolCallResponse

Enums

EnvStateEvent

ReactEvent

TokenEvent