内容
<p align="center">
<img src="docs/public/protoagent-banner.png" alt="protoAgent" width="100%">
</p>
# protoAgent
[](https://github.com/protoLabsAI/protoAgent/actions/workflows/checks.yml)
[](./LICENSE)
[](https://agent.protolabs.studio/docs/)
[](https://github.com/new?template_name=protoAgent&template_owner=protoLabsAI)
一款轻量、适用于A2A原生的LangGraph代理 —— 核心体积小，可通过git-URL插件扩展。
运行单个代理或编排一个集群；可以通过控制台、兼容OpenAI的API或A2A驱动。
本地优先，您可以fork。
它处理枯燥的部分 — A2A规范处理、成本/扩展发射、跟踪、发布管道 — 在舰队中的每个代理都保持稳定，
因此fork一个代理几乎等同于重写`SOUL.md`、`graph/prompts.py`和`tools/lg_tools.py`，而无需其他操作。
您可以通过插件添加功能，而不是继承一大堆功能。
**规范参考实现**：[protoLabsAI/roxy](https://github.com/protoLabsAI/roxy)。
Roxy是一个填充完整的fork — 一个自主的ProtoMaker投资组合管理器，带有自己的个性、A2A技能和项目注册表 —
一个关于fork实际效果的良好示例。
**5分钟试用：** 克隆，`uv sync && uv run python -m server`
（或`pip install -r requirements.txt && python -m server`），打开
<http://localhost:7870>，并浏览安装向导 —
无需fork，无需`sed`，无需Docker即可启动您的第一个代理。
参见[第一个代理教程](./docs/tutorials/first-agent.md)。
**当您准备好发布自己的代理时：** 点击GitHub仓库顶部的 **"使用此模板"**，
然后按照[自定义和部署](./docs/guides/customize-and-deploy.md)进行fork/重命名/发布管道的连接。
## 默认情况下，您可以获得以下内容
| 问题 | 所在位置 | 功能 |
|---|---|---|
| A2A服务器 | `server/a2a.py`，`a2a_impl/executor.py` | `/a2a`上的JSON-RPC 2.0，SSE流式传输，`tasks/*`生命周期，推送通知，众所周知的代理卡，双令牌形状解析 |
| 代理运行时 | `graph/agent.py`，`server/` | LangGraph `create_agent()`连接到A2A处理器，带有用于成本-v1的流式令牌捕获 |
| LLM网关 | `graph/llm.py` | 兼容OpenAI的客户端指向LiteLLM — 通过编辑网关配置而不是fork来交换模型 |
| 子代理 | `graph/subagents/config.py` | 通过`task()`工具进行DeerFlow模式委托；一个可用的示例代理 — 一个`researcher`（网页 + 内存，计划→搜索→合成→引用） |
| 委托给其他代理 | `plugins/delegates/`，`plugins/coding_agent/` | **`delegate_to`** 将子任务路由到另一个代理或端点，通过 **a2a / openai / acp** — 一个**内置**注册表，在控制台中管理和热交换（**工作区设置 ▸ 委托**），带有健康探测器。 `acp`类型通过代理客户端协议（ACP）生成一个CLI编码代理（例如protoCLI）。参见[委托](./docs/guides/delegates.md)，[启动CLI编码代理](./docs/guides/coding-agents.md)，ADR [0024](./docs/adr/0024-spawn-cli-coding-agents-acp.md) / [0025](./docs/adr/0025-unified-delegate-registry-and-panel.md) |
| 启动工具 | `tools/lg_tools.py` | 默认启用：4个无密钥常规工具（`current_time`，`calculator`安全AST评估，`web_search`通过DuckDuckGo，`fetch_url`）+ 2个HITL（`ask_human`，`request_user_input`）+ 3个管理工具（`recent_activity`/`list_skills`/`save_skill`）+ 3个目标工具（`set_goal`/`update_goal_plan`/`abandon_goal`）+ 3个监视工具（`create_watch`/`list_watches`/`clear_watch`），另外 — 当存在其存储时 — 4个内存 + 3个调度器 + 4个任务 + 1个收件箱。 **不**在`get_all_tools`中：注释/文档工具（默认启用插件），`delegate_to`（内置`delegates`插件），GitHub读取工具（选择加入`github`插件）。通过`tools.disabled`删除任意工具；通过插件添加。参见[启动工具](./docs/reference/starter-tools.md) |
| 文件GitHub问题 | `tools/gh_issue.py` | **`/issue`** — 用户专用聊天命令 **和** 🐛实用工具栏表单对话框，通过`gh`CLI提交GitHub问题，搭建并强制执行所需部分，因此它通过存储库的问题门槛。 **不**是代理工具 — 创建问题仍然由您负责（`github`插件的GitHub工具是只读的）。存储库是快速切换列表，在**设置 ▸ 系统 ▸ GitHub**下配置（`github.repos` + `github.default_repo`），与投资组合管理器的多个存储库设置配对。参见[文件GitHub问题](./docs/guides/file-github-issues.md) |
| 知识存储 | `knowledge/store.py`，`knowledge/hybrid_store.py`，`ingestion/` | 默认情况下为sqlite + FTS5关键字搜索；可选的**混合**存储添加嵌入 + RRF融合，以及**摄取管道**从txt/md/html/pdf/web/YouTube/音频/视频源中提取。 一个`chunks`表用于操作员注释和对话发现。 默认启用；通过`middleware.knowledge: false`关闭 |
| 可扩展性 | `graph/skills/`，`tools/mcp_tools.py`，`graph/plugins/`，`plugins/` | 选择加入扩展运行中的代理而无需fork的方式： **`SKILL.md`**技能（AgentSkills格式，按需加载），**MCP服务器**（通过stdio/HTTP的外部工具），以及**插件** — 插件包添加工具，技能，子代理，工作流，FastAPI路由，背景曲面，受控MCP服务器，**控制台轨道视图**，及其自己的配置/秘密/设置。插件**可从git URL安装**（`protoagent plugin install <url>`，在`plugins.lock`中固定）并作为存储库共享 — 存储库是一个完整的捆绑包。 一流的**Telegram** (`plugins/telegram`)集成随附；**Discord**，**Slack**和**Google** Gmail/日历作为外部插件从其自己的存储库安装。 参见[技能](./docs/guides/skills.md)，[MCP](./docs/guides/mcp.md)，[插件](./docs/guides/plugins.md)，[插件控制台视图](./docs/guides/plugin-views.md)，[安装和发布插件](./docs/guides/plugin-registry.md)，ADR [0001](./docs/adr/0001-extensibility-and-plugin-architecture.md) / [0018](./docs/adr/0018-plugin-surfaces-routes-subagents.md) / [0019](./docs/adr/0019-plugin-config-settings-secrets.md) / [0026](./docs/adr/0026-plugin-contributed-console-surfaces.md) / [0027](./docs/adr/0027-install-plugins-from-git-url.md) |
| 媒体输出通道 | `infra/media.py`，`server/media.py`，`graph/multimodal.py` | 工具生成的二进制工件，双向：`registry.save_media()`将图像/音频/视频持久化到核心存储中，通过一个`GET /media/<file>`路由提供服务（每个文件HMAC签名URL在聊天中内联渲染，甚至在持有者门槛下）。 `multimodal_tool_result()`允许工具返回一个**视觉模型实际看到的**图像作为ToolMessage内容块（文本模型降级到标题/描述路径）。 参见[插件 ▸ 更深入地挖掘核心](./docs/guides/plugins.md#consumption-sdk)（#1929/#1930） |
| 调度器 | `scheduler/` | `schedule_task` / `list_schedules` / `cancel_schedule`工具由捆绑的sqlite调度器支持。 多代理安全 — 每个作业都由`AGENT_NAME`命名空间。 参见[安排未来工作](./docs/guides/scheduler.md) |
| 评估框架 | `evals/` | 副作用验证A2A测试框架 — 审计日志 + 回复文本 + 知识库状态。 `python -m evals.runner`针对正在运行的代理。 参见[评估您的fork](./docs/guides/evals.md) |
| 跟踪 | `observability/tracing.py` | Langfuse `trace_session`带有分布式`a2a.trace`传播和OTel跨上下文分离过滤器 |
| 可观察性 | `observability/metrics.py`，`observability/audit.py` | Prometheus指标，带有每个代理前缀的JSONL审计日志和跟踪ID |
| 输出协议 | `graph/output_format.py` | `<scratch_pad>` / `<output>`解析，以便模型可以思考而不向用户泄露 |
| UI | `apps/web/`（React控制台） | React操作员控制台（默认 `--ui console`层 + Tauri桌面应用程序）通过REST/A2A API — 实时令牌流式传输，导航中的聊天连续性（+中断流自愈），插件贡献的轨道视图，以及PWA壳。 参见ADR [0010](./docs/adr/0010-headless-setup-and-ui-tiers.md) |
| 发布管道 | `.github/workflows/*.yml` | 自动语义版本控制，GHCR镜像推送，GitHub发布带有过滤的注释，可选Discord帖子 |
## 快速入门 — 从零到五分钟聊天
```bash
# 1. 获取代码（首次运行无需fork）
git clone https://github.com/protoLabsAI/protoAgent.git my-agent
cd my-agent
# 2. 安装依赖并运行 — uv（推荐）：创建venv，从pyproject.toml安装核心依赖并运行服务器。 无需环境变量。
uv sync && uv run python -m server # 核心，服务React控制台（--ui console）
# 已经同步？`uv run --no-sync python -m server`跳过重新解析。
# 2b. 或使用pip — `requirements.txt`安装核心运行时：
# python -m venv .venv && source .venv/bin/activate
# pip install -r requirements.txt # == pip install -e .
# python -m server
# 3. 打开向导 — 选择您的端点，选择模型，命名代理，选择角色预设，然后启动。 控制台聊天在设置完成时出现。
open http://localhost:7870
```
[第一个代理教程](./docs/tutorials/first-agent.md)逐步介绍每个向导步骤，并附有截图。
一旦您满意并希望将其作为您自己的镜像发布到您自己的GHCR中：[自定义和部署](./docs/guides/customize-and-deploy.md)。
## 一键安装（Docker）
无需克隆，无需Python — 对于您刚刚SSH到的新盒子。 拉取发布的镜像，运行它，并浏览CLI向导（与浏览器向导使用的`/api/config/*`端点相同）以配置提供商，模型和代理名称：
```bash
curl -fsSL https://raw.githubusercontent.com/protoLabsAI/protoAgent/main/scripts/install.sh | sh
```
重新运行更新镜像（保留数据卷）并提供重新运行向导。 通过纯SSH会话工作 — 无TTY启动容器并指向控制台以完成。
## 运行无头
Web控制台是可选的 — protoAgent是一个**API优先的代理服务器**。 无头运行并通过HTTP驱动它，使用 **兼容OpenAI的** API，**A2A**协议，或两者。 同一个代理，工具，技能，内存和目标 — 无需浏览器。
```bash
python -m server --ui none --host 0.0.0.0 # API + A2A + /metrics, 无UI
# 兼容OpenAI — 将任何OpenAI客户端指向基准URL：
curl localhost:7870/v1/chat/completions -H "Authorization: Bearer $TOKEN" \
-d '{"messages":[{"role":"user","content":"hi"}]}'
# A2A — 代理卡 + JSON-RPC端点其他代理/集群调用：
curl localhost:7870/.well-known/agent-card.json
```
`--ui`层：`console`（React + API，默认）· `none`（无头）。 `full`是`console`的废弃别名。 参见[运行无头](./docs/guides/headless.md)。
## 架构
```
┌──────────────┐ A2A JSON-RPC + SSE ┌─────────────────┐
│ Consumer │ ──────────────────────────▶ │ A2A处理器 │
│ （任意A2A │ │ （FastAPI） │
│ 客户端） │ ◀──── 成本-v1 数据部分 ─────│ │
└──────────────┘ └────────┬────────┘
│
▼
┌─────────────────┐
│ graph/agent.py │
│ （LangGraph │
│ create_agent） │
└────────┬────────┘
│
▼
┌─────────────────┐
│ LiteLLM │ ← 模型选择
│ 网关 │ 生活在这里，
└─────────────────┘ 不在代码中
```
A2A处理器直接不与LLM通信 — 它向LangGraph运行时提交消息，
LangGraph运行时拥有工具循环，子代理`task()`委托和结构化输出协议。
## 插件
插件是一个**插件包** — 一个带有`protoagent.plugin.yaml`清单的存储库 —
**在不fork的情况下扩展正在运行的代理：** 工具，`SKILL.md`技能，子代理，
工作流，FastAPI路由，背景曲面，受控MCP服务器，**控制台轨道视图**，
及其自己的配置/秘密/设置。 从git URL安装一个：
```bash
python -m server plugin install https://github.com/you/your-plugin # 固定在plugins.lock中
python -m server plugin uninstall your-plugin --purge # 删除代码，配置 + 秘密
```
**浏览目录 → [agent.protolabs.studio/plugins](https://agent.protolabs.studio/plugins)
一流插件在`plugins/`中提供 — `delegates`是内置的，`notes`，`docs`，
`artifact`和`craft`默认启用，其余是选择加入（通过`plugins.enabled`启用）：
| 插件 | 添加 | 功能 |
| --- | --- | --- |
| [`delegates`](./plugins/delegates/) | 工具 · 设置 | **内置** — `delegate_to`通过a2a / openai / acp，管理Workspace ▸ Delegates |
| [`notes`](./plugins/notes/) | 工具 · 视图 | **默认启用** — 一个共享的markdown笔记，代理和操作员都读写 |
| [`docs`](./plugins/docs/) | 工具 · 视图 · 技能 | **默认启用** — protoAgent自己的文档的离线搜索 |
| [`artifact`](./plugins/artifact/) | 工具 · 视图 · 技能 | **默认启用** — 生成式UI；`show_artifact`渲染图表，图表，Mermaid，Markdown或实时React到一个沙盒面板（[ADR 0038](./docs/adr/0038-generative-ui-artifacts-two-mode.md)) |
| [`craft`](./plugins/craft/) | 技能 · 子代理 | **默认启用** — 工程仪式作为用户专用斜杠命令（/grill，/standup，/code-review，/writing-skills）+ `skill_writer`子代理；仅限提示 |
| [`plugin-devkit`](./plugins/plugin-devkit/) | 工具 · 子代理 · 技能 · 工作流 · 视图 | 编写工具 + 参考插件 — 代理可以搭建并构建自己的插件 |
| [`workflows`](./plugins/workflows/) | 工具 | 声明式多步骤子代理工作流（DAG配方） |
| [`telegram`](./plugins/telegram/) | 曲面 | 运行代理作为Telegram机器人 — 参考 [通信插件](./docs/guides/communication-plugins.md) |
| [`github`](./plugins/github/) | 工具 | 通过`gh`CLI的只读GitHub工具 |
| [`hello`](./plugins/hello/) | 工具 · 技能 · 视图 | 极简示例 — 复制它以开始您自己的 |
| 通信插件（Discord，Telegram，Slack，...）共享一个契约 — 实现一个
小`ChatAdapter`（连接/接收/发送）+ 清单，管理员门控，
每个对话线程，回复块，生命周期和测试按钮都为您处理。
参见[构建通信插件](./docs/guides/communication-plugins.md)
([ADR 0029](./docs/adr/0029-communication-plugins-standard.md))。
**发布您自己的：** 给您的存储库打上 [`protoagent-plugin`](https://github.com/topics/protoagent-plugin)
GitHub主题标签，然后打开一个PR将其添加到 [`plugins.json`](./sites/marketing/data/plugins.json)
中列出的目录中。参见[安装和发布插件](./docs/guides/plugin-registry.md)，
[插件](./docs/guides/plugins.md)，[控制台视图](./docs/guides/plugin-views.md)。
## 默认情况下启用的A2A扩展
| URI | 在卡上声明 | 在运行时发出 |
|---|---|---|
| `cost-v1` (`https://proto-labs.ai/a2a/ext/cost-v1`) | 是 | 是 — 每个终端任务都带有包含令牌使用情况 + `durationMs`的cost-v1 DataPart |
| `confidence-v1` (`https://proto-labs.ai/a2a/ext/confidence-v1`) | 是 | 当模型自我报告一个`<confidence>`标签时 — 带有分数（ `[0,1]`），可选说明和`success`的confidence-v1 DataPart |
| `a2a.trace`传播 | 否（它是一个协议约定，而不是卡扩展） | 是 — 从`params.metadata["a2a.trace"]`读取调用者的Langfuse跟踪上下文，并将此代理的跟踪嵌套在其下 |
## 推送通知支持
A2A处理器支持A2A规范允许的两种令牌形状：
```jsonc
// 形状 1 — 顶级（@a2a-js/sdk 默认序列化）
{ "url": "https://consumer/callback/abc", "token": "shared-secret" }
// 形状 2 — 结构化（RFC-8821 身份验证信息）
{
"url": "https://consumer/callback/abc",
"authentication": { "schemes": ["Bearer"], "credentials": "shared-secret" }
}
```
两种方式都能在输出的webhook上生成 `Authorization: Bearer shared-secret`。
如果您的fork收到401回调，请检查消费者发送哪种格式 —
双令牌解析器在`a2a_impl/auth.py`中读取两者，测试套件涵盖两者。
```
## 可观察性
| 内容 | 位置 | 使用方法 |
|---|---|---|
| Prometheus 指标 | `/metrics` | 抓取；指标前缀为 `AGENT_NAME_*`（已净化） |
| JSONL 审计日志 | `/sandbox/audit/audit.jsonl` | 使用 `jq` 进行取证重放；每条记录都有 `trace_id` |
| Langfuse 跟踪 | `LANGFUSE_*` 环境变量 | 跟踪标签为 `AGENT_NAME`，因此可以通过标签筛选找到此代理的运行 |
| 容器日志 | `docker logs <container>` | INFO 是默认级别 — 设置 `LOG_LEVEL=DEBUG` 以获取更多信息 |
## 发布流程
包含的 GitHub Actions 工作流是可选的，但具有一定的约束性。
- **每次合并到 `main` 分支** → `docker-publish.yml` 构建并推送 `ghcr.io/protolabsai/<image>:latest` + `sha-<short>`。Watchtower（或类似工具）可以轮询 `latest` 以实现自动部署。
- **创建发布版本** → 手动运行 `prepare-release.yml`（`workflow_dispatch`，受 `RELEASE_ENABLED` 仓库变量控制，带有补丁/次要/主要版本输入）。它 **仅打开** 一个 "chore: release vX.Y.Z" 的版本更新 PR（fleet 政策：它 **不** 自动合并或标记）。通过正常的 CI/审查门户合并该 PR，然后手动推送标签（`git tag -a vX.Y.Z -m … && git push origin vX.Y.Z`）— 标签推送会触发 `release.yml`。发布版本按需创建，而不是每次合并。
- **当 semver 标签生效时** → `release.yml` 构建并推送稳定的 semver Docker 标签，创建 GitHub 发布版本，附带筛选的注释，并通过共享的 [`protoLabsAI/release-tools`](https://github.com/protoLabsAI/release-tools) Action 发布 Discord 嵌入。
- **每次 PR + 推送** → `checks.yml` 运行检查：ruff + 导入合约、`pytest`、A2A 实时冒烟测试、Web E2E 冒烟测试（vitest + Playwright）、gitleaks 和 `verify-workspace-config`（fleet `.beads`/`.automaker`/owned-runner 标准），因此可以在 CI 中捕获漂移，而不是在运行时。
所有工作流都在组织拥有的 `namespace-profile-protolabs-linux` 运行器上运行。三个发布工作流（`docker-publish`、`prepare-release`、`release`）都依赖于 `github.repository == 'protoLabsAI/<name>'`，因此在所有者未更新的克隆仓库上，它们不会执行 — 避免在分叉仓库上意外发布。
## 要求
- Python 3.11+（CI 运行 3.12）
- Docker（用于捆绑部署）
- 网络上某个位置的 LiteLLM 兼容的 OpenAI 网关（参见 `config/langgraph-config.yaml`）
- 可选：Langfuse、Prometheus、Discord webhook
## 技能循环 — 从经验中学习的代理
protoAgent 包含一个端到端的 **技能循环**。作为 [`SKILL.md`](./docs/guides/skills.md) 文件夹投入的**人为编写的技能**，在代理的上下文中列出，作为一个始终开启的 `<available_skills>` 索引（名称 + 摘要）；代理通过 `load_skill` 工具**按需加载技能的完整过程**，当它判断某个技能适合任务时（[渐进式披露，ADR 0060](./docs/adr/0060-skill-progressive-disclosure.md)）。代理还可以**从已证明的工作流中编写自己的技能**，通过 `/distill`（它会编写一个新的 `SKILL.md`），而技能管理者会定期重复、衰减和修剪非固定的技能。
| 组件 | 位置 | 功能 |
|---|---|---|
| `SKILL.md` 技能 | `config/skills/`、`<config>/skills/`、插件 | 人为编写的技能（AgentSkills 格式），在启动时加载到索引中（`source=disk`）。也是代理自我编写技能的方式，通过 `/distill`。参见 [技能](./docs/guides/skills.md) |
| 技能索引 | `/sandbox/skills.db`（→ `~/.protoagent`） | SQLite（FTS5）存储已加载的技能，由 `KnowledgeMiddleware` 读取 |
| 技能索引注入 | `graph/middleware/knowledge.py` | 将索引（名称 + 摘要）列为始终开启的 `<available_skills>` 块；代理通过 `load_skill` 按需拉取技能的完整内容（[ADR 0060](./docs/adr/0060-skill-progressive-disclosure.md)） |
| 技能管理者 | `graph/skills/curator.py` | 定期代理，重复、衰减和修剪非固定的技能（磁盘技能是固定的） |
### 运行管理者
```bash
# 干运行 — 查看在不修改索引的情况下会发生什么
python -m graph.skills.curator --dry-run
# 完整管理运行（重复、衰减、修剪；写入审计轨迹）
python -m graph.skills.curator
```
管理者应用 **90 天置信度半衰期**（每 90 天未使用，置信度减半），通过相似性聚类近似重复的技能，并保留最高置信度的副本，并修剪任何置信度低于 0.2 的非固定技能（磁盘 `SKILL.md` 技能是固定的）。
参见 [技能指南](./docs/guides/skills.md) 和 [架构 § 技能循环](./docs/explanation/architecture.md)，了解详细信息。
## 贡献
这是一个模板仓库 — 共享运行时（`server/` 包、`graph/agent.py`、扩展支持、发布流程）的错误和改进都发生在这里。特定于领域的代理逻辑存在于分叉仓库中，而不是这里。
## 许可证
protoAgent 在 [MIT License](./LICENSE) 下发布 — 分叉、构建、发布。捆绑的第三方插件具有自己的 `LICENSE`（也是 MIT）。
连接信息
猜你喜欢
暂无推荐服务器