内容
# botnesia-core
**BotNesia 背后的开放代理运行时基础** — 使用 Python 构建持久、多代理、MCP 原生的 AI 系统。
[](https://github.com/asroryandesfar-art/botnesia-core/actions/workflows/ci.yml)
[](https://pypi.org/project/botnesia-core/)
[](https://github.com/asroryandesfar-art/botnesia-core/releases)
[](LICENSE)
**🌐 线上产品：** [app.botnesia.uk](https://app.botnesia.uk) · **🎬 演示：** [YouTube](https://youtu.be/aNIVa4Q-okI)
> `botnesia-core` 是从 BotNesia 平台中提取的 Apache-2.0 引擎。
> 商业产品（计费、市场、定价、AI 工作流代理、多租户管理、SSO）保留在 **BotNesia Cloud** 中 — 此仓库是可重用的核心，您可以在此基础上构建。
## 在生产环境中查看
[](https://app.botnesia.uk)
*BotNesia 直播产品 ([app.botnesia.uk](https://app.botnesia.uk)) 运行在此引擎上 — 一个 Supervisor 代理，协调 CS、销售、营销、知识、财务和人力资源代理，跨越 WhatsApp、Instagram、Telegram 和网页聊天。*
---
## 问题
构建真正的 AI 代理意味着每次都需要解决相同的难题：
持久性（重启、重试）、多代理路由、工具/插件集成、提供商故障转移和成本控制、内存和安全的外联调用。
大多数开放的代理框架在“循环中的提示”上停止，并将生产环境的基础设施留给您。
`botnesia-core` 提供了这些基础设施 — 与 BotNesia 产品相同的引擎 — 作为一个干净的、无商业化的库。
## 什么是 BotNesia？
BotNesia 是一个 **AI 工作流平台**：它将业务对话和操作转换为由合作的 AI 代理团队完成的工作。
`botnesia-core` 开源了实现此功能的基本组件 — 代理 SDK、持久运行时、共享状态和内存、工具/MCP 插件层、提供商路由、RAG、推理组件和工作流引擎。
> **开放核心：** 该库是引擎；托管的 **BotNesia Cloud** 添加了商业层（计费、市场、AI 工作流代理、租户管理、SSO）。
> 在 BotNesia 产品网站上了解更多。
## 为什么它与众不同
- **持久，而不仅仅是一个包装。** 基于 Postgres 的任务运行时，带有重试/DLQ — 代理在重启后存活，与演示的提示循环不同。
- **MCP 原生插件。** 通过一个环境变量添加工具，只需指向任何 MCP 服务器 — 无需更改代码。
- **多代理设计。** 注册表 + 编排器在实现 `run()` 的代理之间路由工作。
- **提供商无关 + 成本感知。** `SmartModelRouter` 跨 DeepSeek/Gemini/Groq/OpenRouter，具有任务类路由。
- **电池，而不是锁定。** 共享状态（进程内或 Redis）、长期内存、策略引擎、提示注册表、评估、RAG — 所有这些都是独立的模块。
- **无商业代码和可审计。** 零秘密，零计费/定价/租户代码。
## 比较
| | 提示循环脚本 | 典型的代理框架 | **botnesia-core** |
|---|:---:|:---:|:---:|
| 持久运行时（重试/DLQ，重启后存活） | ❌ | 部分 | ✅ |
| 多代理注册表 + 编排器 | ❌ | ✅ | ✅ |
| MCP 原生插件（通过 env 添加工具） | ❌ | 各不相同 | ✅ |
| 共享状态（进程内 **或** Redis） | ❌ | ❌ | ✅ |
| 成本感知的提供商路由 | ❌ | ❌ | ✅ |
| SSRF 防护的工具获取 | ❌ | ❌ | ✅ |
| 从实时生产产品中提取 | ❌ | 罕见 | ✅ |
*不是基准测试 — 功能比较，比较的是已有的功能。*
## 安装
```bash
pip install botnesia-core
# 或从源代码：
git clone https://github.com/asroryandesfar-art/botnesia-core
cd botnesia-core && pip install -e ".[dev]"
```
可选附加功能：`pip install "botnesia-core[redis]"`（分布式状态）。
## 快速入门（5 分钟）
<!-- 演示：用 assets/demo.gif 替换，一旦录制完成（参见 assets/README.md） -->
> 🎬 **演示：** 60–90 秒的快速入门录制将位于 `assets/demo.gif`。
```python
import asyncio
from base import BaseAgent
class GreeterAgent(BaseAgent):
name = "greeter"
skills = ["greet"]
async def run(self, context: dict) -> dict:
return {"output": f"你好 {context.get('name', '世界')}!"}
print(asyncio.run(GreeterAgent(api_key=None).run({"name": "Sari"})))
# {'output': '你好 Sari!'}
```
然后探索可运行的示例：
```bash
python examples/01_list_builtin_tools.py # 检查工具注册表
python examples/02_mcp_plugin_config.py # 通过 MCP 插件添加工具
python examples/03_define_workflow.py # 渲染工作流步骤
```
## 示例：LLM 支持的代理
```python
from base import BaseAgent
class SummarizerAgent(BaseAgent):
name = "summarizer"
async def run(self, context: dict) -> dict:
text = context["text"]
# BaseAgent 提供多提供商 LLM 管道（自带密钥）：
summary = await self._call_llm(
system="用一句话总结用户的文本。",
user=text,
)
return {"summary": summary}
```
使用编排器（`multi_agent_orchestrator`）路由到多个代理，并使用 `task_runtime` 持久运行它们。
## 架构
`botnesia-core` 是一组独立的可导入模块。
您的应用程序（或 BotNesia Cloud）位于其上，注册其自己的代理/工具，并添加商业层。
完整指南：[`docs/SDK_GUIDE.md`](docs/SDK_GUIDE.md)。
## BotNesia × Casper — 可验证的 AI 决策
AI 代理越来越多地采取影响资金和客户的行动。
BotNesia 将“信任 AI”转变为“验证 AI”，通过将每次重要代理决策的哈希值锚定在链上。
- **链上证明：** BotNesia 产品将决策哈希值锚定到 **Casper Testnet** (`casper-test`) 上的 `ai_proof_registry` 智能合约，通过 `store_proof` 入口。
每个锚定决策都会产生一个 Casper 部署，任何人都可以独立验证区块链浏览器。
- **真实、可验证的引用：**
- 合约哈希 — `15009cd4a6489c904b699c0a1f292e7e5557e823e54c236539c9ce9973ee2323`
- [测试网上的合约包](https://testnet.cspr.live/contract-package/897c4bd670325c1f17ab1704633a470f55eeeb1ec2b357ef48e5d26ecb78a9f0)
- 示例确认部署 — [`fbb4b7e7…aa7b4e`](https://testnet.cspr.live/deploy/fbb4b7e766c0275980074d070d446d8e64703c2c2eb81be84637dfa531aa7b4e)
- **为什么选择 Casper：** 可预测的费用和可升级的合约适用于每个决策的锚定工作负载，其浏览器使证明易于验证。
> 范围说明：Casper 锚定客户端和合约在 **BotNesia 产品** 中运行（不在此开放运行时包中）。
> 本节记录了平台如何使用 Casper；`botnesia-core` 是运行这些决策的代理引擎。
## 插件
插件系统是 **MCP** + 工具注册表。指向任何 MCP 服务器：
```python
import os, json, mcp_registry
os.environ["MCP_SERVERS"] = json.dumps({"github": {"url": "https://mcp.example.com/github"}})
registry = mcp_registry.configure_from_env() # 工具作为 mcp__github__* 出现
```
参见 [`docs/PLUGIN_GUIDE.md`](docs/PLUGIN_GUIDE.md)。
## 工作流
使用 `workflow_engine` 定义多步骤自动化（代理 → 操作 → 通知）；支持模板字段 (`{{agent_output}}`) 和条件节点。
参见 `examples/03_define_workflow.py`。
## 路线图
- **0.1.x** — 稳定基元、PyPI、CI、指南。
- **0.2.x** — 入口点插件发现、可注入提供商/可观察性钩子。
- **→ 1.0** — API 稳定性保证、参考部署、插件画廊。
完整路线图：[`ROADMAP.md`](ROADMAP.md)。
## 常见问题
**这是整个 BotNesia 产品吗？**
不，它是开放引擎。计费、市场、定价、AI 工作流代理、租户管理和 SSO 保留在商业 BotNesia Cloud 中。
**我需要数据库或 Redis 吗？**
不需要 SDK 基础知识。`task_runtime` 使用 Postgres 进行持久作业，`platform_state` 可以使用 Redis 进行分布式状态 — 两者都是可选的。
默认状态后端是进程内状态。
**支持哪些 LLM 提供商？**
通过 `SmartModelRouter` 支持 DeepSeek、Gemini、Groq 和 OpenRouter。带上您自己的 API 密钥；路由按任务类别进行成本感知。
**如何添加工具或集成？**
通过 `MCP_SERVERS` 环境变量指向 MCP 服务器（无需代码），或注册自定义工具。
参见 [`docs/PLUGIN_GUIDE.md`](docs/PLUGIN_GUIDE.md)。
**它是否已准备好投入生产？**
基本组件是从生产系统提取的，并受到测试的保护。
在 1.0 之前，API 可能会调整（参见 `CHANGELOG.md` / `SUPPORTED_VERSIONS.md`）。
**支持哪些 Python 版本？**
3.10+（CI 运行 3.10–3.12）。
## 贡献和社区
问题和 PR 欢迎 — 参见 [`CONTRIBUTING.md`](CONTRIBUTING.md)、
[`GOVERNANCE.md`](GOVERNANCE.md) 和 [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md)。
安全：[`SECURITY.md`](SECURITY.md)。
## 许可证
[Apache-2.0](LICENSE) © BotNesia. 参见 [`NOTICE`](NOTICE)。
