YAI Agent Core

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

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

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

这是什么

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

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

适合谁 / 不适合谁

和你听过的东西有何不同

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

30 秒跑起来

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

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

路线 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 是逐行讲解。

核心能力

两种用法

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），不随学习顺序重排，以便与各版材料、讲义路径一致。

在线 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 / 授权闸、子进程教学沙箱、灵动岛员工薄壳
• v1.0（规划中）：作为 AI Companion 项目 AMBRACE 的 Agent 内核回流嵌入

许可证

MIT · Gi-Tuu