内容
# 腐蚀剂
[](https://github.com/tapiocaboy/corrosive_agents/actions/workflows/ci.yml)
[](https://github.com/tapiocaboy/corrosive_agents/actions/workflows/audit.yml)
[](https://codecov.io/gh/tapiocaboy/corrosive_agents)
[](https://crates.io/crates/corrosive_agents)
[](https://docs.rs/corrosive_agents)
[](#许可证)
使用Rust构建**可验证的、交互式的人工智能代理**，由[NVIDIA Nemotron](https://build.nvidia.com)免费的大型语言模型支持。
腐蚀剂具有名称、版本和一组主动能力 — 所有这些都可以通过JSON清单加载 — 以及原生**技能**、**MCP**（模型上下文协议）服务器和**Ed25519身份**，因此任何人都可以使用公钥加密验证它。通过Tokio **REST API**、**WebSocket**或**gRPC**提供服务，并使用**Pinecone**、**Qdrant**或任何**自定义向量存储**为其提供内存。
## 功能
| | |
|---|---|
| 🏗️ **构建模式** | 流畅的`Agent::builder()…build()`构造，带有semver + 配置验证 |
| 📄 **JSON清单** | 从文件中加载名称/版本/能力/技能/MCP服务器 |
| 🔐 **可验证的身份** | Ed25519清单；`did:key` DIDs；X.509证书；密钥轮换和撤销（`TrustStore`） |
| 🧠 **NVIDIA Nemotron** | 聊天、流式传输、工具调用、嵌入 — 带有重试/回退 + 速率限制处理 |
| 🛠️ **技能** | 带有沙盒的异步JSON能力：允许列表、权限、超时、panic隔离 |
| 🔁 **工具循环** | `chat_with_tools`：模型自动调用技能；内置使用情况统计钩子 |
| 🔌 **MCP** | stdio + 可流式传输的HTTP/SSE传输；工具、资源和提示 |
| 🌐 **传输** | REST + WebSocket + gRPC，带有API密钥/JWT身份验证、TLS、优雅关闭、`/ready`、OpenAPI |
| 🤝 **A2A委托** | `RemoteAgent`对等方，带有固定密钥/DID验证；委托聊天和技能 |
| 💾 **会话** | 可插入的`SessionStore`：内存、SQLite或Redis持久性 |
| 📚 **向量存储** | 内存、Qdrant、Pinecone、pgvector；元数据过滤器、切分、`remember`/`recall` |
📖 **不熟悉该库？阅读 [教程](docs/TUTORIAL.md)** — 它从一个空项目逐步引导到一个生产就绪的代理，并作为`tutorial`模块发布在[docs.rs](https://docs.rs/corrosive_agents)上。
## 安装
```toml
[dependencies]
corrosive_agents = "0.0.1" # 默认启用REST + WebSocket
tokio = { version = "1", features = ["full"] }
```
可选功能：
```toml
corrosive_agents = { version = "0.0.1", features = ["full"] } # 所有功能
```
| 功能 | 默认 | 启用 |
| --- | --- | --- |
| `server` | ✅ | REST + WebSocket服务 + 身份验证中间件 |
| `grpc` | — | gRPC服务 + 生成的客户端（tonic） |
| `tls` | — | REST和gRPC的TLS帮助程序 |
| `openapi` | — | `/openapi.json`处的OpenAPI 3文档 |
| `x509` | — | 基于X.509证书的身份 |
| `pinecone` | — | Pinecone向量存储后端 |
| `qdrant` | — | Qdrant向量存储后端 |
| `pgvector` | — | PostgreSQL/pgvector向量存储后端 |
| `sqlite-sessions` | — | SQLite持久化对话历史 |
| `redis-sessions` | — | Redis持久化对话历史 |
| `full` | — | 以上所有功能 |
## 快速入门
在[build.nvidia.com](https://build.nvidia.com)获取免费的API密钥，并将其导出为`NVIDIA_API_KEY`。
```rust,no_run
use corrosive_agents::prelude::*;
#[tokio::main]
async fn main() -> Result<()> {
let agent = Agent::builder()
.name("research-agent")
.version("0.1.0")
.description("A concise research assistant")
.system_prompt("Answer in at most three sentences.")
.model(models::NEMOTRON_3_NANO_30B)
.capability(Capability::new("chat", "Conversational Q&A"))
.llm(NvidiaClient::from_env()?)
.generate_identity() // 清单在构建时签名
.build()?;
let reply = agent.chat("session-1", "What is NVIDIA Nemotron?").await?;
println!("{reply}");
Ok(())
}
```
### 从JSON加载代理
```json
{
"name": "manifest-agent",
"version": "1.0.0",
"model": "nvidia/llama-3.3-nemotron-super-49b-v1",
"capabilities": [{ "name": "chat", "description": "Conversational Q&A" }],
"skills": ["word_count"],
"mcp_servers": [
{ "name": "fs", "command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"] }
]
}
```
```rust,no_run
use corrosive_agents::prelude::*;
# fn skill_impl() -> FnSkill { FnSkill::new("word_count", "", |i| async move { Ok(i) }) }
# async fn run() -> Result<()> {
let agent = AgentBuilder::from_json_file("agent.json")?
.skill(skill_impl()) // 实现绑定到声明的名称
.llm(NvidiaClient::from_env()?)
.generate_identity()
.build()?;
agent.connect_mcp_servers().await?; // 启动并握手声明的MCP服务器
let tools = agent.mcp_tools("fs").await?;
# Ok(())
# }
```
### 使用公钥加密验证代理
```rust
use corrosive_agents::prelude::*;
# fn main() -> Result<()> {
let agent = Agent::builder()
.name("trusted").version("1.0.0")
.generate_identity()
.build()?;
// 将清单作为JSON发送到任何地方…
let json = agent.manifest().to_json()?;
// …任何人都可以在离线状态下验证它：
let received = AgentManifest::from_json(&json)?;
received.verify()?; // 嵌入式公钥
received.verify_with(&agent.public_key().unwrap())?; // 或固定密钥
# Ok(())
# }
```
篡改任何已签名的字段都会导致验证失败。
### 提供服务
```rust,no_run
use std::sync::Arc;
use corrosive_agents::prelude::*;
# async fn run() -> Result<()> {
# let agent = Agent::builder().name("a").version("1.0.0").build()?;
let agent = Arc::new(agent);
// REST + WebSocket（功能`server`，默认启用）
agent.clone().serve("0.0.0.0:8080".parse().unwrap()).await?;
// gRPC（功能`grpc`）
// agent.serve_grpc("0.0.0.0:50051".parse().unwrap()).await?;
# Ok(())
# }
```
REST端点：`GET /health`，`GET /agent`，`GET /agent/manifest`，
`GET /capabilities`，`GET /skills`，`POST /skills/{name}`，`POST /chat`，
`POST /verify`，以及带有可选流式传输块的WebSocket `/ws`。
gRPC服务（`proto/agent.proto`）：`GetInfo`，`Chat`，`ChatStream`
（服务器流式传输），`ExecuteSkill` — 随 crate 一起发布的生成的Rust客户端位于`corrosive_agents::grpc::pb::agent_service_client::AgentServiceClient`。
### 使用向量存储进行RAG
```rust,no_run
use corrosive_agents::prelude::*;
use serde_json::json;
# async fn run() -> Result<()> {
let nvidia = NvidiaClient::from_env()?;
let agent = Agent::builder()
.name("rag").version("0.1.0")
.llm(nvidia.clone())
.embeddings(nvidia) // NvidiaClient也支持嵌入
.vector_store(InMemoryVectorStore::new()) // 或QdrantStore / PineconeStore
.build()?;
agent.remember("Nemotron models are free at build.nvidia.com", json!({"topic": "nvidia"})).await?;
let hits = agent.recall("where are Nemotron models hosted?", 3).await?;
# Ok(())
# }
```
通过实现`VectorStore`特征（三个异步方法：`upsert`、`search`、`delete`）来使用您自己的存储。
## 示例
| 示例 | 展示 | 运行 |
| --- | --- | --- |
| `build_agent` | 构建模式、能力、技能、签名清单、聊天 | `cargo run --example build_agent` |
| `agent_from_json` | 从`examples/agent.json`加载代理 + MCP配置 | `cargo run --example agent_from_json` |
| `interactive_chat` | 带有流式传输令牌的终端REPL | `cargo run --example interactive_chat` |
| `tool_calling` | 模型自动调用技能（函数调用）+ 使用情况钩子 | `cargo run --example tool_calling` |
| `sign_and_verify` | 端到端公钥验证（离线） | `cargo run --example sign_and_verify` |
| `vector_rag` | 嵌入 + 向量存储 + 检索增强答案 | `cargo run --example vector_rag` |
| `serve` | REST + WebSocket服务器 | `cargo run --example serve` |
| `serve_grpc` | gRPC服务器 | `cargo run --example serve_grpc --features grpc` |
| `a2a_delegation` | 代理到代理的委托，带有DID固定对等验证（离线） | `cargo run --example a2a_delegation` |
所有LLM示例都需要`NVIDIA_API_KEY`（或`.env`文件中的`NVIDIA_KEY`）。
## Nemotron模型
`corrosive_agents::llm::models`中的常量，均可使用免费密钥：
- `nvidia/nemotron-3-ultra-550b-a55b`，`nvidia/nemotron-3-super-120b-a12b`，
`nvidia/nemotron-3-nano-30b-a3b`（默认）
- `nvidia/llama-3.1-nemotron-ultra-253b-v1`，`nvidia/llama-3.3-nemotron-super-49b-v1`，
`nvidia/llama-3.1-nemotron-nano-8b-v1`，`nvidia/nemotron-mini-4b-instruct`
- 嵌入：`nvidia/nv-embedqa-e5-v5`，`nvidia/llama-nemotron-embed-1b-v2`
目录不断演变 — 使用`GET https://integrate.api.nvidia.com/v1/models`列出您的密钥可以访问的模型。
## 开发
```sh
cargo test --features full # 单元测试 + 集成测试 + 文档测试
cargo clippy --all-targets --features full
cargo fmt --check
cargo deny check # 安全建议、许可证、禁止项、源码（deny.toml）
cargo llvm-cov --features full # 代码覆盖率报告
cargo run --manifest-path tools/protogen/Cargo.toml # 在编辑proto/后重新生成gRPC代码
```
## 许可证
许可方式为以下两者之一：
- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))
- MIT license ([LICENSE-MIT](LICENSE-MIT))
任选其一。
