krow-agent-sdk 0.8.12.18

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-15）：✅ 已上 PyPI 主站 — pip install krow-agent-sdk 即可装。 SDK 当前为 v0.8.x（Beta，API 稳定但持续迭代）；详细路线 → roadmap.md。

License 状态：本包受 End User License Agreement (EULA) v1.1 DRAFT 约束， 装包即同意（详见装机 site-packages 内的 LICENSE 文件全文）。EULA EFFECTIVE 版本（含真律师签字）正在 review 中， 重大变更会以 30 天提前通知方式告知现有用户。

完整公开文档 → https://github.com/aullik5/krow-sdk-docs（quickstart / plugin 协议 / EULA / roadmap）

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 协议 + 真实业务范例）→ 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 同步号）

详 roadmap.md Step 2。

反馈

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

License

Proprietary © Krow Team. All rights reserved.

License terms: see the LICENSE file in this distribution (also bundled in the wheel — python -c "import krow_agent_sdk, pathlib; print(pathlib.Path(krow_agent_sdk.__file__).parent.parent / 'krow_agent_sdk-*.dist-info' / 'licenses' / 'LICENSE')" to locate locally) and the authoritative source EULA.md. EULA is currently v1.1 DRAFT with external counsel sign-off pending; published in good faith per industry best practices + AI-assisted legal analysis. Material changes (if any) from the future EFFECTIVE version will be communicated with at least 30 days' notice.