面向希望快速构建、运行和治理多智能体服务的 Python 开发者。文章目录引言为什么要做一个多智能体 SDK什么是 SDK适合哪些场景技术架构核心功能使用方法1. 安装环境与依赖2. 创建最小 Custom Agent3. 在线体验与接口验证4. 配置模型与 API profile5. 自定义 Graph 与 ReAct6. 接入只读数据召回质量验证GitHub仓储引言为什么要做一个多智能体 SDK在我自己的日常实践中发现大语言模型让“写一个能回答问题的 Agent”变得很容易但把多个 Agent 作为长期运行的服务交付仍然会反复遇到同样的问题比如请求和结果格式不一致、流式事件难以消费、取消与超时语义模糊、会话隔离不足、工具边界不清晰以及不同团队重复搭建 HTTP 和模型适配层。写Muye Multi-Agent SDK 的目标是提供一套可组合的运行时契约。开发的人可以专注于业务 Agent、工具和领域数据SDK 负责标准化请求、结果、SSE、并发控制、上下文、模型适配和 internal Agent 通信。这样一来确定性工作流、LangGraph 状态图和 ReAct 工具调用可以共享同一套服务边界。简单来说SDK提供可靠和标准的Agent交互协议和通用功能你只需要做业务然后按需开启配置即可。什么是 SDKmuye-multi-agent-sdk是一个 Python 库不是独立的产品项目它被安装在每个 Agent 进程中帮助应用创建标准 FastAPI ASGI 服务并提供以下三种实现方式模式开发者实现适用场景CustomAgentmetadata与execute()确定性业务流程、外部系统适配GraphAgentbuild_graph()与result_from_state()有状态、可观测的 LangGraph 流程ReActAgentinstructions与langchain_tools模型根据指令自主选择工具三种模式都使用AgentRequest、AgentResult和AgentEvent。通过create_app()后服务统一暴露/health、/capabilities、/invoke、/invoke/stream和/cancel等接口是否暴露 public profile 由配置决定。适合哪些场景将已有查询、审批、推荐或工作流封装为可调用的内部 Agent。将多步业务流程构建为可取消、可观察的状态图。为 ReAct Agent 提供固定范围的检索、查询或业务工具。将多个独立 Agent 通过 internal HTTP 协议组合成主编排服务。需要向浏览器或上游服务提供稳定 SSE 事件而不希望每个项目重复实现流协议。SDK 不负责业务数据库写入、身份认证和公网接入。生产环境应由网关、认证代理、网络策略和领域服务共同完成这些边界。技术架构调用方 - Agent FastAPI 服务create_app - Custom / Graph / ReAct 模式 - ExecutionManager同会话互斥、超时、取消 - Contextmemory / SQLite / Postgres可选 - Intent Guard可选失败时 fail-open - 模型muye-llm 或 OpenAI-compatible - DataClient可信内网 muye-data可选只读HTTP transport 负责将类型化事件编码为 SSE。正常生命周期固定为session_start - thinking/tool/block/result - done - session_endpublic profile 只投影可展示的 Markdown、图表和 JSONinternal profile 才可用于可信服务之间的完整协议协作。不要把 internal 的原始数据、提示词或领域异常详情直接暴露给浏览器。核心功能统一服务契约健康检查、能力声明、同步调用、流式调用和取消请求具有一致结构。三种 Agent 模式以最小抽象覆盖确定性逻辑、状态图和工具驱动推理。SSE 事件协议事件带有会话、用户、顺序和生命周期信息调用方无需解析模型供应商的原始流。执行治理同一用户和会话互斥执行支持请求超时与精确取消。模型注入与工厂可注入 LangChain 模型也可使用muye或openai_compatible配置工厂。可选上下文默认关闭启用后支持内存、SQLite 和 Postgres checkpointer。可选意图守卫结构化识别无意义或违规输入模型依赖故障时不阻塞主流程。只读数据召回DataClient只调用muye-data的逻辑 resource alias不持有数据库凭据。注意以上的部分功能可能需要搭配muye 的其他模块进行比如muye-data、muye-llm。使用方法1. 安装环境与依赖运行环境要求 Python 3.11 或更高版本。使用已创建的虚拟环境.venv/bin/python-mpipinstallmuye-multi-agent-sdk1.1.0启用 Postgres 上下文时.venv/bin/python-mpipinstallmuye-multi-agent-sdk[postgres]1.1.0从源码开发 SDKcdsdk .venv/bin/python-mpipinstall-e.[all,dev][all,dev]面向源码开发和 CI生产应用按实际需要安装运行依赖即可。2. 创建最小 Custom Agent创建main.pyfrommuye_multi_agent_sdkimport(AgentMetadata,AgentRequest,AgentResult,CustomAgent,create_app,)classEchoAgent(CustomAgent):propertydefmetadata(self)-AgentMetadata:returnAgentMetadata(nameecho-agent,version1.0.0,description最小示例)asyncdefexecute(self,request:AgentRequest,**_kwargs:object)-AgentResult:returnAgentResult.success({markdown:f已处理{request.task}},trace_idrequest.context.trace_id,)appcreate_app(EchoAgent())启动服务.venv/bin/python-muvicorn main:app--host127.0.0.1--port80003. 在线体验与接口验证在另一个终端执行curlhttp://127.0.0.1:8000/healthcurlhttp://127.0.0.1:8000/capabilitiescurl-XPOST http://127.0.0.1:8000/invoke\-HContent-Type: application/json\-d{task:处理一条示例任务,context:{user_id:demo,session_id:demo-1}}使用curl -N调用/invoke/stream可观察 SSE。生产调用应传入稳定、非默认的user_id与session_id尤其是在启用短期上下文时。4. 配置模型与 API profileSDK 可通过环境变量配置内置muye-llm适配器MUYE_SDK_MODEL_PROVIDERmuye MUYE_SDK_MODEL_BASE_URLhttp://127.0.0.1:9850 MUYE_SDK_MODELyour-model-alias MUYE_SDK_API_PROFILESinternal,public MUYE_SDK_PUBLIC_PATH/api/v1/echo MUYE_SDK_CONTEXT_PROFILES MUYE_SDK_INTENT_GUARDfalse模型 alias 由muye-llm注册表管理API Key、数据库 URI 和其他密钥由部署环境注入不能写入源码或提交.env。若使用 OpenAI-compatible 服务改用MUYE_SDK_MODEL_PROVIDERopenai_compatible并显式配置模型、地址与密钥。5. 自定义 Graph 与 ReActexamples/graph/main.py演示了如何把StateGraph交给GraphAgentexamples/react/main.py演示了如何用 LangChaintool定义工具并在ReActAgent中返回工具列表。自定义时遵循三个边界领域校验、权限和写操作放在业务服务不交给模型决定。ReAct 工具将 resource、租户过滤和返回字段固定在应用代码中。对外公开时使用 public profile并设计 public 请求适配与输出投影。6. 接入只读数据召回DataClient面向可信内网的muye-data。ReAct 场景建议用固定作用域工具避免模型覆盖资源或过滤条件frommuye_multi_agent_sdk.toolsimportcreate_data_retrieval_tool toolcreate_data_retrieval_tool(self.data_client,resourceproduct_knowledge,pipelinehybrid,fixed_filter{op:eq,field:tenant_id,value:tenant-1},return_fields[title,source_url],)SDK 不直接连接 Milvus、OpenSearch 或其他数据库也不提供写入接口。质量验证在 SDK 根目录执行.venv/bin/python-mpytest-qtests .venv/bin/python-mcompileall-qsrc examples .venv/bin/python-mbuild--wheel.GitHub仓储SDK的独立仓储https://github.com/muye-x/muye-multi-agent-sdk多Agent脚手架(基于SDK)https://github.com/muye-x/muye-multi-agent