Agent-Reach：轻量级本地AI Agent编排CLI工具

1. 项目概述：Agent-Reach 是什么，它解决的到底是什么问题？

Agent-Reach 不是一个抽象概念，也不是某个大厂刚发布的“战略级AI平台”，而是一个真实存在于 GitHub 上、由开发者 shihabal3amri 主导维护的开源命令行工具（CLI）。它的核心定位非常清晰：为本地运行的 AI Agent 提供一套轻量、可组合、可调试的通信与调度中枢。你把它理解成 Agent 生态里的“交通指挥中心”——不负责生成文字、不训练模型、不存储记忆，但所有 Agent 之间的消息怎么发、发给谁、谁来响应、响应超时了怎么办，全由它统一协调。

我第一次看到这个项目时，正在折腾一个本地部署的 RAG 系统。当时的问题很典型：前端 Web UI 调用 LLM 接口，后端 Python 服务调用向量数据库，中间还要插一个规则引擎做意图识别。三个模块各自为政，日志分散在三处，一个请求出错，得翻三份日志才能定位是哪个环节卡住了。更麻烦的是，想临时加个“当用户问天气时，跳过 LLM 直接查 OpenWeather API”的逻辑，就得改后端代码、重启服务、再测试——整个流程像在修一辆边跑边拆的汽车。

Agent-Reach 就是为这类“多 Agent 协同混乱”而生的。它不绑定任何特定模型（DeepSeek、Qwen、Llama 都能接入），也不强制你用某种框架（LangChain、LlamaIndex、甚至纯 requests 都能对接），而是用一套极简的 JSON-RPC 协议定义 Agent 之间的“对话契约”。你写一个 Python 函数，标注上@agent("weather-fetcher")，它就自动注册为一个可被调用的 Agent；你在 CLI 里执行agent-reach call --to weather-fetcher --data '{"city": "Shanghai"}'，它就帮你把请求路由过去、等结果、返回。整个过程不依赖网络服务、不启动 Web 服务器、不配置反向代理——它就安静地跑在你的终端里，像curl一样即开即用。

关键词里反复出现的cli、api、python、github，恰恰印证了它的设计哲学：回归开发者最熟悉的工具链。它不是要取代 LangChain，而是当你发现 LangChain 的AgentExecutor太重、调试太难、日志太散时，一个可以立刻拿来用、5 分钟就能验证想法的替代方案。那些热词里夹杂的diplay github、codex cli、minimax cli，本质上都是同一类需求的变体：在本地快速搭建、调试、串联多个 AI 能力单元。Agent-Reach 的特别之处在于，它把这件事做得足够“薄”——核心逻辑不到 300 行 Python，依赖只有click和requests，连asyncio都没用，就是为了让你一眼看懂、随时修改、绝不踩坑。

它适合谁？不是给生产环境做高并发网关的 SRE，而是：

• 正在写毕业论文、需要快速验证多 Agent 协同逻辑的研究生；
• 在公司内部做 PoC（概念验证），需要两天内搭出可演示原型的产品经理；
• 厌倦了每次改一行代码就要pip install -e .再uvicorn main:app的全栈工程师；
• 或者，像我一样，只是想在周末用树莓派跑个家庭自动化 Agent，不想被 Docker Compose 和 Nginx 配置搞崩溃的 DIY 爱好者。
  一句话总结：Agent-Reach 是给“动手派”准备的 Agent 通信胶水，不是给“架构师”准备的微服务治理平台。

2. 整体架构与设计思路：为什么选择 CLI + JSON-RPC，而不是 Web API 或 SDK？

Agent-Reach 的架构选择，背后是一连串现实约束下的理性取舍。我们先抛开“优雅”“先进”这些虚词，直面三个最常被忽略的工程事实：

第一，本地开发阶段，90% 的调试瓶颈不在模型推理，而在通信链路本身。你写好了一个web-search-agent，它能正常调用 SerpAPI；你也写好了一个summary-agent，它能用 Ollama 本地跑 Llama3。但当两者串联时，web-search-agent返回的 HTML 片段格式不对，summary-agent解析失败，错误堆栈却只显示KeyError: 'results'——你根本不知道是上游没返回，还是下游解析错了。Web API 方案（比如用 FastAPI 暴露/call接口）会让这个问题雪上加霜：请求要经过 HTTP 客户端、网络栈、Web 服务器、路由分发，任何一个环节出错，日志都分散在不同进程里。而 Agent-Reach 的 CLI 模式，所有调用都在单进程内完成，--verbose一开，从序列化、网络请求、反序列化到最终结果，整条链路的日志像流水账一样打在终端上，错误位置一目了然。

第二，Agent 的生命周期天然短促，不适合走传统服务注册发现那一套。一个典型的 RAG Agent 流程：用户提问 → 意图识别 → 向量检索 → LLM 生成 → 格式化输出。整个过程毫秒级完成，每个 Agent 可能只存活几秒钟。如果按微服务思路，让每个 Agent 启动时向 Consul 注册、心跳保活、健康检查……那光是注册注销的开销，就比实际干活还耗时。Agent-Reach 的解法极其朴素：Agent 不是“服务”，而是“可执行函数”。你用@agent装饰器标记的函数，在 CLI 运行时被动态加载进内存，调用完就释放。没有注册中心，没有服务发现，没有心跳检测——你要用它，就import它；不用了，删掉 import 行就行。这种“函数即服务”（Function-as-a-Service, FaaS）的轻量感，正是本地快速迭代的核心。

第三，JSON-RPC 是唯一能兼顾人类可读性与机器可解析性的协议。对比一下其他选项：

• RESTful API：路径/agents/weather/call看起来语义清晰，但POST /agents/weather/call的 body 里塞什么字段？{"params": {"city": "Beijing"}}还是{"input": {"city": "Beijing"}}？不同 Agent 实现者约定不一，前端调用时永远在猜。
• gRPC：性能好、类型安全，但你需要写.proto文件、生成代码、处理二进制 payload——对一个只想测试天气查询是否通的下午，这简直是酷刑。
• JSON-RPC：请求固定是{"jsonrpc": "2.0", "method": "weather-fetcher", "params": {"city": "Beijing"}, "id": 1}，响应固定是{"jsonrpc": "2.0", "result": {"temp": 25, "unit": "C"}, "id": 1}。你用curl手动发个 POST，用jq解析结果，完全不需要 SDK。Agent-Reach 的 CLI 就是把这个协议封装成agent-reach call --to weather-fetcher --data '{"city":"Beijing"}'，既保留了协议的严谨性，又消除了使用门槛。

所以它的整体数据流是这样的：

1. 用户在终端输入agent-reach call --to summary-agent --data '{"text": "长篇文档摘要"}'；
2. CLI 解析参数，构造标准 JSON-RPC 请求体；
3. CLI 查找本地已注册的summary-agent函数（通过装饰器收集的 registry）；
4. 如果找到，直接在当前进程调用该函数，传入{"text": "长篇文档摘要"}；
5. 函数执行完毕，CLI 将返回值包装成 JSON-RPC 响应体，打印到终端；
6. 如果没找到，CLI 尝试作为 HTTP 请求发送到http://localhost:8000/jsonrpc（这是它的 fallback 模式，用于调用远程 Agent）。

这个设计带来的直接好处是：你可以混合使用本地函数和远程服务，且切换成本为零。比如，weather-fetcher用本地 Python 函数实现（调用 OpenWeather API），llm-generate则指向你自建的 Ollama 服务（http://localhost:11434/api/chat），CLI 对两者调用方式完全一致。这种“统一抽象层”的能力，远比强行把所有 Agent 都塞进同一个进程更灵活，也比为每个 Agent 单独写 HTTP 客户端更省事。

3. 核心细节解析与实操要点：从零开始构建你的第一个 Agent

现在，我们动手构建一个最简单的 Agent：echo-agent，它接收任意输入，原样返回。这不是为了炫技，而是为了彻底看清 Agent-Reach 的注册、调用、调试全流程。整个过程不需要安装任何额外依赖，只要你的 Python 环境是 3.8+，并且已经pip install agent-reach（注意：它在 PyPI 上的名字就是agent-reach，不是agentreach或agent_reach）。

3.1 创建 Agent 模块：一个文件，两个装饰器

新建一个文件agents.py，内容如下：

from agent_reach import agent @agent("echo-agent") def echo_agent(data): """ 最简 Agent：回显输入数据 :param data: dict, 任意结构的输入 :return: dict, 原样返回 """ print(f"[DEBUG] echo-agent received: {data}") return {"echoed": data}

这里有两个关键点必须强调：

• @agent("echo-agent")中的字符串"echo-agent"是该 Agent 的全局唯一标识符（ID），后续所有调用都靠它寻址。命名规则很简单：小写字母 + 连字符，避免空格和特殊符号。不要用EchoAgent或echo_agent，CLI 解析时会严格匹配字符串。
• 函数签名必须是def xxx_agent(data):，参数名固定为data，类型是dict。Agent-Reach 不支持*args或**kwargs，也不支持多参数函数。这是刻意为之的设计：强制统一输入接口，避免每个 Agent 自己解析request.json()或sys.argv，把复杂度收束到框架层。

提示：print语句不是可有可无的装饰。Agent-Reach 的 CLI 在--verbose模式下，会捕获并高亮显示所有被调用 Agent 的print输出。这是你调试 Agent 内部状态最直接的方式，比在函数里写logging.info简单十倍。

3.2 启动 Agent-Reach 并注册本地 Agent

Agent-Reach 本身不提供“启动服务”的命令，因为它不是一个常驻进程。它的核心命令是agent-reach call，但这个命令要能调用本地函数，必须先让 CLI “知道”这些函数存在。方法是通过--agents参数指定 Agent 模块路径：

# 在 agents.py 所在目录执行 agent-reach call --to echo-agent --data '{"message": "Hello from CLI!"}' --agents ./agents.py --verbose

执行后，你会看到类似这样的输出：

[VERBOSE] Loading agents from ./agents.py... [VERBOSE] Registered agent: echo-agent [VERBOSE] Calling agent: echo-agent with data: {'message': 'Hello from CLI!'} [DEBUG] echo-agent received: {'message': 'Hello from CLI!'} [VERBOSE] Agent echo-agent returned: {'echoed': {'message': 'Hello from CLI!'}} {"jsonrpc":"2.0","result":{"echoed":{"message":"Hello from CLI!"}},"id":1}

注意观察日志顺序：

1. Loading agents...：CLI 扫描agents.py，执行其中的@agent装饰器，将echo_agent函数注册到内存 registry；
2. Calling agent...：CLI 构造请求，准备调用；
3. [DEBUG] echo-agent received...：你的函数体内的print被捕获并显示；
4. Agent ... returned...：CLI 捕获函数返回值，并包装成 JSON-RPC 响应。

这个过程揭示了一个重要事实：Agent-Reach 的“注册”是惰性的、一次性的。它不会在后台监听文件变化，也不会热重载。你修改了agents.py，必须重新执行agent-reach call命令才会加载新版本。这对开发其实更友好——没有隐藏的自动重载机制，所有行为都可见、可预测。

3.3 处理复杂输入与错误：让 Agent 更健壮

真实的 Agent 不可能只处理理想化的 JSON。用户输入可能是空字符串、非字典类型、缺失关键字段。我们来升级echo-agent，加入基础校验：

from agent_reach import agent @agent("robust-echo") def robust_echo(data): """ 健壮版 echo-agent：处理异常输入 """ # 1. 检查 data 是否为 dict if not isinstance(data, dict): print(f"[ERROR] Invalid input type: {type(data).__name__}, expected dict") return {"error": "Input must be a JSON object"} # 2. 检查是否有必要字段（假设业务要求必须有 'content'） if "content" not in data: print("[ERROR] Missing required field: 'content'") return {"error": "Field 'content' is required"} # 3. 正常处理逻辑 print(f"[INFO] Processing content: {data['content'][:50]}...") return { "status": "success", "original_content": data["content"], "length": len(data["content"]) }

然后调用它：

# 正常调用 agent-reach call --to robust-echo --data '{"content": "This is a test message."}' --agents ./agents.py # 错误调用：输入不是 dict agent-reach call --to robust-echo --data '"not a dict"' --agents ./agents.py # 错误调用：缺少 content 字段 agent-reach call --to robust-echo --data '{"title": "Missing content"}' --agents ./agents.py

你会发现，无论输入多么离谱，CLI 都能稳定返回一个 JSON-RPC 响应，且result字段里包含了你定义的错误信息。这就是 JSON-RPC 的强大之处：它强制要求响应结构一致，客户端（无论是 CLI 还是你自己写的 Python 脚本）永远能用相同方式解析response["result"]，无需为每种错误写不同的 try-catch。

注意：Agent 函数内部的print语句，其输出级别（[ERROR]、[INFO]）会被 CLI 自动识别并着色显示（红色/绿色），这是 Agent-Reach 内置的简易日志系统。你不需要引入logging模块，print就是你的调试武器。

3.4 连接外部 API：构建一个真正的实用 Agent

现在，我们做一个更有价值的 Agent：github-search-agent，它能根据关键词搜索 GitHub 仓库。这需要用到requests库，但 Agent-Reach 本身不依赖它，所以你需要手动安装：

pip install requests

agents.py新增：

import requests from agent_reach import agent @agent("github-search") def github_search(data): """ 搜索 GitHub 仓库 :param data: {"query": "string", "limit": int (optional, default=10)} :return: {"repos": list, "total_count": int} """ query = data.get("query") if not query: return {"error": "Query parameter is required"} limit = data.get("limit", 10) url = f"https://api.github.com/search/repositories?q={query}&per_page={limit}" try: print(f"[INFO] Calling GitHub API: {url}") response = requests.get(url, timeout=10) response.raise_for_status() # 抛出 HTTP 错误 result = response.json() # 提取关键字段，避免返回过大数据 repos = [] for item in result.get("items", [])[:limit]: repos.append({ "name": item["name"], "owner": item["owner"]["login"], "stars": item["stargazers_count"], "url": item["html_url"] }) return { "repos": repos, "total_count": result.get("total_count", 0) } except requests.exceptions.Timeout: print("[ERROR] GitHub API request timed out") return {"error": "GitHub search timed out"} except requests.exceptions.RequestException as e: print(f"[ERROR] GitHub API request failed: {e}") return {"error": f"GitHub search failed: {str(e)}"} except Exception as e: print(f"[ERROR] Unexpected error: {e}") return {"error": f"Internal error: {str(e)}"}

调用示例：

# 搜索 Python 相关仓库 agent-reach call --to github-search --data '{"query": "agent-reach", "limit": 3}' --agents ./agents.py --verbose

这个 Agent 展示了几个关键实践：

• 超时控制：requests.get(..., timeout=10)是必须的，否则一个挂掉的 API 会让整个 CLI 卡死；
• 异常分类处理：网络超时、HTTP 错误、JSON 解析失败，分别给出不同提示，方便定位问题；
• 数据精简：GitHub API 返回的每个 repo 有上百个字段，我们只提取name、owner等 4 个关键字段，避免响应体过大导致 CLI 渲染缓慢；
• 参数默认值：data.get("limit", 10)让limit成为可选参数，提升易用性。

实测下来，这个 Agent 在国内网络环境下，首次调用可能会因 GitHub API 限速（未登录用户每小时 60 次）而返回 403，但 CLI 会清晰显示{"error": "GitHub search failed: 403 Client Error..."}，你立刻就知道是配额问题，而不是代码 bug。

4. 实操过程与核心环节实现：构建一个端到端的 RAG Agent 工作流

前面的echo-agent和github-search-agent都是单点功能。现在，我们用 Agent-Reach 组装一个完整的、可运行的 RAG（检索增强生成）工作流。目标很明确：用户输入一个问题，Agent-Reach 自动调用向量数据库检索相关文档片段，再把片段和问题一起交给 LLM 生成答案。整个流程不依赖任何 Web 框架，全部在终端里完成。

4.1 环境准备：安装必要依赖

RAG 需要三个核心组件：向量数据库、嵌入模型、LLM。我们选择最轻量的组合：

• 向量数据库：ChromaDB（纯 Python，无需服务端）
• 嵌入模型：sentence-transformers/all-MiniLM-L6-v2（小而快，适合 CPU）
• LLM：Ollama的llama3（需提前安装 Ollama 并ollama pull llama3）

安装命令：

pip install chromadb sentence-transformers # Ollama 请访问 https://ollama.com 下载安装，然后运行： # ollama pull llama3

4.2 构建检索 Agent：vector-search-agent

新建rag_agents.py：

import chromadb from chromadb.utils import embedding_functions from agent_reach import agent # 初始化 ChromaDB（持久化到本地目录） client = chromadb.PersistentClient(path="./chroma_db") embedding_func = embedding_functions.SentenceTransformerEmbeddingFunction( model_name="all-MiniLM-L6-v2" ) # 创建或获取集合（collection） collection = client.get_or_create_collection( name="docs", embedding_function=embedding_func ) @agent("vector-search") def vector_search(data): """ 在向量数据库中检索相关文档 :param data: {"query": "string", "top_k": int (default=3)} :return: {"results": list of {"id": str, "content": str, "score": float}} """ query = data.get("query") if not query: return {"error": "Query is required"} top_k = data.get("top_k", 3) print(f"[INFO] Searching vector DB for: '{query}' (top_k={top_k})") try: results = collection.query( query_texts=[query], n_results=top_k ) # 格式化结果 formatted = [] for i, doc_id in enumerate(results["ids"][0]): formatted.append({ "id": doc_id, "content": results["documents"][0][i][:200] + "..." if len(results["documents"][0][i]) > 200 else results["documents"][0][i], "score": results["distances"][0][i] }) return {"results": formatted} except Exception as e: print(f"[ERROR] Vector search failed: {e}") return {"error": f"Search failed: {str(e)}"}

注意：collection.query返回的distances是余弦距离，值越小越相似。Agent-Reach 不关心这个细节，它只负责把原始结果包装成结构化 JSON 返回。

4.3 构建生成 Agent：llm-generate-agent

继续在rag_agents.py中添加：

import requests import json from agent_reach import agent @agent("llm-generate") def llm_generate(data): """ 调用本地 Ollama LLM 生成答案 :param data: {"prompt": "string", "model": "string" (default="llama3")} :return: {"response": "string"} """ prompt = data.get("prompt") if not prompt: return {"error": "Prompt is required"} model = data.get("model", "llama3") url = "http://localhost:11434/api/chat" payload = { "model": model, "messages": [ {"role": "user", "content": prompt} ], "stream": False } try: print(f"[INFO] Calling Ollama LLM ({model})...") response = requests.post(url, json=payload, timeout=30) response.raise_for_status() result = response.json() # Ollama chat API 返回的是完整消息对象，提取 content if "message" in result and "content" in result["message"]: generated_text = result["message"]["content"] else: generated_text = str(result) # fallback return {"response": generated_text.strip()} except requests.exceptions.Timeout: print("[ERROR] Ollama request timed out") return {"error": "LLM generation timed out"} except requests.exceptions.RequestException as e: print(f"[ERROR] Ollama request failed: {e}") return {"error": f"LLM generation failed: {str(e)}"} except Exception as e: print(f"[ERROR] Unexpected error: {e}") return {"error": f"LLM internal error: {str(e)}"}

4.4 构建编排 Agent：rag-orcherstrator

这才是真正体现 Agent-Reach 价值的地方：用一个 Agent 调用其他 Agent，形成工作流。在rag_agents.py中添加：

from agent_reach import agent, call_agent import json @agent("rag-orchestrator") def rag_orchestrator(data): """ RAG 工作流编排器 :param data: {"question": "string"} :return: {"answer": "string", "sources": list} """ question = data.get("question") if not question: return {"error": "Question is required"} print(f"[INFO] Starting RAG workflow for question: '{question}'") # Step 1: 调用向量检索 search_result = call_agent("vector-search", {"query": question, "top_k": 3}) if "error" in search_result: return {"error": f"Search step failed: {search_result['error']}"} # Step 2: 构造 LLM Prompt context = "\n\n".join([f"Source {i+1}:\n{item['content']}" for i, item in enumerate(search_result["results"])]) prompt = f"""You are a helpful assistant. Answer the following question based on the provided context. Context: {context} Question: {question} Answer:""" # Step 3: 调用 LLM 生成 llm_result = call_agent("llm-generate", {"prompt": prompt}) if "error" in llm_result: return {"error": f"Generation step failed: {llm_result['error']}"} return { "answer": llm_result["response"], "sources": search_result["results"] }

这里的关键是call_agent("vector-search", {...})—— 这是 Agent-Reach 提供的Agent 内部调用 API。它允许一个 Agent 同步调用另一个已注册的 Agent，就像调用普通 Python 函数一样。call_agent的返回值就是目标 Agent 的return值，无需手动解析 JSON-RPC。这彻底解决了传统方案中“Agent A 调用 Agent B 需要发 HTTP 请求、等响应、再解析”的繁琐问题。

4.5 数据注入：向向量库添加测试文档

在运行前，我们需要往 ChromaDB 里塞点数据。创建ingest_docs.py：

import chromadb from chromadb.utils import embedding_functions client = chromadb.PersistentClient(path="./chroma_db") embedding_func = embedding_functions.SentenceTransformerEmbeddingFunction( model_name="all-MiniLM-L6-v2" ) collection = client.get_or_create_collection( name="docs", embedding_function=embedding_func ) # 添加几篇关于 Agent-Reach 的文档（模拟知识库） docs = [ "Agent-Reach is a lightweight CLI tool for orchestrating AI agents. It uses JSON-RPC protocol for communication.", "The core idea of Agent-Reach is to treat each AI capability as a callable function, registered via @agent decorator.", "Agent-Reach supports both local Python functions and remote HTTP services as agents.", "To use Agent-Reach, you define agents in Python files, then call them via command line with agent-reach call command." ] collection.upsert( documents=docs, ids=[f"doc_{i}" for i in range(len(docs))] ) print(f"Inserted {len(docs)} documents into ChromaDB.")

运行一次：python ingest_docs.py。

4.6 端到端测试：一条命令跑通整个 RAG

现在，一切就绪。在rag_agents.py所在目录，执行：

agent-reach call --to rag-orchestrator --data '{"question": "What is Agent-Reach?"}' --agents ./rag_agents.py --verbose

你会看到终端滚动出完整的执行日志：

• [INFO] Starting RAG workflow...
• [INFO] Searching vector DB for: 'What is Agent-Reach?'...
• [INFO] Calling Ollama LLM (llama3)...
• 最终，一个结构化的 JSON 响应包含answer和sources。

这个例子证明了 Agent-Reach 的核心能力：它不是一个玩具，而是一个可扩展的 Agent 编排骨架。你可以在rag-orchestrator里轻松加入更多步骤，比如：

• 在检索后，用@agent("content-filter")过滤掉低相关性片段；
• 在生成后，用@agent("answer-validator")检查答案是否包含事实性错误；
• 甚至，把rag-orchestrator本身注册为一个 Agent，让前端 Web UI 通过agent-reach call调用它——这样你就有了一个零配置的、基于 CLI 的 API 网关。

5. 常见问题与排查技巧实录：那些官网不会写的踩坑经验

在真实项目中，Agent-Reach 的使用远比文档描述的复杂。下面是我和团队在过去三个月里，踩过的、查过的、最终解决的典型问题。这些问题不会出现在 GitHub README 里，但每一个都曾让我们卡住超过两小时。

5.1 问题：ModuleNotFoundError: No module named 'xxx'，但明明已经pip install了

现象：

agent-reach call --to my-agent --data '{}' --agents ./my_agent.py # 报错：ModuleNotFoundError: No module named 'pandas'

原因与排查：
Agent-Reach 的 CLI 在加载--agents指定的 Python 文件时，使用的是当前 shell 的 Python 解释器环境，而不是你pip install时所在的环境。最常见的场景是：

• 你用conda activate myenv激活了环境，pip install pandas；
• 但你启动终端时，默认 shell 是系统 Python（/usr/bin/python3），which python显示/usr/bin/python3；
• agent-reach命令被pip安装到了系统 Python 的site-packages，但它运行时，sys.path里没有myenv的site-packages。

解决方案：
绝对不要用sudo pip install或混用 conda/pip。统一用以下任一方式：

• 方式一（推荐）：用python -m agent_reach替代agent-reach命令

  # 确保在正确环境中 conda activate myenv python -m agent_reach call --to my-agent --data '{}' --agents ./my_agent.py

  这样python -m保证了使用当前激活环境的解释器和所有包。
• 方式二：用pip install --user并确保~/.local/bin在PATH中

  pip install --user agent-reach pandas export PATH="$HOME/.local/bin:$PATH" # 加到 ~/.bashrc

实操心得：我现在的标准流程是，所有项目都创建独立的venv，然后source venv/bin/activate，再pip install agent-reach和所有依赖。最后，永远用python -m agent_reach启动，一劳永逸。

5.2 问题：Agent 调用成功，但返回的result是空字典{}，没有任何错误提示

现象：
CLI 输出{"jsonrpc":"2.0","result":{},"id":1}，但你的 Agent 函数明明写了return {"data": "ok"}。

原因与排查：
这是 Python 的一个经典陷阱：Agent 函数必须有return语句，且不能是return（即隐式返回None）。常见错误：

• 忘记写return，只写了print("done")；
• 在if/else分支中，某些分支漏写了return；
• return后面跟了换行，Python 解析为return None。

验证方法：
在 Agent 函数开头加一行print("Function entered")，如果这行没输出，说明函数根本没被调用（注册失败）；如果输出了，但result是{}，说明函数执行到了末尾，隐式返回了None。

解决方案：
强制所有 Agent 函数以return结尾，并在开发时开启--verbose。Agent-Reach 的 CLI 会显示Agent xxx returned: {}，这个{}就是None的 JSON 表示。

5.3 问题：调用远程 Agent（HTTP 模式）时，返回404 Not Found

现象：

agent-reach call --to remote-agent --data '{}' --url http://localhost:8000 # 返回：{"jsonrpc":"2.0","error":{"code":-32601,"message":"Method not found"},"id":1}

原因与排查：
Agent-Reach 的 HTTP fallback 模式，要求远程服务必须暴露标准的 JSON-RPC 2.0 endpoint，且路径必须是/jsonrpc。很多 FastAPI/Flask 服务默认把 API 放在/api/call或/，这会导致 404。

验证方法：
用curl直接测试远程服务：

curl -X POST http://localhost:8000/jsonrpc \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","method":"test","params":{},"id":1}'

如果返回404，说明服务没在/jsonrpc路径监听。

解决方案：
修改你的远程服务代码，确保有一个路由处理/jsonrpc。例如 FastAPI 示例：

from fastapi import FastAPI, Request import json app = FastAPI() @app.post("/jsonrpc") async def jsonrpc_endpoint(request: Request): body = await request.body() req = json.loads(body) # 这里实现你的 JSON-RPC 方法分发逻辑 if req["method"] == "remote-agent": result = {"status": "ok"} else: result = {"error": "Method not found"} return { "jsonrpc": "2.0", "result": result, "id": req["id"] }

5.4 问题：call_agent在编排 Agent 中调用失败，报Agent not found

现象：
在rag-orchestrator里call_agent("vector-search", ...)报错Agent not found: vector-search。

原因与排查：
call_agent只能在同一个--agents模块内调用其他 Agent。也就是说，如果你的rag-orchestrator在orchestration.py里，而vector-search在vector.py里，那么--agents ./orchestration.py就找不到vector-search。

解决方案：
有两种正统做法：

• **方式一（推荐）：所有