krow-agent-sdk 0.8.12

Krow Agent SDK — extend the Krow agent engine with custom plugins, ACTs, tools, hints, gates and more.

krow-agent-sdk

让外部团队基于 Krow Agent 引擎扩展垂直场景应用，无需修改 Krow 主仓。

安装

pip install krow-agent-sdk              # 最小核心（13 项依赖）
pip install "krow-agent-sdk[office]"    # +24 项 docx/pptx/excel/pdf/Pillow 等
pip install "krow-agent-sdk[knowledge]" # +4 项 networkx/jieba 等
pip install "krow-agent-sdk[remote]"    # +8 项 fastapi/uvicorn/websockets 等
pip install "krow-agent-sdk[all]"       # 一站式全装

当前发布状态（2026-05-14）：M1-M4 工程实现 ✅ 全部完成（PR #235 / #265 / #279 / #281）， 但正式上 PyPI 仍待商业流程定稿（详 roadmap.md Step 2）。 现阶段外部用户走 monorepo 路径：pip install -e ".[sdk]"，或用 dev wheel：

python -m build --wheel packages/krow-agent-sdk
pip install packages/krow-agent-sdk/dist/krow_agent_sdk-*.whl

详细路线 → 设计文档 §5。

5 分钟上手

from krow_agent_sdk import AgentBuilder

agent = (
    AgentBuilder()
    .with_krow_api_key("sk-...")                # Krow Cloud API key（任何 sk- 前缀 + ≥20 字符；推荐 sk-user-）
    .with_project_root("/path/to/your/project") # 项目根（agent 写文件的边界）
    .with_chat_model("qwen3.6-plus")            # chat 类别（可选；6 类按需指定）
    .with_vision_model("qwen2.5-vl-72b-instruct")  # vision (VLM) 类别（可选）
    .build()
)

result = agent.run("帮我把 docs/ 下的 5 篇论文整理成 PPT")
print(result.final_output)  # AgentV3Result 顶层的最终输出文本
agent.shutdown()

流式输出（实时事件 + 最终结果）

for item in agent.run_stream("帮我把 docs/ 下的 5 篇论文整理成 PPT"):
    if item.kind == "event":
        print(f"[{item.event.type}] {item.event.payload.get('summary', '')}")
    elif item.kind == "result":
        print("DONE:", item.result.final_output)
    elif item.kind == "error":
        raise item.error
agent.shutdown()

run_stream 返回 Iterator[StreamItem]，3 种 kind：event（实时事件）/ result（最终结果）/ error（后台异常）。 默认订阅 macro_react.* / progressive.* / planner.* / react.* / llm.* / agent.task_*，可用 topics= 自定义（必须含 1 个终止 topic 防 stream 永挂）。

完整文档（含所有 plugin 协议 + 真实业务范例）→ docs/sdk/quickstart.md。

能力一览

维度	说明
Plugin 协议（10+）	ACTPlugin / ToolPlugin / HintPlugin / GatePlugin / EventListenerPlugin / ObservabilityPlugin / MCPServerPlugin（form-A/B/C）/ SecurityPlugin / DomainPackPlugin / VisualAdapter
AgentBuilder API	.with_krow_api_key / .with_project_root / 6 个 .with_<category>_model（chat / reasoning / vision / image_gen / image_edit / text_encoder）/ .with_replay_store / .with_*_plugin 等链式构造
Agent 执行 API	agent.run(...) 阻塞同步 / agent.run_stream(...) 流式 yield 事件 / agent.event_bus.subscribe(...) 自定义订阅
LLM Record/Replay	krow_agent_sdk.replay.LLMReplayStore 让 plugin 测试零网络成本
诊断 / Read-only API	krow_agent_sdk.data / krow_agent_sdk.diagnostics 内省 Agent 状态
Headless Docker	FROM krow-headless 直接拿到 SDK runtime

版本号

SDK 版本号 = Krow 主仓 config/version.py:get_version() 动态读取（始终一致）。 当前主线版本：0.8.x。

发布 tag 约定（参考，最终以 GitHub Releases 为准）：

• sdk-v0.8.x — 公开 SDK wheel（PyPI krow-agent-sdk）
• runtime-v0.8.x — 私有 runtime wheel（私有 index krow-agent-sdk-runtime）
• v0.8.x-lite / v0.8.x-full — 桌面应用 release（与 SDK 同步号）

详 docs/sdk/roadmap.md Step 2。

反馈

• Issues: https://github.com/aullik5/krow/issues
• 商务/SDK 接入: [e-mail]

License

Proprietary © Krow Team. All rights reserved.

正式上 PyPI 前，license 决策最终确认 — 详见 docs/sdk/EULA.md + source-protection-design.md §10。