vv-agent-rs

中文文档

vv-agent-rs is the Rust workspace for the vv-agent crate: an embeddable agent runtime, SDK, CLI, tool system, memory layer, and workspace abstraction for model-driven automation.

It is designed around explicit agent control flow. A task is not considered done because the model wrote a final-looking sentence; the model must call task_finish to complete or ask_user to pause for user input. This keeps CLI runs, SDK sessions, background runs, and distributed execution on the same result contract.

Architecture

AgentRuntime
├── LLM client              # vv-llm backed chat client, endpoint resolution, streaming
├── CycleRunner             # one model turn: prompt, response, tool-call plan
├── ToolOrchestrator        # tool policy, approval, dispatch, timeout, telemetry
├── RuntimeHookManager      # before/after hooks for LLM, tools, and memory
├── MemoryManager           # context budgeting, compaction, artifacts, session memory
├── RunHandle / RunEvent    # live control, typed events, event-store replay
├── RuntimeExecutionBackend # run scheduling
│   ├── InlineBackend       # synchronous default
│   ├── ThreadBackend       # non-blocking task submission
│   └── DistributedBackend  # checkpointed cycles with pluggable dispatch
└── WorkspaceBackend        # file/object I/O boundary for tools
    ├── LocalWorkspaceBackend
    ├── MemoryWorkspaceBackend
    └── S3WorkspaceBackend

Provider request building, endpoint transport, retries, streaming deltas, token limits, usage accounting, and provider-specific protocol details are delegated to the published vv-llm crate. vv-agent focuses on agent execution: prompts, tools, hooks, memory, sessions, workspace access, and orchestration.

Setup

Run commands from this repository root:

cd vv-agent-rs
cargo test -p vv-agent

Most real-model examples and the CLI read a local vv-llm settings file. Keep the credential-bearing file untracked:

cp crates/vv-agent/tests/dev_settings.example.json local_settings.json
# Fill endpoint keys in local_settings.json.

The default settings path is local_settings.json. You can override it with VV_AGENT_LOCAL_SETTINGS for examples or --settings-file for the CLI.

Quick Start

CLI

cargo run -p vv-agent -- \
  --prompt "Summarize this repository" \
  --backend deepseek \
  --model deepseek-v4-pro \
  --settings-file local_settings.json \
  --workspace ./workspace \
  --verbose

CLI flags:

Agent + Runner SDK

Use Agent + Runner for new embedded applications. Agent describes instructions, model, tools, handoffs, hooks, and defaults. Runner owns model providers, workspace defaults, and execution. RunConfig overrides one run without changing the agent definition, including the public ExecutionMode for inline, threaded, or distributed execution.

use vv_agent::{Agent, ExecutionMode, ModelRef, Runner, RunConfig, VvLlmModelProvider};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let provider = VvLlmModelProvider::from_settings_file("local_settings.json")
        .with_default_backend("deepseek");
    let runner = Runner::builder()
        .model_provider(provider)
        .workspace("./workspace")
        .build()?;

    let agent = Agent::builder("assistant")
        .instructions("You plan, use tools when useful, and call task_finish when done.")
        .model(ModelRef::backend("deepseek", "deepseek-v4-pro"))
        .build()?;

    let result = runner
        .run_with_config(
            &agent,
            "Create notes.md with three project takeaways.",
            RunConfig::builder()
                .max_cycles(12)
                .execution_mode(ExecutionMode::Inline)
                .build(),
        )
        .await?;
    println!("{:?}", result.final_output());
    Ok(())
}

Sessions keep conversation history across runner calls:

use vv_agent::{MemorySession, RunConfig};

let session = MemorySession::new("thread-001");
runner
    .run_with_config(&agent, "Analyze the current workspace.", RunConfig::builder().session(session.clone()).build())
    .await?;
let result = runner
    .run_with_config(&agent, "Continue with follow-up suggestions.", RunConfig::builder().session(session).build())
    .await?;

Live Runs and Events

Runner::run() and run_with_config() are the one-shot entrypoints. Use Runner::start() when an application needs live UI/server control: subscribe to events, approve pending tools, cancel a run, or await the final result from one RunHandle. Runner::stream() is a convenience wrapper over start() for typed live events.

use vv_agent::{ApprovalDecision, RunConfig, RunEventPayload};

let handle = runner
    .start(&agent, "Inspect the workspace and report findings.", RunConfig::default())
    .await?;
let mut events = handle.events();

while let Some(event) = events.next().await {
    match event?.payload() {
        RunEventPayload::AssistantDelta { delta } => print!("{delta}"),
        RunEventPayload::ToolCallStarted { tool_name, .. } => {
            eprintln!("tool started: {tool_name}");
        }
        RunEventPayload::ApprovalRequested { request_id, .. } => {
            handle.approve(request_id, ApprovalDecision::allow()).await?;
        }
        _ => {}
    }
}

let result = handle.result().await?;

Each RunEvent is a v1 envelope with event_id, run_id, trace_id, optional session and parent identifiers, timing, metadata, and a typed RunEventPayload. JsonlRunEventStore can append events and replay a run, including child events linked by parent run id.

Live tool approval uses ApprovalProvider and the handle-owned broker. The model-facing ask_user tool remains for requesting user input as part of the conversation. Host applications can also attach ContextProvider values for ordered prompt fragments and MemoryProvider values for external search, save, and compaction lifecycle hooks.

App Server

Use the App Server when a product shell needs to drive vv-agent over a stable JSON-RPC protocol instead of linking directly to runtime internals. It supports stdio JSONL transport, thread and turn lifecycle requests, live item notifications, approval server requests, replay, schema generation, and a typed Rust test client.

vv-agent app-server --listen stdio
vv-agent app-server generate-json-schema --out target/app-server-schema/json
vv-agent app-server generate-ts --out target/app-server-schema/typescript

See crates/vv-agent/docs/app_server.md for protocol examples and client responsibilities.

Low-Level Runtime

Use the runtime directly only when you need to assemble the LLM client, prompt, tool registry, workspace, and run controls yourself. New embedded applications should start with Agent + Runner.

use std::path::PathBuf;

use vv_agent::config::build_vv_llm_from_local_settings;
use vv_agent::prompt::{build_system_prompt_with_options, BuildSystemPromptOptions};
use vv_agent::{build_default_registry, AgentRuntime, AgentTask, RuntimeRunControls};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let (llm, resolved) = build_vv_llm_from_local_settings(
        "local_settings.json",
        "deepseek",
        "deepseek-v4-pro",
        90.0,
    )?;
    let runtime = AgentRuntime::new(llm).with_tool_registry(build_default_registry());
    let system_prompt = build_system_prompt_with_options(
        "You are a reliable execution agent.",
        BuildSystemPromptOptions {
            language: "zh-CN".to_string(),
            use_workspace: true,
            enable_todo_management: true,
            ..BuildSystemPromptOptions::default()
        },
    );

    let mut task = AgentTask::new(
        "demo",
        resolved.model_id,
        system_prompt,
        "Read the workspace README and summarize the project.",
    );
    task.max_cycles = 12;

    let result = runtime.run_with_controls(
        task,
        RuntimeRunControls {
            workspace: Some(PathBuf::from("./workspace")),
            ..RuntimeRunControls::default()
        },
    )?;
    println!("{:?}: {:?}", result.status, result.final_answer);
    Ok(())
}

See crates/vv-agent/examples/01_quick_start.rs for a complete low-level runtime version with event logging.

Core Capabilities

Execution Backends

The public SDK selects scheduling through ExecutionMode. Lower-level runtime backend structs remain available for advanced integrations:

Checkpointed runs can store state in memory, SQLite, or Redis. The optional apalis feature adds an Apalis job bridge for applications that already use Apalis workers:

cargo test -p vv-agent --features apalis --test apalis_backend

The distributed API also has an inline fallback, which is useful for local development and tests. See crates/vv-agent/examples/23_distributed_backend.rs.

Workspace Backends

All built-in file tools go through WorkspaceBackend. That keeps local files, memory-backed files, and S3-compatible object storage on the same tool contract.

find_files and search_files include safety defaults for large workspaces: bounded result counts, hidden/dependency directory filtering, explicit ignored path inclusion, and local rg acceleration when available.

Examples

The numbered examples are the best way to explore the public API:

cargo run -p vv-agent --example 01_quick_start
cargo run -p vv-agent --example 03_sdk_client
cargo run -p vv-agent --example 04_session_api
cargo run -p vv-agent --example 23_distributed_backend
cargo run -p vv-agent --example 24_workspace_backends
cargo run -p vv-agent --example 26_agent_runner_facade
cargo run -p vv-agent --example 27_facade_handoff
cargo run -p vv-agent --example 28_facade_approval_background_trace

See crates/vv-agent/examples/README.md for the full example index covering Agent + Runner, runtime hooks, custom tools, handoffs, live approval, background tasks, tracing, sub-agent pipelines, skills, streaming, cancellation, state stores, execution backends, workspace backends, and temporary tool injection.

Live Smoke Tests

Live tests are opt-in and use a local settings file without printing credentials. By default they read the untracked crates/vv-agent/tests/dev_settings.json; start from crates/vv-agent/tests/dev_settings.example.json.

VV_AGENT_RUN_LIVE_TESTS=1 \
cargo test -p vv-agent --test live_deepseek -- --ignored

VV_AGENT_RUN_LIVE_TESTS=1 \
cargo test -p vv-agent --test live_edit_file -- --ignored --test-threads=1

The live suite exercises direct runtime completion, SDK completion, ask_user, todo updates, memory notes, skill activation, workspace tools, image reading, safe edit_file recovery, foreground and background shell commands, sub-agent waiting/status checks, and configured sub-agent delegation.

Verification

Run the standard checks from vv-agent-rs/:

cargo fmt --check
cargo test -p vv-agent
cargo check --examples
cargo clippy --all-targets --all-features -- -D warnings

Focused checks that are useful while editing public docs and examples:

cargo test -p vv-agent --test public_api
cargo test -p vv-agent --test examples_coverage

Repository Layout

vv-agent-rs/
  Cargo.toml
  crates/vv-agent/
    src/
      cli/        # CLI entrypoint and task construction
      config/     # LLM settings loading and model resolution
      llm/        # LLM trait, scripted test client, vv-llm client bridge
      memory/     # compaction, artifacts, session memory, token budgeting
      prompt/     # system prompt sections and prompt-cache metadata
      agent.rs    # public Agent builder
      runner.rs   # public Runner over runtime execution
      run_config.rs
      model.rs
      model_settings.rs
      sessions.rs
      runtime/    # agent runtime, hooks, backends, cancellation, sub-agents
      skills/     # skill discovery, parsing, validation, activation
      tools/      # registry, schemas, dispatcher, built-in handlers
      workspace/  # local, memory, and S3 workspace backends
    examples/
    tests/
  docs/

Additional design notes live under docs/, especially docs/architecture.md and docs/model-settings.md.