1. 从一份起诉状到十份文书SuitAgent 多 Agent 律师助理系统到底解决什么问题如果你正在找一套能跑通的多 Agent 系统实战案例SuitAgent 值得认真看一遍。它是一个基于 Claude Code 构建的诉讼法律服务智能分析系统把复杂案件拆成 10 个专业 AI Agent 分层协作覆盖文档解析、争议识别、法律研究、策略制定、文书生成、质量审查的完整链路。适合谁适合想学多 Agent 协作架构的开发者、想用 AI 提效的法律从业者以及正在找 Claude Code 真实落地场景的工程师。传统诉讼工作里律师收到一份起诉状后往往要花 3 到 4 小时做这些事通读材料、提取当事人和诉讼请求、查相关法条、梳理争议焦点、起草答辩状。这些工作里真正需要深度专业判断的部分其实不多大量时间消耗在信息抽取、整合和格式化输出上。SuitAgent 的思路就是把这些可标准化、可工程化的环节交给 AI Agent 流水线律师只在关键决策点介入。我试过把一份起诉状丢进去系统自动识别出被告应诉场景然后依次完成 PDF 解析、案件要素提取、争议焦点识别、应诉策略制定、答辩状起草最后输出一整套初稿文件。整个过程从原来的 6 到 10 小时压缩到 15 到 30 分钟。这不是说 AI 能替代律师而是说那些重复性的信息处理工作确实可以交给一套设计良好的多 Agent 系统。这套系统的核心设计思想是分层协作。10 个 Agent 按职能分成四层输入层负责文档采集与解析分析层负责争议识别和法律研究输出层负责文书和报告生成支持层负责日程管理和质量审查。每一层专注特定任务类型层与层之间通过主 Agent 调度子 Agent 只把最终结果返回给主 Agent主 Agent 再根据这些结果做决策。这种设计解决了法律文档上下文过长的问题——如果所有内容都塞进一个上下文窗口模型很容易丢失关键信息通过 subagent 机制每个 Agent 只处理自己那部分返回精炼结果主 Agent 拿到的就是结构化后的关键信息。下面我会从环境准备开始一步步带你把 SuitAgent 跑起来包括 Claude Code 的接入配置、Agent 角色定义、任务分发规则、本地验证步骤以及常见的报错排查。你不需要有法律背景只要会基本的命令行操作和 JSON/YAML 配置就能跟着做下来。2. 前置准备Claude Code 接入与 TaoToken 配置SuitAgent 基于 Claude Code 构建所以第一步是把 Claude Code 的运行环境配好。Claude Code 是 Anthropic 推出的命令行编程助手支持通过 API 方式接入模型。这里我们用 TaoToken 作为模型接入入口它提供 Claude 系列模型的 API 访问配置简单适合国内开发者使用。先确认你的本地环境Node.js 18 以上、npm 或 yarn、Git。然后安装 Claude Codenpm install -g anthropic-ai/claude-code安装完成后需要配置 API 接入信息。Claude Code 支持通过环境变量或配置文件指定 Base URL 和 API Key。TaoToken 的 API 地址是https://taotoken.net/api你需要在 TaoToken 控制台创建一个 API Key。创建 Key 的路径登录 TaoToken 官网后进入控制台找到 API Keys 页面点击创建新 Key。建议给这个 Key 起个容易识别的名字比如suitagent-dev方便后续管理。拿到 Key 之后配置 Claude Code 的接入信息。有两种方式推荐用配置文件方式更清晰也更容易管理。在用户目录下创建或编辑~/.claude/settings.json{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoToken密钥 } }如果你用的是 Windows路径是C:\Users\你的用户名\.claude\settings.json。注意 JSON 格式要严格正确不能有多余逗号。配置完成后验证 Claude Code 是否能正常调用模型claude --version claude 用一句话介绍你自己如果返回了模型输出说明接入成功。如果报 401 错误检查 API Key 是否复制完整如果报连接超时检查 Base URL 是否写成了https://taotoken.net/api注意末尾没有斜杠。接下来克隆 SuitAgent 项目git clone https://github.com/cat-xierluo/SuitAgent.git cd SuitAgent项目结构里最关键的是agents/目录里面定义了 10 个 Agent 的角色配置workflows/目录定义了不同场景下的任务分发规则context/目录用来存放案件上下文文件。先大致浏览一遍这些目录后面我们会逐个配置。还需要确认 Claude Code 的模型设置。在 SuitAgent 项目根目录下创建.claude/settings.json指定使用的模型 ID{ model: claude-sonnet-4-20250514, env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoToken密钥 } }这里 Model ID 填你 TaoToken 账号下可用的 Claude 模型标识。如果你不确定用哪个可以在 TaoToken 的模型对话页面先测试一下确认模型能正常响应后再填入配置。三件套确认Base URL 是https://taotoken.net/apiKey 是你创建的sk-开头的密钥Model ID 是 Claude 系列模型标识。这三个信息在后续所有配置里保持一致不要混用不同来源的 Key 和地址。3. 可复制配置Agent 角色定义与任务分发规则SuitAgent 的核心在于 Agent 角色配置和任务分发规则。这一章给出可直接复制的配置片段你照着改就能用。先看 Agent 角色定义。每个 Agent 用一个 Markdown 文件描述放在agents/目录下。以 DocAnalyzer 为例创建agents/doc-analyzer.md--- name: DocAnalyzer description: 法律文档解析与信息提取 model: claude-sonnet-4-20250514 tools: - Read - Write - Glob --- 你是法律文档分析专家。你的任务是解析用户上传的法律文档提取结构化信息。 输入法律文档文件路径PDF、Word、图片或文本 输出JSON 格式的结构化数据包含以下字段 - case_type: 案件类型 - parties: 当事人信息原告、被告 - claims: 诉讼请求 - facts: 案件事实摘要 - evidence_list: 证据清单 - legal_basis: 引用法条 处理规则 1. 如果是 PDF 或图片先做 OCR 识别 2. 识别文档类型起诉状、判决书、庭审笔录等 3. 提取上述字段缺失字段填 null 4. 输出必须是合法 JSON不要加额外解释其他 Agent 按同样格式创建。EvidenceAnalyzer 负责证据分析IssueIdentifier 负责争议焦点识别Researcher 负责法律研究Strategist 负责策略制定Writer 负责文书生成Reporter 负责报告编制Summarizer 负责摘要生成Scheduler 负责日程管理Reviewer 负责质量审查。每个 Agent 的description和系统提示词要写清楚职责边界避免职责重叠导致输出混乱。然后是任务分发规则。SuitAgent 用 YAML 定义工作流放在workflows/目录下。以被告应诉场景为例创建workflows/defense-response.yamlname: 被告应诉工作流 trigger: 收到起诉状需要应诉 steps: - agent: DocAnalyzer input: 起诉状文件路径 output: case_info.json - agent: IssueIdentifier input: case_info.json output: issues.json depends_on: DocAnalyzer - agent: Researcher input: issues.json output: research.json depends_on: IssueIdentifier - agent: Strategist input: [case_info.json, issues.json, research.json] output: strategy.json depends_on: [IssueIdentifier, Researcher] - agent: Writer input: [case_info.json, strategy.json] output: 答辩状草稿.md depends_on: Strategist - agent: Reviewer input: 答辩状草稿.md output: review_report.json depends_on: Writer parallel: - [DocAnalyzer, EvidenceAnalyzer]这个配置里steps定义了执行顺序depends_on指定依赖关系parallel指定可以并行执行的 Agent。DocAnalyzer 和 EvidenceAnalyzer 可以同时跑因为它们都只依赖原始输入互不干扰。主 Agent 的调度逻辑写在main-agent.md里--- name: MainAgent description: 多 Agent 调度中枢 model: claude-sonnet-4-20250514 --- 你是 SuitAgent 的主调度 Agent。你的职责是 1. 接收用户输入判断案件场景 2. 根据场景选择对应的工作流 YAML 3. 按工作流定义依次或并行调用子 Agent 4. 收集子 Agent 输出传递给下游 Agent 5. 最终汇总所有输出生成案件分析包 调度规则 - 子 Agent 只返回最终结果不返回中间过程 - 如果某个子 Agent 失败重试一次仍失败则记录错误并继续 - 所有输出写入 context/{case_id}/ 目录 - 每个子 Agent 调用时传入必要的上下文文件路径上下文继承机制通过context/目录实现。每个案件一个子目录比如context/case-20250501/里面存放case_info.json、issues.json、research.json、strategy.json等文件。当有新证据进来时主 Agent 读取已有上下文只让相关 Agent 做增量更新不需要从头跑一遍。Reviewer 的配置要特别注意它需要在独立上下文中运行不能和 Writer 共享上下文否则会陷入自我证实的陷阱——Writer 觉得自己写对了Reviewer 在同一上下文里也容易顺着这个思路走。所以 Reviewer 的配置里要明确--- name: Reviewer description: 独立质量审查 model: claude-sonnet-4-20250514 isolated: true --- 你是独立质量审查专家。你不参与内容生成只负责审查其他 Agent 的输出。 审查维度 1. 信息提取准确性当事人、诉讼请求、事实是否与原文一致 2. 证据分析逻辑性证据链是否完整质证意见是否有依据 3. 法条引用准确性引用的法条是否现行有效是否适用于本案 4. 文书格式规范性是否符合法律文书格式要求 输出格式 { quality_level: A/B/C/D, issues: [问题1, 问题2], suggestions: [修改建议1, 修改建议2] }isolated: true表示这个 Agent 在独立上下文中运行不继承主 Agent 的对话历史。这是保证审查独立性的关键。配置完成后目录结构应该是这样的SuitAgent/ ├── .claude/ │ └── settings.json ├── agents/ │ ├── doc-analyzer.md │ ├── evidence-analyzer.md │ ├── issue-identifier.md │ ├── researcher.md │ ├── strategist.md │ ├── writer.md │ ├── reporter.md │ ├── summarizer.md │ ├── scheduler.md │ └── reviewer.md ├── workflows/ │ ├── defense-response.yaml │ ├── evidence-challenge.yaml │ └── post-hearing.yaml ├── context/ │ └── (案件上下文文件) └── main-agent.md4. 验证请求跑通一条完整的多 Agent 协同推理链路配置写好了接下来验证整条链路能不能跑通。我们用一个模拟起诉状做测试不需要真实案件数据。先准备测试文件。在项目根目录创建test-data/complaint.txt民事起诉状 原告张三男1985年3月出生住北京市朝阳区。 被告李四男1987年8月出生住北京市海淀区。 诉讼请求 1. 判令被告偿还借款本金人民币50万元 2. 判令被告支付逾期利息以50万元为基数按年利率6%计算自2024年1月1日起至实际清偿之日止 3. 本案诉讼费用由被告承担。 事实与理由 2023年6月被告因资金周转需要向原告借款50万元约定2023年12月31日前归还。 原告通过银行转账方式将50万元交付被告被告出具借条一份。 借款到期后原告多次催要被告均以各种理由推脱至今未归还。 原告认为被告的行为已构成违约严重损害了原告的合法权益。 为维护原告合法权益特向贵院提起诉讼请求依法判决。 此致 北京市朝阳区人民法院 具状人张三 2025年1月15日然后启动 Claude Code在 SuitAgent 项目目录下运行cd SuitAgent claude进入交互界面后输入指令收到起诉状需要应诉。文件路径test-data/complaint.txt主 Agent 会开始调度。你会看到它依次调用 DocAnalyzer、IssueIdentifier、Researcher、Strategist、Writer、Reviewer。每个 Agent 执行时Claude Code 会显示调用的工具和返回结果。DocAnalyzer 的输出应该类似{ case_type: 民间借贷纠纷, parties: { plaintiff: {name: 张三, gender: 男, birth_year: 1985, address: 北京市朝阳区}, defendant: {name: 李四, gender: 男, birth_year: 1987, address: 北京市海淀区} }, claims: [ 偿还借款本金50万元, 支付逾期利息年利率6%自2024年1月1日起算, 承担诉讼费用 ], facts: 2023年6月被告向原告借款50万元约定2023年12月31日前归还原告通过银行转账交付被告出具借条。到期后被告未归还。, evidence_list: [借条, 银行转账记录], legal_basis: [民法典第667条, 民法典第675条, 民法典第676条] }IssueIdentifier 会识别出争议焦点比如借款事实是否成立、利息计算标准是否合理、是否已过诉讼时效等。Researcher 会检索相关法条和案例。Strategist 会给出应诉策略比如对借款事实无异议但主张利息计算标准过高或审查诉讼时效是否届满。Writer 生成答辩状草稿Reviewer 做质量审查。最终在context/目录下会生成一个案件文件夹里面包含所有中间文件和最终输出。验证成功的标志context/目录下出现完整的案件分析包包括case_info.json、issues.json、research.json、strategy.json、答辩状草稿.md、review_report.json。打开答辩状草稿.md内容应该结构完整、格式规范包含答辩人信息、答辩事项、事实与理由、法律依据等部分。如果某个 Agent 没有按预期输出检查它的 Markdown 配置里tools字段是否包含了需要的工具。比如 DocAnalyzer 需要Read和Write如果只写了Read它就无法保存输出文件。再测试一个并行场景。准备一份新证据文件test-data/new-evidence.txt然后输入有新证据需要质证。证据文件test-data/new-evidence.txt主 Agent 会读取之前的案件上下文然后调用 EvidenceAnalyzer 和 DocAnalyzer 并行处理Researcher 同时做法条检索最后 Writer 生成质证意见。这个过程验证了上下文继承和并行执行两个核心机制。5. 常见报错排查401、local proxy failed、reading choices、OAuth跑多 Agent 系统时最容易出问题的地方是 API 接入和 Agent 调度。下面列出几个我踩过的坑和对应的排查方法。401 Unauthorized这是最常见的错误说明 API Key 无效或没有正确传递。排查步骤第一检查~/.claude/settings.json和项目.claude/settings.json里的ANTHROPIC_API_KEY是否一致有没有多余空格第二确认 Key 没有过期在 TaoToken 控制台的 API Keys 页面可以看到 Key 的状态第三确认 Base URL 写的是https://taotoken.net/api不要加/v1或其他路径第四如果用了环境变量检查echo $ANTHROPIC_API_KEY是否有输出。如果确认 Key 没问题但还是 401可能是 Claude Code 版本问题。运行claude --version确认版本然后npm update -g anthropic-ai/claude-code更新到最新版。local proxy failed这个错误通常出现在网络环境有代理设置的情况下。Claude Code 会读取系统的HTTP_PROXY和HTTPS_PROXY环境变量如果这些变量指向了一个不可用的代理就会报 local proxy failed。解决方法检查echo $HTTP_PROXY和echo $HTTPS_PROXY如果有值且你不需要代理用unset HTTP_PROXY和unset HTTPS_PROXY清除。或者在.claude/settings.json里显式设置NO_PROXY: taotoken.net让请求绕过代理。reading choices 报错这个错误一般出现在模型返回格式不符合预期时。Claude Code 期望模型返回特定结构的响应如果模型输出被截断或格式错乱就会报 reading choices 失败。排查第一检查 Model ID 是否正确用不支持的模型 ID 会导致响应格式异常第二检查输入是否过长如果单次请求超过模型上下文限制响应会被截断第三在 SuitAgent 的 Agent 配置里确保系统提示词明确要求输出 JSON 格式并且加了不要加额外解释这类约束。如果问题持续可以在 TaoToken 的模型对话页面单独测试同一个 Model ID确认模型本身能正常返回结构化输出。OAuth 相关报错Claude Code 默认可能尝试 OAuth 登录流程如果你用的是 API Key 方式接入需要确保没有触发 OAuth。在.claude/settings.json里明确设置apiKeyHelper: null或者不配置 OAuth 相关字段。如果之前登录过 Anthropic 账号运行claude logout清除登录状态然后重新用 API Key 配置。Agent 调度卡住或死循环如果主 Agent 反复调用同一个子 Agent或者某个步骤一直不往下走检查工作流 YAML 里的depends_on是否形成了循环依赖。比如 A 依赖 BB 又依赖 A就会死锁。另外检查子 Agent 的输出文件路径是否和下游 Agent 的输入路径一致路径不匹配会导致下游 Agent 读不到文件一直等待。Reviewer 输出质量评级总是 D如果 Reviewer 对所有输出都打低分可能是它的审查标准太严格或者它没有拿到完整的上下文。检查 Reviewer 的配置里isolated: true是否生效以及传入的输入文件是否包含了被审查的完整内容。另外Reviewer 的系统提示词里要明确审查维度和评分标准否则模型可能凭感觉打分。排查时建议打开 Claude Code 的详细日志模式在启动时加--verbose参数可以看到每个 Agent 调用的完整请求和响应方便定位问题。6. 从跑通到用好多 Agent 系统的调优方向与接入入口跑通基础链路之后下一步是让系统真正好用。这里有几个调优方向。第一是上下文文件的组织。SuitAgent 把每个案件的上下文存在context/{case_id}/目录下用 YAML 和 Markdown 混合存储。YAML 存结构化数据案件要素、争议焦点、策略方案Markdown 存非结构化内容文书草稿、分析报告。这种混合方式的好处是结构化数据方便 Agent 读取和更新非结构化内容方便人类阅读和修改。你可以定期把各个案件的 YAML 文件提取出来做一个统一的案件看板方便管理多个案件。第二是 Agent 提示词的迭代。初始版本的提示词往往不够精确跑几个案件后你会发现某些 Agent 的输出格式不稳定或者遗漏关键字段。这时候回到对应的 Markdown 文件把输出格式要求写得更具体加上示例输出模型的表现会明显提升。比如 Writer 生成答辩状时如果格式总是不对就在提示词里贴一个标准答辩状的模板让模型照着填。第三是并行执行的粒度控制。SuitAgent 默认让 DocAnalyzer 和 EvidenceAnalyzer 并行Researcher 内部也并行做法条检索和判例分析。但并行不是越多越好如果两个 Agent 都要写同一个文件就会冲突。所以在工作流 YAML 里要确保并行执行的 Agent 输出到不同文件或者用文件锁机制避免写冲突。第四是 Reviewer 的独立上下文。这是保证质量的关键。Reviewer 不能和 Writer 共享上下文否则它会顺着 Writer 的思路走审查就流于形式。在配置里用isolated: true强制隔离并且给 Reviewer 传入原始输入和 Writer 的输出让它做对比审查而不是只审查输出本身。如果你想把 SuitAgent 接入自己的开发流程需要先准备好 TaoToken 的 API Key 和接入配置。API Key 在控制台的 API Keys 页面创建接入文档在文档页面可以找到详细的参数说明。配置时注意 Base URL 用https://taotoken.net/apiModel ID 填你账号下可用的 Claude 模型标识。对于需要长期跑编码和 Agent 任务的场景可以了解 Coding Plan 的额度方案适合高频调用。如果只是想先验证模型效果可以在模型对话页面直接测试确认模型能正常响应后再接入 SuitAgent。SuitAgent 的价值不在于它现在能生成多完美的法律文书而在于它展示了一套可复制的多 Agent 协作架构。你可以把这套架构迁移到其他领域——比如合同审查、专利分析、合规检查——只要把 Agent 角色和任务分发规则换成对应领域的配置就能快速搭出一个领域专用的多 Agent 系统。Claude Code 作为开发入口提供了 Agent 调度、上下文管理、工具调用的基础能力你只需要专注于业务逻辑的拆解和提示词的打磨。
