{"id":50725980,"url":"https://github.com/andersonby/vv-agent-rs","last_synced_at":"2026-06-10T04:01:49.381Z","repository":{"id":361431875,"uuid":"1254440030","full_name":"AndersonBY/vv-agent-rs","owner":"AndersonBY","description":"Rust agent runtime, SDK, CLI, tools, and workspace backends","archived":false,"fork":false,"pushed_at":"2026-05-30T15:32:38.000Z","size":1334,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-30T17:12:38.644Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AndersonBY.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-30T15:10:57.000Z","updated_at":"2026-05-30T15:32:24.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/AndersonBY/vv-agent-rs","commit_stats":null,"previous_names":["andersonby/vv-agent-rs"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/AndersonBY/vv-agent-rs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AndersonBY%2Fvv-agent-rs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AndersonBY%2Fvv-agent-rs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AndersonBY%2Fvv-agent-rs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AndersonBY%2Fvv-agent-rs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AndersonBY","download_url":"https://codeload.github.com/AndersonBY/vv-agent-rs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AndersonBY%2Fvv-agent-rs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34136112,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-10T02:00:07.152Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-10T04:01:48.346Z","updated_at":"2026-06-10T04:01:49.369Z","avatar_url":"https://github.com/AndersonBY.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# vv-agent-rs\n\n[中文文档](README_ZH.md)\n\n`vv-agent-rs` is the Rust workspace for the `vv-agent` crate: an embeddable\nagent runtime, SDK, CLI, tool system, memory layer, and workspace abstraction\nfor model-driven automation.\n\nIt is designed around explicit agent control flow. A task is not considered\ndone because the model wrote a final-looking sentence; the model must call\n`task_finish` to complete or `ask_user` to pause for user input. This keeps\nCLI runs, SDK sessions, background runs, and distributed execution on the same\nresult contract.\n\n## Architecture\n\n```text\nAgentRuntime\n├── LLM client              # vv-llm backed chat client, endpoint resolution, streaming\n├── CycleRunner             # one model turn: prompt, response, tool-call plan\n├── ToolOrchestrator        # tool policy, approval, dispatch, timeout, telemetry\n├── RuntimeHookManager      # before/after hooks for LLM, tools, and memory\n├── MemoryManager           # context budgeting, compaction, artifacts, session memory\n├── RunHandle / RunEvent    # live control, typed events, event-store replay\n├── RuntimeExecutionBackend # run scheduling\n│   ├── InlineBackend       # synchronous default\n│   ├── ThreadBackend       # non-blocking task submission\n│   └── DistributedBackend  # checkpointed cycles with pluggable dispatch\n└── WorkspaceBackend        # file/object I/O boundary for tools\n    ├── LocalWorkspaceBackend\n    ├── MemoryWorkspaceBackend\n    └── S3WorkspaceBackend\n```\n\nProvider request building, endpoint transport, retries, streaming deltas, token\nlimits, usage accounting, and provider-specific protocol details are delegated\nto the published `vv-llm` crate. `vv-agent` focuses on agent execution: prompts,\ntools, hooks, memory, sessions, workspace access, and orchestration.\n\n## Setup\n\nRun commands from this repository root:\n\n```bash\ncd vv-agent-rs\ncargo test -p vv-agent\n```\n\nMost real-model examples and the CLI read a local `vv-llm` settings file. Keep\nthe credential-bearing file untracked:\n\n```bash\ncp crates/vv-agent/tests/dev_settings.example.json local_settings.json\n# Fill endpoint keys in local_settings.json.\n```\n\nThe default settings path is `local_settings.json`. You can override it with\n`VV_AGENT_LOCAL_SETTINGS` for examples or `--settings-file` for the CLI.\n\n## Quick Start\n\n### CLI\n\n```bash\ncargo run -p vv-agent -- \\\n  --prompt \"Summarize this repository\" \\\n  --backend deepseek \\\n  --model deepseek-v4-pro \\\n  --settings-file local_settings.json \\\n  --workspace ./workspace \\\n  --verbose\n```\n\nCLI flags:\n\n| Flag | Purpose |\n| --- | --- |\n| `--prompt` | Required user task. |\n| `--backend` | Backend key under `LLM_SETTINGS.backends`. |\n| `--model` | Model key under the selected backend. |\n| `--settings-file` | Local `vv-llm` settings file. |\n| `--workspace` | Directory exposed to workspace tools. |\n| `--max-cycles` | Maximum runtime cycles before stopping. |\n| `--language` | Prompt/tool guidance locale. |\n| `--agent-type` | Optional agent profile type such as `computer`. |\n| `--verbose` | Emit per-cycle runtime events. |\n\n### Agent + Runner SDK\n\nUse `Agent` + `Runner` for new embedded applications. `Agent`\ndescribes instructions, model, tools, handoffs, hooks, and defaults. `Runner`\nowns model providers, workspace defaults, and execution. `RunConfig` overrides\none run without changing the agent definition, including the public\n`ExecutionMode` for inline, threaded, or distributed execution.\n\n```rust\nuse vv_agent::{Agent, ExecutionMode, ModelRef, Runner, RunConfig, VvLlmModelProvider};\n\n#[tokio::main]\nasync fn main() -\u003e Result\u003c(), Box\u003cdyn std::error::Error\u003e\u003e {\n    let provider = VvLlmModelProvider::from_settings_file(\"local_settings.json\")\n        .with_default_backend(\"deepseek\");\n    let runner = Runner::builder()\n        .model_provider(provider)\n        .workspace(\"./workspace\")\n        .build()?;\n\n    let agent = Agent::builder(\"assistant\")\n        .instructions(\"You plan, use tools when useful, and call task_finish when done.\")\n        .model(ModelRef::backend(\"deepseek\", \"deepseek-v4-pro\"))\n        .build()?;\n\n    let result = runner\n        .run_with_config(\n            \u0026agent,\n            \"Create notes.md with three project takeaways.\",\n            RunConfig::builder()\n                .max_cycles(12)\n                .execution_mode(ExecutionMode::Inline)\n                .build(),\n        )\n        .await?;\n    println!(\"{:?}\", result.final_output());\n    Ok(())\n}\n```\n\nSessions keep conversation history across runner calls:\n\n```rust\nuse vv_agent::{MemorySession, RunConfig};\n\nlet session = MemorySession::new(\"thread-001\");\nrunner\n    .run_with_config(\u0026agent, \"Analyze the current workspace.\", RunConfig::builder().session(session.clone()).build())\n    .await?;\nlet result = runner\n    .run_with_config(\u0026agent, \"Continue with follow-up suggestions.\", RunConfig::builder().session(session).build())\n    .await?;\n```\n\n### Live Runs and Events\n\n`Runner::run()` and `run_with_config()` are the one-shot entrypoints. Use\n`Runner::start()` when an application needs live UI/server control: subscribe\nto events, approve pending tools, cancel a run, or await the final result from\none `RunHandle`. `Runner::stream()` is a convenience wrapper over `start()` for\ntyped live events.\n\n```rust\nuse vv_agent::{ApprovalDecision, RunConfig, RunEventPayload};\n\nlet handle = runner\n    .start(\u0026agent, \"Inspect the workspace and report findings.\", RunConfig::default())\n    .await?;\nlet mut events = handle.events();\n\nwhile let Some(event) = events.next().await {\n    match event?.payload() {\n        RunEventPayload::AssistantDelta { delta } =\u003e print!(\"{delta}\"),\n        RunEventPayload::ToolCallStarted { tool_name, .. } =\u003e {\n            eprintln!(\"tool started: {tool_name}\");\n        }\n        RunEventPayload::ApprovalRequested { request_id, .. } =\u003e {\n            handle.approve(request_id, ApprovalDecision::allow()).await?;\n        }\n        _ =\u003e {}\n    }\n}\n\nlet result = handle.result().await?;\n```\n\nEach `RunEvent` is a v1 envelope with `event_id`, `run_id`, `trace_id`,\noptional session and parent identifiers, timing, metadata, and a typed\n`RunEventPayload`. `JsonlRunEventStore` can append events and replay a run,\nincluding child events linked by parent run id.\n\nLive tool approval uses `ApprovalProvider` and the handle-owned broker. The\nmodel-facing `ask_user` tool remains for requesting user input as part of the\nconversation. Host applications can also attach `ContextProvider` values for\nordered prompt fragments and `MemoryProvider` values for external search, save,\nand compaction lifecycle hooks.\n\n### App Server\n\nUse the App Server when a product shell needs to drive `vv-agent` over a stable\nJSON-RPC protocol instead of linking directly to runtime internals. It supports\nstdio JSONL transport, thread and turn lifecycle requests, live item\nnotifications, approval server requests, replay, schema generation, and a typed\nRust test client.\n\n```bash\nvv-agent app-server --listen stdio\nvv-agent app-server generate-json-schema --out target/app-server-schema/json\nvv-agent app-server generate-ts --out target/app-server-schema/typescript\n```\n\nSee `crates/vv-agent/docs/app_server.md` for protocol examples and client\nresponsibilities.\n\n### Low-Level Runtime\n\nUse the runtime directly only when you need to assemble the LLM client, prompt,\ntool registry, workspace, and run controls yourself. New embedded applications\nshould start with `Agent` + `Runner`.\n\n```rust\nuse std::path::PathBuf;\n\nuse vv_agent::config::build_vv_llm_from_local_settings;\nuse vv_agent::prompt::{build_system_prompt_with_options, BuildSystemPromptOptions};\nuse vv_agent::{build_default_registry, AgentRuntime, AgentTask, RuntimeRunControls};\n\nfn main() -\u003e Result\u003c(), Box\u003cdyn std::error::Error\u003e\u003e {\n    let (llm, resolved) = build_vv_llm_from_local_settings(\n        \"local_settings.json\",\n        \"deepseek\",\n        \"deepseek-v4-pro\",\n        90.0,\n    )?;\n    let runtime = AgentRuntime::new(llm).with_tool_registry(build_default_registry());\n    let system_prompt = build_system_prompt_with_options(\n        \"You are a reliable execution agent.\",\n        BuildSystemPromptOptions {\n            language: \"zh-CN\".to_string(),\n            use_workspace: true,\n            enable_todo_management: true,\n            ..BuildSystemPromptOptions::default()\n        },\n    );\n\n    let mut task = AgentTask::new(\n        \"demo\",\n        resolved.model_id,\n        system_prompt,\n        \"Read the workspace README and summarize the project.\",\n    );\n    task.max_cycles = 12;\n\n    let result = runtime.run_with_controls(\n        task,\n        RuntimeRunControls {\n            workspace: Some(PathBuf::from(\"./workspace\")),\n            ..RuntimeRunControls::default()\n        },\n    )?;\n    println!(\"{:?}: {:?}\", result.status, result.final_answer);\n    Ok(())\n}\n```\n\nSee `crates/vv-agent/examples/01_quick_start.rs` for a complete low-level\nruntime version with event logging.\n\n## Core Capabilities\n\n| Area | What `vv-agent` provides |\n| --- | --- |\n| Runtime | Multi-cycle model execution, explicit terminal states, live `RunHandle`, cancellation, typed events, event replay, and max-cycle handling. |\n| Tools | Built-in tools plus a `ToolOrchestrator` path for policy, approval, dispatch, timeout, and telemetry. |\n| SDK | `Agent`, `Runner`, `RunConfig`, `ModelSettings`, typed tools, `Agent::as_tool()`, `RunEvent`, providers, and `Session`. |\n| Memory | Token budgeting, prompt-too-long retries, micro and full compaction, artifact-backed large tool results, image trimming, session memory, and external provider hooks. |\n| Hooks | Rust `RuntimeHook` implementations can inspect or patch LLM calls, tool calls, memory compaction, and run lifecycle behavior. |\n| Sub-agents | Runtime-backed sub-task creation, batch submission, background status polling, continuation, steering, and inherited streaming callbacks. |\n| Skills | Skill directory discovery, frontmatter parsing, validation, prompt rendering with budget limits, activation, and activation history. |\n| Workspace | Local, in-memory, and S3 object-store backends behind one `WorkspaceBackend` boundary. |\n\n## Execution Backends\n\nThe public SDK selects scheduling through `ExecutionMode`. Lower-level runtime\nbackend structs remain available for advanced integrations:\n\n| Backend | Use case |\n| --- | --- |\n| `ExecutionMode::Inline` | Default synchronous execution in the current process. |\n| `ExecutionMode::Threaded` | Submit runs without blocking the caller. |\n| `ExecutionMode::Distributed` | Checkpointed cycle execution with serializable runtime recipes and pluggable dispatch. |\n\nCheckpointed runs can store state in memory, SQLite, or Redis. The optional\n`apalis` feature adds an Apalis job bridge for applications that already use\nApalis workers:\n\n```bash\ncargo test -p vv-agent --features apalis --test apalis_backend\n```\n\nThe distributed API also has an inline fallback, which is useful for local\ndevelopment and tests. See `crates/vv-agent/examples/23_distributed_backend.rs`.\n\n## Workspace Backends\n\nAll built-in file tools go through `WorkspaceBackend`. That keeps local files,\nmemory-backed files, and S3-compatible object storage on the same tool contract.\n\n`list_files` and `workspace_grep` include safety defaults for large workspaces:\nbounded result counts, hidden/dependency directory filtering, explicit ignored\npath inclusion, and local `rg` acceleration when available.\n\n## Examples\n\nThe numbered examples are the best way to explore the public API:\n\n```bash\ncargo run -p vv-agent --example 01_quick_start\ncargo run -p vv-agent --example 03_sdk_client\ncargo run -p vv-agent --example 04_session_api\ncargo run -p vv-agent --example 23_distributed_backend\ncargo run -p vv-agent --example 24_workspace_backends\ncargo run -p vv-agent --example 26_agent_runner_facade\ncargo run -p vv-agent --example 27_facade_handoff\ncargo run -p vv-agent --example 28_facade_approval_background_trace\n```\n\nSee `crates/vv-agent/examples/README.md` for the full example index covering\nAgent + Runner, runtime hooks, custom tools, handoffs, live approval,\nbackground tasks, tracing, sub-agent pipelines, skills, streaming, cancellation,\nstate stores, execution backends, workspace backends, and temporary tool\ninjection.\n\n## Live Smoke Tests\n\nLive tests are opt-in and use a local settings file without printing\ncredentials. By default they read the untracked\n`crates/vv-agent/tests/dev_settings.json`; start from\n`crates/vv-agent/tests/dev_settings.example.json`.\n\n```bash\nVV_AGENT_RUN_LIVE_TESTS=1 \\\ncargo test -p vv-agent --test live_deepseek -- --ignored\n```\n\nThe live suite exercises direct runtime completion, SDK completion,\n`ask_user`, todo updates, memory notes, skill activation, workspace tools,\nimage reading, foreground and background shell commands, sub-agent polling, and\nconfigured sub-agent delegation.\n\n## Verification\n\nRun the standard checks from `vv-agent-rs/`:\n\n```bash\ncargo fmt --check\ncargo test -p vv-agent\ncargo check --examples\ncargo clippy --all-targets --all-features -- -D warnings\n```\n\nFocused checks that are useful while editing public docs and examples:\n\n```bash\ncargo test -p vv-agent --test public_api\ncargo test -p vv-agent --test examples_coverage\n```\n\n## Repository Layout\n\n```text\nvv-agent-rs/\n  Cargo.toml\n  crates/vv-agent/\n    src/\n      cli/        # CLI entrypoint and task construction\n      config/     # LLM settings loading and model resolution\n      llm/        # LLM trait, scripted test client, vv-llm client bridge\n      memory/     # compaction, artifacts, session memory, token budgeting\n      prompt/     # system prompt sections and prompt-cache metadata\n      agent.rs    # public Agent builder\n      runner.rs   # public Runner over runtime execution\n      run_config.rs\n      model.rs\n      model_settings.rs\n      sessions.rs\n      runtime/    # agent runtime, hooks, backends, cancellation, sub-agents\n      skills/     # skill discovery, parsing, validation, activation\n      tools/      # registry, schemas, dispatcher, built-in handlers\n      workspace/  # local, memory, and S3 workspace backends\n    examples/\n    tests/\n  docs/\n```\n\nAdditional design notes live under `docs/`, especially `docs/architecture.md`\nand `docs/model-settings.md`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandersonby%2Fvv-agent-rs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandersonby%2Fvv-agent-rs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandersonby%2Fvv-agent-rs/lists"}