vifu-runtime

vifu-runtime is the embeddable, stateful Agent Runtime at the center of Vifu. Rust applications use this crate to embed Vifu directly in their process. The separate vifu package installs the complete Server and Agent Gateway application.

The crate uses Bevy App and ECS primitives without the renderer, windowing stack, HTTP server, or Vifu Console. The default crates.io build includes the SQLite store and Local Whisper provider helpers; hosts that need a smaller core can compile with default-features = false. It also provides the higher-level VifuRuntime API used by applications and Vifu Server.

Add the runtime

[dependencies]
vifu-runtime = "0.1"

Register providers, agents, and endpoints

use std::sync::Arc;
use vifu_runtime::prelude::*;

let mut provider = HttpCapabilityProvider::new(
    "models",
    "https://provider.example.com/v1",
    Some(std::env::var("MODEL_API_TOKEN")?),
)?;
provider.add_route(
    "chat",
    HttpCapabilityRoute::OpenAiChat {
        model: "model-name".into(),
        persona: json!({ "instructions": "Be concise." }),
    },
)?;

let runtime = VifuRuntime::new("my-application")?;
runtime.register_provider("models", Arc::new(provider))?;
runtime.register_agent(AgentDefinition {
    id: "guide".into(),
    name: "Guide".into(),
    provider: "models".into(),
    capabilities: vec!["chat".into()],
    metadata: json!({}),
})?;
runtime.register_endpoint(EndpointDefinition {
    name: "guide".into(),
    agent: "guide".into(),
    capability: "chat".into(),
    timeout_ms: 30_000,
})?;

let output = runtime
    .invoke(InvocationInput::json(
        "guide",
        json!({ "messages": [{ "role": "user", "content": "Hello" }] }),
    ))
    .await?;

Providers implement AgentProvider and are registered dynamically, so an application can connect an in-process agent, an HTTP model service, or its own transport without changing Cargo features. MemoryRuntimeStore is the default. Pass a host RuntimeStore to VifuRuntime::with_store for durable sessions, or use project snapshot export and restore.

timeout_ms is an inactivity timeout. Output, stage, and provider activity events renew it; cancellation is propagated to the provider when it expires.

start_invoke, poll_invocation, and cancel_invocation provide the same result contract to synchronous game loops. The lower-level HeadlessRuntime remains available for Bevy plugins, command/event processing, and custom effects.

Vifu Server reuses this invocation model and adds multi-project HTTP APIs, access control, database persistence, and traces. Agent Gateway is an optional Server transport for providers running on another machine.