国产大模型 Agent 开发实战：用 milu 5 分钟搭一个多用户 AI Agent 服务（DeepSeek/Qwen/Kimi/GLM）

目录

• 一、milu 是什么，解决什么问题

• 二、环境准备与安装（pip / uv / Docker）

• 三、5 分钟跑通第一个 Agent

• 四、命令行直接用：milu CLI

• 五、一行起多用户 Web 服务：milu serve

• 六、给 Agent 加自定义工具

• 七、工具安全模式（talk / manual / auto / superwork）

• 八、多用户并发：AgentPool

• 九、长期记忆与 RAG 知识库

• 十、接入 MCP 服务器

• 十一、小结与资源

---

一、milu 是什么，解决什么问题

milu 是一个开源的 Python AI Agent 框架（统一 AI 模型抽象层 + Agent 编排引擎），核心特点：

• 9 家大模型一个接口 ：通义千问 Qwen、DeepSeek、Kimi、GLM（智谱）、MiniMax、豆包，以及 OpenAI、Gemini、Claude------6 家国产大模型一等公民，一行代码切换。

• 多用户并发开箱即用 ：内置 AgentPool 资源池，解决"多用户会话互相串台"这个生产难题。

• 全家桶内置 ：20+ 工具、MCP 协议、子代理、技能、RAG 向量知识库、定时任务、四种工具安全模式，外加 milu serve 一行起多用户 Web 服务。

• 一个 pip install -U milu 全装好，MIT 协议，Python 3.10+。

适合：用国产大模型做 AI 应用、要从单用户 demo 走到多用户/多租户服务、想要开箱即用的开发者。

项目地址（GitHub）：https://github.com/stephonGAO/milu
PyPI：https://pypi.org/project/milu/

---

二、环境准备与安装

要求：Python 3.10+。

方式一：pip（已有 Python）

pip install -U milu

一个命令把 CLI、Web 服务、RAG 知识库、MCP 全装好，不用再装一堆插件。

方式二：uv（没装过 Python 也行，推荐新手）

# 先装 uv（一行，不需要 Python）

# macOS / Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows PowerShell:

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"



# 再装 milu（uv 会自动帮你拉一个 Python）

uv tool install milu

方式三：Docker（宿主机完全不装 Python）

cp .env.example .env       # 填至少一家的 API Key

docker compose up -d

配置 API Key ：milu 从环境变量 {PROVIDER}_API_KEY 读密钥，例如：

# Windows PowerShell

$env:DEEPSEEK_API_KEY="你的key"

# Linux / macOS

export DEEPSEEK_API_KEY="你的key"

各厂商对应变量：QWEN_API_KEY、DEEPSEEK_API_KEY、KIMI_API_KEY、GLM_API_KEY、MINIMAX_API_KEY、DOUBAO_API_KEY、OPENAI_API_KEY、GEMINI_API_KEY、ANTHROPIC_API_KEY。

不想手动配？直接 milu 首次运行会有交互式引导，选厂商、贴 Key 一步到位。

---

三、5 分钟跑通第一个 Agent

新建 demo.py：

import asyncio

from milu import Agent, ModelRegistry, TextDelta, AgentDone



async def main():

    # 创建 Agent，默认即完整体：内置提示词 + 20+ 工具 + 技能 + 子代理 + 会话

    agent = Agent(ModelRegistry.create("deepseek"))

    async for evt in agent.run("现在几点？用工具查一下"):

        if isinstance(evt, TextDelta):

            print(evt.text, end="", flush=True)

        elif isinstance(evt, AgentDone):

            print(f"\n[完成，共 {evt.turn_count} 轮]")



asyncio.run(main())

运行：

python demo.py

Agent(llm) 默认就是完整配置------内置系统提示词、20+ 工具、技能、三个子代理、会话持久化、上下文自动压缩全都有，传显式参数才覆盖。换模型只要改一个字符串："deepseek" → "qwen" / "kimi" / "glm" / "minimax" / "doubao" / "openai" / "gemini" / "anthropic"。

只调 LLM、不要 Agent？

import asyncio

from milu import ModelRegistry, Message, MessageRole



async def main():

    llm = ModelRegistry.create("qwen", model="qwen3.6-plus")

    async for chunk in llm.chat([Message(role=MessageRole.USER, content="你好！")]):

        if chunk.content:

            print(chunk.content, end="", flush=True)



asyncio.run(main())

---

四、命令行直接用：milu CLI

装完就有 milu 命令，不写代码也能用：

milu                 # 进入交互式对话（首次运行引导选厂商 + 填 Key）

milu setup           # 初始化引导：厂商 / API Key / 搜索后端

milu chat -p glm     # 指定厂商进入对话

milu run "总结这段话" -q     # 一次性执行，-q 只输出最终回答（可管道）

echo "翻译成英文：你好" | milu run    # 从 stdin 读指令

milu providers       # 列出 9 家厂商及 Key 配置状态

milu sessions list   # 查看历史会话

milu --lang en chat  # 切换界面语言（中 / 英双语）

milu run 支持管道，可以接进 shell 工作流里。

---

五、一行起多用户 Web 服务：milu serve

这是 milu 最能打的功能之一------一个命令起一个多用户、流式对话的 Web 服务，还自带全功能演示前端：

milu serve                          # 默认 127.0.0.1:8000

milu serve --port 9000              # 自定义端口

浏览器打开 http://127.0.0.1:8000，你会看到一个完整的单页应用：流式对话、设置面板（切厂商/模型/模式）、会话管理、定时任务、知识库管理、聊天附件上传（截图/文档）、危险工具确认弹窗。前端是纯 vanilla（无构建链、无外部 CDN），随包分发。

底层就是 AgentPool 多用户并发 + 可选嵌入式定时任务调度 + 共享 MCP，沉淀成的正规服务。

---

六、给 Agent 加自定义工具

用 @tool 装饰器，自动生成 JSON Schema：

from milu import Agent, tool



@tool(name="add", description="把两个数相加", is_safe=True)

async def add(a: int, b: int) -> int:

    """:param a: 第一个数\n:param b: 第二个数"""

    return a + b



agent = Agent(llm, tools=[add])    # 显式传 tools 会覆盖内置工具

is_safe=False 的工具会走当前安全模式：被 AI 判定、或人工确认、或拦截（见下一节）。

---

七、工具安全模式（talk / manual / auto / superwork）

Agent 能调 shell、写文件、跑 Python 时，安全就成了真问题。milu 给了四种模式：

agent = Agent(llm, mode="manual")   # 不安全工具等人工审批

agent.set_mode("talk")              # 只读：不安全工具一律拦截

| 模式 | 行为 |

|---|---|

| talk | 只读，所有不安全工具调用被拦, 适合纯RAG项目例如智能客服 |

| manual | 安全工具直接跑；不安全工具产出确认事件、等审批 |

| auto（默认） | 自主决策；不安全调用交 AI 安全判定器三态裁决（放行 / 转确认 / 拒绝） |

| superwork | 全权限，跳过一切检查（只对完全可信任务用） |

子代理会继承父级模式和确认回调------委派不构成安全旁路。

---

八、多用户并发：AgentPool

要做"多人同时用"的服务，核心就是它。Agent 含实例级状态，多用户不能共享同一个 Agent，AgentPool 给每个用户独立实例并统一管理：

import asyncio

from milu import AgentPool, ModelRegistry



async def main():

    llm = ModelRegistry.create("qwen", model="qwen3.6-plus")  # 协程安全，可共享

    pool = AgentPool.from_llm(llm)

    await pool.start()



    # 按 (user_id, session_id) 拿这个用户专属的 Agent

    async with pool.acquire("user-1", "session-A") as h:

        async for evt in h.agent.run("你好！"):

            ...



    await pool.stop()



asyncio.run(main())

四个硬不变量：每个 (user, session) ≤1 实例、实例总数有上限、并发 run 有上限、空闲实例自动淘汰。会话、记忆、知识库都按 user_id 自动派生隔离。

---

九、长期记忆与 RAG 知识库

一行开启长期记忆 + 向量知识库（按用户隔离）：

agent = Agent(llm, memory="user-42", knowledge="user-42")

• memory（长期记忆）：少量持久事实，每轮渲染进系统提示词，跨会话、跨进程保留。

• knowledge（RAG 知识库） ：把 pdf/docx/xlsx/pptx/md/txt 分块向量化，余弦检索，来源路由常驻 prompt，可选每轮自动检索，配 kb_search / kb_ingest / kb_manage 三个工具。

适合做企业知识库助手、FAQ 问答、手册检索------回答会区分"内部知识库 vs 网络搜索"的出处，相似度低于阈值就回"无相关内容"，而不是硬编一个答案。

---

十、接入 MCP 服务器

milu 支持 MCP 协议（stdio / streamable HTTP / SSE 三种传输）。在 config/mcp_servers.json 配置：

{

  "mcpServers": {

    "playwright": { "command": "npx", "args": ["@playwright/mcp@latest"] },

    "my-http":    { "type": "streamable_http", "url": "http://localhost:3000/mcp" }

  }

}

MCP 工具采用前沿的"休眠池"设计：schema 不会污染上下文，Agent 按需发现并激活。高并发部署时，一套共享 MCP 进程可以服务整个池。

---

十一、小结与资源

这篇过了一遍 milu 从安装、CLI、Web 服务，到自定义工具、安全模式、多用户并发、RAG、MCP 的完整上手路径。它的定位很清晰：用国产大模型，从单用户 demo 到多用户生产，开箱即用。

项目还很新（v0.1.0），但 1100+ 测试、中英双语文档、Docker 部署文档都在位。如果这篇帮你跑通了，欢迎去 GitHub 点 star / 提 issue：

• 🦌 GitHub：https://github.com/stephonGAO/milu
• 📦 PyPI：pip install -U milu

---