YAI Agent Core

English · 简体中文

给每个软件，一颗会思考的心脏。

进程内嵌入式、自适应的 Agent 内核 —— Agent 世界的 SQLite。
不必部署一个智能体平台，也不必写 Agent Loop / Planner / 工具选择代码：把内核 import
进你已有的软件，宿主只声明“我有什么能力”，Core 自动发现能力、选策略、调工具、完成任务。

一个浮窗，就是一个数字员工。 对话为主体，思考链与工具调用折叠成“过程 · N 步”； 路由、能力缺口、新工具飞入、授权卡全部由真实内核事件驱动。截图数据均为虚构。

这是什么

YAI 不是又一个聊天机器人，也不是让你照着教程拼装的 Agent 框架。它是一个跑在你软件进程里的内核：

• 你把软件里本来就存在的普通函数交给它（或接入 MCP / OpenAPI）；
• 它内省这些能力、自动生成工具规格，在收到任务时自适应地决定直接回答、调用工具、分步规划，还是向你澄清；
• 能力不足时能感知缺口、按需发现新工具，高危操作默认先请求授权——每一步都以事件对外可见。

适合谁 / 不适合谁

和你听过的东西有何不同

数据库类比：平台是云数据库控制台，框架是 ORM，YAI 是 SQLite —— 不抢主角，安静地嵌进你的程序。

30 秒跑起来

路线 A · 只装库、零 Key 验证嵌入（不必克隆、不必申请模型）。内核本体零第三方硬依赖：

pip install yai-agent-core

想尝鲜 main 上尚未发版的最新提交，再用源码安装：
pip install "yai-agent-core @ git+https://github.com/Gi-Tuu/yai-agent-core.git"

import asyncio
from yai_core import AgentCore, ScriptedModel, ModelResponse, ToolCallRequest, build_spec

def search_notes(keyword: str) -> list[str]:
    """搜索宿主笔记库。"""                # 你自己的普通业务函数，没有任何 Agent 代码
    return {"周报": ["Core 骨架", "工具调用"]}.get(keyword, [])

# 离线确定性模型（真实上线整体换成 OpenAICompatProvider）：先调工具，再给结论
model = ScriptedModel([
    ModelResponse(content="", tool_calls=[ToolCallRequest(id="c1", name="search_notes",
                 arguments={"keyword": "周报"})]),
    ModelResponse(content="本周周报 2 条。"),
])
core = AgentCore(model)
core.register_tools([build_spec(search_notes)])      # 内省 type hints / docstring 生成工具
print(asyncio.run(core.run("搜索周报并总结")).final_text)   # 本周周报 2 条。

接真实模型只需换一行（[llm] extra，OpenAI 兼容 DeepSeek / 通义 / OpenAI / Agnes）：

from yai_core import OpenAICompatProvider
model = OpenAICompatProvider()      # 读 OPENAI_API_KEY / OPENAI_BASE_URL / LLM_MODEL

用 Claude 系列则换 [anthropic] extra（同一套 ModelProvider 契约，翻译在适配器里做完）：

from yai_core import AnthropicProvider
model = AnthropicProvider()         # 读 ANTHROPIC_API_KEY / ANTHROPIC_MODEL / ANTHROPIC_STRONG_MODEL

路线 B · 克隆仓库，跑全部宿主与测试（离线，无需 Key）：

uv venv
uv pip install -e ".[dev,llm,server]"
uv run python scripts/smoke_test.py   # 同一 Core 自适应多个不同宿主
uv run pytest                         # 全量测试，不需要 API Key

第一次读代码：docs/reading-guide.md 是学习路线，docs/walkthrough/00-index.md 是逐行讲解。

核心能力

Model · Channel · Memory · Policy · Discovery · Sandbox · RouteSelector · Embedding · StorageCipher · Resource
——宿主可替换任意一个，Core 提供零配置默认实现（StorageCipher 为可选的落盘加密插槽；Resource
是文件/资源访问插槽，内核本体不碰磁盘，内置实现见 batteries/filesystem.py）。内核本体始终零第三方硬依赖。

两种用法

1）作为库嵌入（三步）

from yai_core import AgentCore, OpenAICompatProvider
import my_app_capabilities as cap                       # 宿主自己的普通业务函数

core = AgentCore.auto(cap, OpenAICompatProvider())      # ① 内省能力，自动注册工具
result = await core.run("搜索本周记录并整理成报告")        # ② 自适应 direct/react/plan/clarify
print(result.final_text)                                # ③ 可交付结果 + 全程事件

2）灵动岛员工薄壳（shell/desktop）

需要一张“脸”的宿主不必自己写交互窗口：官方薄壳提供一个常驻浮窗，Qt Quick 真原生渲染、
与各应用内置的 Core 跑在同一进程（无本地端口）。

• 三态形变：圆形球（56）→ 悬停向右展开胶囊（340×52）→ 点击向下展开员工面板（470×620），全程可拖动；
• 位置记忆：拖动后关闭重开，浮窗回到原处；
• 首次引导：球内“点我” + 紫色呼吸环，引导一次后不再出现；
• 全局快捷键：在任意软件按 Ctrl+Alt+Y 立刻呼出并展开；
• 离线 / 真实双入口：桌面快捷方式分别启动离线演示与接真实模型的员工；
• 多专员切换：一座岛管理销售 / 仓库 / 笔记 / 陪伴多个彼此隔离的专员，时间线不丢 ——
  灵动岛只做前台 / 交换机，不做超级 Agent。

uv sync --extra desktop
.\.venv\Scripts\python.exe -m shell.desktop            # 离线演示：无 Key 看全部动效
.\.venv\Scripts\python.exe -m shell.desktop --live     # 接真实模型

薄壳只做呈现与编排；shell/employee 把子员工实现为“收窄工具 + 收窄权限 + 独立上下文 + 预算”的
一次 sub-run（并行 ≤ 5、嵌套 ≤ 2、结果只回流根），内核不感知界面、也不做多 Agent 框架。

截图墙

左：软件本来的样子（六个原生视图，无 Core 也完整可用）； 右：嵌入 Core 后，能力不足时自动发现工具、首次调用仍弹授权卡（发现 ≠ 授权）。

示例（由浅入深）

目录名保留历史编号（a/c/d/e/f/g/i/j/k），不随学习顺序重排，以便与各版材料、讲义路径一致。

在线 HTTP API

线上实例：https://yai-agent-core.onrender.com（免费层冷启动约 30–90s）

GET  /health                  # {"status":"ok", ...}
GET  /v1/tools                # 当前宿主自动发现的工具清单
POST /v1/agent/run            # {"task": "..."} -> 事件流 + 最终结果

可选环境变量（持久化记忆、历史裁剪 / TTL、限流等）见 .env.example 与 docs/architecture.md。

版本路线

• v0.1 – v0.3（已完成）：函数内省、规则 / LLM 路由、Agent Loop、SPI 默认实现、MCP Client、SQLite 持久化、OpenAPI 发现、历史裁剪与限流、容器化部署
• v0.4 – v0.6（已完成）：能力缺口感知与 ToolDiscovery 闭环、host_e CRM 零改造嵌入、权限三档、组合工具、双通道语义发现、执行中动态发现
• v0.7（已完成）：自校准路由 contextual bandit（离线 +16pp）、代码工具注册 / TTL / 授权闸、子进程教学沙箱、灵动岛员工薄壳
• v0.8（已完成）：上下文摘要压缩、MCP/OpenAPI 动态发现源与多源聚合、SQLite KV TTL、Docker 沙箱适配器、API Key 鉴权 / 限流 / 响应守卫、发布 PyPI、CI 安全加固（CodeQL、OpenSSF Scorecard、mypy、覆盖率门禁）
• v0.9（已完成）：动态重规划 replan、成本·延迟感知选档 tiering（standard/strong 自动换挡 + DONE 成本汇总）；长期记忆语义召回与任务起始主动注入、落盘加密第九 SPI StorageCipher；结构化 tracing（OpenTelemetry）与 metrics / readiness、任务级预算熔断；子员工预算与全局并发闸；第三方播种五拍标准线（host_j 零改造嵌入真实记账应用 Actual Budget）
• v0.10（已完成）：治理声明随能力清单跨进程、工具硬超时 tool_timeout 与 aclose 统一收尾、Anthropic 模型后端、第十个 SPI ResourceProvider、ACC 兼容层、审批-执行-审计同源与声明式脱敏、全局限流兜底
• v0.11（已完成）：原生参数级审批（ACC 降级为互操作 shim）、risk / scope 随事件发出、资源作用域闸 filesystem_gate、PEP 563 注解解析修正
• v0.12（已完成）：八处"静默失效"安全加固、ACC 执行提示由执行器真正强制、多模态消息契约 ChatMessage.parts、能力清单 manifest_version 升 2、certifi 关键漏洞修复
• v0.13（已完成）：入参 schema 子集 4→13 个关键字、多模态三处落地（成本口径 / 能力探测 / host_k 样板）、组合工具版本仓库、跨层对抗性证据、POSIX O_NOFOLLOW 收窄竞态窗口
• v0.14（已完成，当前发布版本）：执行约束覆盖全部路径、入参校验成为所有调用的共同下限、strict_direct 严格模式、capability_health() 接入体检、可信变更预览 ChangePreview、执行收据与进程内幂等
• v0.15（候选中）：跨实例分布式限流、生产级沙箱递进、组合工具可视化编排（宿主侧）、预览 token 收窄、公网实例暴露面收口、多模态真机验证
• v1.0（规划中）：作为 AI Companion 项目 AMBRACE 的 Agent 内核回流嵌入

许可证

MIT · Gi-Tuu