一个通用型 AI Agent 编排框架。给 LLM 配一套工具（搜索、计算、文件、HTTP、Shell、自定义），LLM 自己决定思考 → 调用工具 → 观察 → 再思考 → 给出最终答案。 比 LangChain Agent 更轻，比 AutoGen 更聚焦。接 MiniMax-M3 + LangGraph，可本地 / Hugging Face Space 一键部署。
"设计并开发具备多步推理、工具调用能力的 AI Agent 及 Agentic Workflow"
这个项目就是上面那句话的最小可运行实例：
- 🤖 ReAct 循环：LLM 决定 → 调用工具 → 观察结果 → 再决定
- 🛠️ 9 个内置工具：搜索 / 计算 / 时区 / 文件读写 / HTTP / Shell / 自定义插件
- 🔌 工具注册协议：3 行代码注册一个新工具
- 🪪 持久记忆：对话历史 SQLite，可跨 session 调取
- 🖥️ Web UI + CLI：Gradio UI 实时展示思考过程
- 🧪 可观测：每一步都有 trace，可导出 JSON replay
应用场景示例（自带 5 个真实业务场景 demo）：
- "调研美国市场蓝牙耳机月销量，给出 3 个差异化选品建议"
- "分析我 3 个 Listing 竞品的价格策略，生成竞品分析表"
- "把这份 markdown 文档翻译成英文并总结 3 个核心观点"
- "我的 Listing 标题被亚马逊下架了，查一下可能的原因和申诉流程"
- "我有两个 csv 文件（销量 + 库存），分析哪些 SKU 需要补货"
┌─────────────────────┐
│ 用户输入 query │
└──────────┬──────────┘
▼
┌─────────────────────┐
│ ReAct Loop │
│ │
│ Thought ──▶ Action │
│ ▲ │ │
│ └── Observe ┘ │
└──────────┬──────────┘
│
┌────────────┼────────────┐
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ 9 个工具 │ │ LLM │ │ 记忆 DB │
│ │ │ MiniMax │ │ SQLite │
└──────────┘ └──────────┘ └──────────┘
ReAct 循环（LangGraph 实现）：
def react_step(state):
thought = llm.think(state)
if thought.has_final_answer:
return END
action = thought.choose_tool()
observation = tools[action.name](**action.args)
state.append(thought, action, observation)
return react_step| 工具 | 用途 | 真实场景 |
|---|---|---|
web_search |
网络搜索 | 调研市场、查竞品 |
calculator |
精确数学 | 利润测算、库存计算 |
datetime_now |
当前时间 | 含时区转换 |
read_file |
读文件 | 读 SOP、读 csv |
write_file |
写文件 | 生成报告 |
http_get |
HTTP GET | 接 API（汇率、商标） |
shell_run |
执行 shell | 只读命令（白名单） |
python_repl |
Python REPL | 数据分析 |
echo |
调试 | 测试用 |
注册自定义工具（3 行代码）：
from src.tools import register_tool
@register_tool(name="my_tool", description="我的工具描述", args_schema={...})
def my_tool(arg1: str) -> str:
return "result"git clone https://github.com/hhdhh/agent-orchestrator.git
cd agent-orchestrator
pip install -r requirements.txt
export MINIMAX_API_KEY="sk-cp-..."
# 方式 1：Web UI
python -m src.app
# → http://localhost:7862
# 方式 2：CLI
python -m src.cli "调研美国市场蓝牙耳机月销量"
# 方式 3：Python API
from src.agent import Agent
agent = Agent()
result = agent.run("分析销量.csv 哪些 SKU 需要补货")
print(result)agent-orchestrator/
├── src/
│ ├── app.py # Gradio Web UI
│ ├── cli.py # CLI 入口
│ ├── agent.py # Agent 主类
│ ├── react.py # ReAct 循环核心
│ ├── graph.py # LangGraph 状态机
│ ├── llm.py # LLM 客户端（MiniMax）
│ ├── memory.py # SQLite 持久记忆
│ ├── trace.py # 可观测性（trace 记录 + replay）
│ ├── tools/
│ │ ├── __init__.py # 工具注册表
│ │ ├── web_search.py
│ │ ├── calculator.py
│ │ ├── datetime.py
│ │ ├── file_io.py
│ │ ├── http_get.py
│ │ ├── shell_run.py
│ │ ├── python_repl.py
│ │ └── echo.py
│ └── prompts/
│ ├── react_system.txt
│ └── tool_format.txt
├── tests/
│ ├── test_agent.py # 端到端测试
│ ├── test_tools.py # 工具单测
│ └── fixtures/
├── docs/
│ ├── architecture.md
│ ├── tool_authoring.md # 如何加新工具
│ └── trace_replay.md # trace 回放机制
├── .github/workflows/ci.yml
├── requirements.txt
├── README.md
└── LICENSE
每次运行都会记录完整 trace 到 data/traces/<timestamp>.json：
{
"query": "分析销量.csv 哪些 SKU 需要补货",
"steps": [
{"step": 1, "thought": "需要先读 csv 文件", "action": {"tool": "read_file", "args": {"path": "销量.csv"}}, "observation": "id,name,units,days_of_stock\n1,SKU-A,120,15\n2,SKU-B,80,5\n3,SKU-C,200,30"},
{"step": 2, "thought": "需要计算哪些 days_of_stock < 14", "action": {"tool": "python_repl", "args": {"code": "..."}}, "observation": "[1, 2]"},
{"step": 3, "thought": "可以给出最终答案了", "action": null, "final_answer": "SKU-A 和 SKU-B 需要补货 ..."
]
}回放：
python -m src.trace --replay data/traces/2026-06-10-xxx.json- Agent 循环：LangGraph 0.2+（ReAct 模式）
- LLM：MiniMax-M3（OpenAI 兼容）
- 记忆：SQLite（内置，零配置）
- Web UI：Gradio 4.x（实时展示思考过程）
- 可观测：自研 trace 协议
python -m pytest tests/ -v包含 6 个真实业务场景的端到端测试（mock LLM），验证：
- 工具选择正确
- 思考链条连贯
- 最终答案相关
- Trace 完整
MIT