1. 项目概述构建文件系统原生的强智能体工作流平台如果你正在尝试构建一个能真正“运行”的智能体系统而不仅仅是调用API那么你很可能已经遇到了一个核心矛盾现有的很多框架把重点放在了“模型能调用什么”上却忽略了智能体作为一个执行单元需要一个真实的会话、一个持久的工作目录、一套权限模型、有副作用的工具调用以及与其他智能体在同一个系统内协作的能力。这正是AgentWorld这个Python包试图解决的底层问题。它不是一个顶层的应用而是一个位于应用之下的平台层为构建像AutoR那样的自动化研究系统或者任何需要强智能体协作的工作流和组织提供可复用的基础构件。简单来说AgentWorld提供了一套“乐高积木”让你可以搭建一个文件系统原生、状态可恢复、执行可追踪的智能体工作流。它的核心设计理念是执行优先这意味着它从第一天起就考虑了智能体在实际运行中会遇到的所有“脏活累活”会话管理、工作空间隔离、检查点、状态回滚、跨阶段交接、产物验证等等。这听起来可能有点抽象但当你需要让一个智能体去执行一段代码、生成一份报告并让另一个智能体去审核这份报告时这些“脏活累活”就成了决定系统能否稳定运行的关键。这个项目目前聚焦于平台的基础层实现包括控制器、操作器、明确的A2A智能体到智能体协议、图运行时、工作空间、清单、阶段、产物等一系列原语。你可以把它看作是智能体世界的“操作系统内核”而具体的应用如自动化研究则是运行在这个内核之上的“应用程序”。注意AgentWorld与许多“提示词编排”框架有本质区别。它不假设智能体只是无状态的文本生成器而是将其视为有状态、可交互、能产生持久化副作用的执行单元。这种设计选择使得它特别适合需要严谨流程、可审计性和可恢复性的生产级场景。2. 核心设计理念与架构拆解2.1 为什么需要“文件系统原生”在传统的智能体编排中状态管理常常是个难题。状态可能存储在内存里、数据库里或者分散在各个提示词的上下文窗口中。AgentWorld选择了一个看似朴素但极其强大的方案将一切状态显式地持久化到文件系统中。每个运行Run都有一个独立的根目录里面包含了目标描述、运行配置、内存记录、阶段清单、产物索引、操作器状态以及实际的工作空间。这种设计带来了几个关键优势可观测性与可调试性你可以直接打开运行目录查看每个阶段生成了什么文件智能体做了什么决策状态是如何演变的。这对于调试复杂的工作流至关重要。可恢复性运行可以被中断、暂停然后从任意一个已完成检查点的阶段恢复。运行时通过维护run_manifest.json等清单文件来跟踪进度和状态。强一致性产物Artifact不再是模糊的文本描述而是文件系统中实实在在的文件。系统可以通过扫描文件并生成artifact_index.json来推断产物模式并进行验证。与现有工具链集成文件是通用的接口。其他脚本、CI/CD流水线、版本控制系统都可以直接与AgentWorld生成的工作空间交互。2.2 核心组件边界与职责AgentWorld的架构清晰地划分了不同组件的职责避免了常见的“上帝对象”问题。理解这些边界是有效使用它的关键。2.2.1 控制器与具体AI提供商的边界控制器是平台与外部AI世界如Claude Code、Codex交互的桥梁。它的职责非常具体会话生命周期管理创建、维持和销毁与特定AI模型的会话。工具策略映射将平台统一的工具调用规范转换为特定AI提供商能理解的格式例如将“执行Python脚本”映射为Claude Code的run_command工具。流式响应解析实时解析AI返回的流式事件如message_start,tool_call,message_completed并将其标准化为平台内部的ControllerEvent。这种隔离意味着如果你想支持一个新的AI模型比如GPT-4 Code Interpreter你只需要实现一个新的控制器而无需改动上层的操作器、运行时或工作流逻辑。项目目前已经实现了ClaudeCodeController并为CodexController和OpenClawController预留了接口。2.2.2 操作器统一的执行单元抽象操作器是控制器之上的抽象层。它定义了一个智能体“节点”应该如何被调用。其核心职责包括组装请求根据节点的目标、角色、技能列表以及当前运行状态组装出发送给控制器的标准化请求。加载技能从本地的技能市场skills/目录动态加载并注入特定领域的指导。规范化输出将控制器返回的原始事件转换为平台内部的结构化消息、工具结果、交接物和状态补丁。DefaultOperator和StageOperator是两种主要的操作器实现。前者用于通用的图节点后者专门用于具有固定合约起草、修复、审核、终版的“阶段”。2.2.3 技能可复用的领域指导模块技能是AgentWorld一个非常巧妙的抽象。它不是一个营销标签而是一个实实在在的、可加载的执行指导包。每个技能是一个文件夹通常包含一个SKILL.md文件里面描述了该技能的使用时机、工作流程、参考案例等。例如research-paper-search技能会指导智能体在开始执行前如何系统地搜索相关论文、数据库和证据链。你可以为工作流中不同的节点分配不同的技能组合。比如“规划者”节点可能加载research-paper-search和experiment-planning技能而“审核者”节点则加载citation-audit和result-audit技能。这样即使它们使用同一个底层的AI模型通过同一个控制器也能表现出完全不同的领域专长和行为模式。2.2.4 A2A协议结构化的智能体间通信智能体之间如何通信很多框架依赖于在提示词里拼接上下文这既脆弱又难以追踪。AgentWorld定义了一个明确的A2A协议规定了智能体间传递的消息、工具调用结果、阶段交接物、产物引用等都必须采用结构化的形式。这确保了通信的可靠性和可追溯性为图运行时进行状态合并和路由决策提供了清晰的数据基础。2.2.5 图运行时调度与状态管理的引擎图运行时是当前最具体的编排子系统但请注意AgentWorld的范围比图运行时更广。它负责节点调度决定下一个执行哪个节点。状态合并将一个节点的输出状态补丁合并到全局运行状态中。检查点与持久化在关键节点后保存运行状态支持恢复和回滚。执行追踪记录所有事件形成完整的执行轨迹。运行时确保了整个工作流的执行是可控、可中断、可恢复的。2.3 与AutoR类应用的关系AgentWorld明确将自己定位在像AutoR这样的具体应用之下。一个AutoR风格的自动化研究系统需要什么它需要一个固定的研究阶段流水线如规划、假设、设计、编码、实验、分析、写作、发布每个阶段都需要起草、审核、产出最终产物并且阶段之间需要有批准的“记忆”进行交接。AgentWorld现在提供的就是构建这类系统所需的所有可复用原语RunWorkspace提供了持久的运行目录。StageSpec和StageOperator定义了阶段合约和执行逻辑。ApprovalGate实现了人工或自动化的审核关卡。append_approved_stage_summary和write_stage_handoff管理着阶段间的记忆传递。scan_artifacts和write_artifact_index负责产物的扫描和验证。examples/auto-research目录下的参考实现完整地演示了如何用AgentWorld的积木搭建出一个八阶段的AutoR式工作流而无需复制或修改AutoR本身的代码。这证明了其作为平台层的有效性和灵活性。3. 从零开始快速上手与核心实操3.1 环境准备与安装首先你需要一个Python 3.11的环境。我强烈建议使用虚拟环境来管理依赖避免污染全局环境。# 克隆仓库 git clone https://github.com/ScienceIntelligence/AgentWorld.git cd AgentWorld # 创建并激活虚拟环境以venv为例 python -m venv .venv source .venv/bin/activate # Linux/macOS # .venv\Scripts\activate # Windows # 以可编辑模式安装包及其依赖 python -m pip install -e .安装完成后运行测试套件是一个好习惯可以确保一切基本功能正常。python -m unittest discover -s tests -v3.2 运行你的第一个智能体图项目提供了一个简单的“规划者-编码者-审核者”顺序图示例。这个例子不依赖任何真实的AI控制器而是使用一个模拟的静态控制器非常适合用来理解图运行时的工作机制。python examples/planner_coder_reviewer.py运行这个脚本你会看到控制台输出展示了图的编译、节点的顺序执行、状态的合并以及产物的创建。这是理解AgentGraph、DefaultOperator和运行时交互的绝佳起点。3.3 体验真实的AutoR式研究流程要运行一个真正“完整”的用例你需要一个能实际执行代码的强智能体。AgentWorld默认集成了ClaudeCodeController它需要你本地安装并认证好Claude Code CLI工具。实操心得在运行真实用例前务必确认你的claudeCLI已正确安装且认证有效。可以运行claude --version和claude auth status来验证。网络环境也可能影响Claude Code的调用请确保稳定的连接。以下命令将启动一个完整的自动化研究流程目标是构建并评估一个手写数字分类模型python examples/auto-research/run.py \ --runs-dir /tmp/agentworld-auto-research-runs \ --approval-mode validation-only \ --permission-mode bypassPermissions \ --max-attempts 2 \ --timeout 7200 \ Build and evaluate a handwritten digit classification model on the scikit-learn digits dataset. Train SVM-RBF, RandomForest, kNN, LogisticRegression, and DecisionTree baselines. The experiment stage must actually execute the Python training script and produce real cross-validation results, held-out test results, confusion matrices, hypothesis verdicts, figures, and a paper-style report. Do not use predicted or literature-only results as a substitute for execution.让我拆解一下这些参数--runs-dir指定运行目录的根路径。所有运行都会作为子目录创建在这里。--approval-mode validation-only这是一个关键设置。它意味着跳过人工审核提示完全依靠系统对阶段产物的自动验证来决定是否批准该阶段。这对于自动化流水线至关重要。--permission-mode bypassPermissions这个模式允许智能体在工作空间内执行命令如运行Python脚本。请注意这仅在受信任的环境中使用。对于更安全的场景可以使用editOnly模式它只允许文件编辑阻止命令执行。--max-attempts 2每个阶段最多重试修复的次数。--timeout 7200整个运行的总超时时间秒。最后的长字符串是本次运行的“目标”它会被写入goal.md并作为整个工作流的起点。运行开始后CLI会实时打印运行状态、阶段进展、Claude会话活动、工具调用、验证结果和修复尝试。如果你只想看最终结果可以加上--quiet参数。3.4 验证运行结果与产物运行结束后如何判断它是否真正成功不能只看run_manifest.json里的run_status: completed。因为即使流程走完了实验也可能因为权限问题而未能实际执行。我们必须检查具体的产物。首先找到最新的运行目录RUN_ROOT$(ls -td /tmp/agentworld-auto-research-runs/* | head -1) echo $RUN_ROOT然后我们可以编写一个简单的Python脚本来进行系统性的验证import json from pathlib import Path run_root Path(RUN_ROOT) # 1. 检查运行清单 manifest_path run_root / run_manifest.json if not manifest_path.exists(): raise FileNotFoundError(Run manifest not found.) manifest json.loads(manifest_path.read_text()) print(fRun ID: {manifest.get(run_id)}) print(fRun Status: {manifest.get(run_status)}) print(fStages Approved: {sum(1 for s in manifest[stages] if s[approved])} / {len(manifest[stages])}) if manifest[run_status] ! completed: raise ValueError(Run did not complete successfully.) # 2. 检查实验结果文件 results_path run_root / workspace/results/results.json if not results_path.exists(): raise FileNotFoundError(Core results file not found.) results json.loads(results_path.read_text()) # 关键执行标记 if results.get(execution_blocker): raise ValueError(fExecution was blocked: {results[execution_blocker]}) if results.get(experiments_executed) is False: raise ValueError(Experiments were not executed (marked as false).) if results.get(exit_code) not in (0, None): raise ValueError(fExperiment script exited with code: {results[exit_code]}) # 3. 检查必需产物是否存在 required_artifacts [ workspace/results/results.json, workspace/results/cv_results.json, workspace/results/test_results.json, workspace/results/hypothesis_verdicts.json, workspace/figures/accuracy_comparison.png, workspace/figures/confusion_matrices.png, workspace/writing/main.tex, workspace/artifacts/paper.pdf, ] missing [art for art in required_artifacts if not (run_root / art).exists()] if missing: print(WARNING: Missing some artifacts:, missing) else: print(SUCCESS: All core artifacts present.) # 4. 可选检查一些具体指标例如交叉验证精度 cv_results_path run_root / workspace/results/cv_results.json if cv_results_path.exists(): cv_data json.loads(cv_results_path.read_text()) print(\nCross-validation Accuracy:) for model, data in cv_data.items(): if isinstance(data, dict): acc data.get(mean_cv_accuracy) if acc is not None: print(f {model}: {acc:.4f})一个成功的运行应该满足1) 运行状态为completed2) 所有阶段都被批准3) 实验结果文件显示没有执行阻塞且实验已执行4) 所有关键的产物文件结果JSON、图表、论文PDF都已生成。3.5 从Python API直接调用除了CLI你也可以直接在Python代码中集成AgentWorld。例如创建一个持久化的运行工作空间from pathlib import Path from agentworld import create_run_workspace workspace create_run_workspace( runs_dirPath(./my_runs), run_iddemo-run-001, goalDemonstrate the creation of a recoverable multi-agent research workflow., config{workflow_type: custom-analysis, version: 1.0}, ) print(fRun root: {workspace.run_root}) print(fMemory file: {workspace.memory}) # 此时文件系统中已经创建了完整的目录结构或者直接运行一个自动化研究任务from pathlib import Path from agentworld import run_auto_research result run_auto_research( goalBuild a compact evaluation report for a digit classifier on the scikit-learn digits dataset., runs_dirPath(./research_runs), approval_modevalidation-only, # 自动验证无需人工介入 permission_modeeditOnly, # 更安全的模式只允许编辑文件 max_attempts3, ) if result.success: print(fResearch completed successfully! Run saved at: {result.workspace.run_root}) print(fApproved stages: {result.approved_stages}) else: print(fResearch failed or was interrupted. Check logs in {result.workspace.run_root})这种编程式接口让你可以轻松地将AgentWorld嵌入到更大的自动化系统或Web服务中。4. 深度解析技能市场与自定义技能4.1 技能是什么为什么需要它在复杂的多智能体工作流中不同的节点往往需要不同的领域知识和行为模式。例如一个负责文献综述的智能体和一个负责代码审查的智能体它们需要的指导截然不同。传统的做法可能是为每个角色编写不同的、冗长的系统提示词但这很难维护和复用。AgentWorld的技能机制将领域指导模块化、包化。每个技能是一个独立的文件夹包含自描述的文档和可能的辅助资源。运行时可以根据节点的配置动态地将对应的技能内容注入到操作器的请求中。这带来了几个好处关注点分离系统提示词负责通用行为技能负责特定领域知识。可复用性一个写好的“论文搜索”技能可以被任何需要此功能的节点使用。可组合性一个节点可以加载多个技能获得复合能力。易于维护和分享技能可以像代码库一样被版本控制、分享和改进。4.2 内置研究技能详解项目在skills/目录下预置了五个研究导向的技能它们共同构成了一个初步的“技能市场”。技能文件夹核心目的关键指导内容research-paper-search执行前进行系统性文献检索指导智能体如何确定搜索关键词、使用哪些学术数据库如arXiv、PubMed、Google Scholar、如何记录论文IDDOI、arXiv ID、如何评估来源可靠性、以及如何整理初步的参考文献列表。它强调“证据先行”避免在缺乏文献支撑的情况下空想方案。literature-synthesis将一组论文转化为结构化知识指导智能体如何阅读论文摘要/引言/结论提取核心主张、研究方法、关键发现、支持证据如何识别不同论文间的共同主题、矛盾之处和研究空白最终输出一个结构化的综述摘要为后续的假设生成和实验设计提供依据。citation-audit审核引用和参考文献的质量指导智能体检查文内引用格式是否正确、是否所有引用都在参考文献列表中列出、参考文献条目信息作者、标题、期刊、年份、DOI是否完整准确、是否存在过度自引或引用可疑来源等问题。这对于生成严谨的学术报告至关重要。experiment-planning设计可执行的实验方案指导智能体如何将研究问题转化为具体的、可验证的假设如何选择合适的数据集、评估指标和基线模型如何设计控制变量如何规划实验步骤、预期产出和潜在风险。确保生成的计划不是空中楼阁而是可以一步步落地执行的。result-audit审核实验结果和结论的稳健性指导智能体如何检查实验结果图表是否清晰、数据是否支持文中的结论、是否与基线进行了公平比较、是否存在统计错误或过拟合迹象、结论是否夸大了结果、是否有未讨论的局限性。这是质量控制的最后一道关卡。4.3 如何在图中使用技能在构建图时你可以为每个节点指定一个技能列表。运行时会在该节点执行前自动加载这些技能的内容并将其作为上下文的一部分提供给智能体。from agentworld import AgentGraph, DefaultOperator from agentworld.controller.claude_code import ClaudeCodeController from pathlib import Path # 1. 创建控制器和操作器 claude_controller ClaudeCodeController() planner_operator DefaultOperator(research_planner, claude_controller) reviewer_operator DefaultOperator(critical_reviewer, claude_controller) # 2. 构建图 graph AgentGraph(nameskill-driven-research) # 添加操作器定义 graph.add_operator(planner, planner_operator) graph.add_operator(reviewer, reviewer_operator) # 添加节点并分配技能 graph.add_node( literature_review, operatorplanner, objectiveConduct a thorough literature review on few-shot learning for image classification., skills[research-paper-search, literature-synthesis], # 规划节点使用搜索和综述技能 roleSenior Research Scientist, ) graph.add_node( methodology_critique, operatorreviewer, objectiveCritically review the proposed methodology for flaws and improvements., skills[citation-audit, result-audit], # 审核节点使用引用和结果审核技能 rolePeer Reviewer, dependencies[literature_review], # 依赖于前一个节点完成 ) # 3. 编译并运行图 compiled_graph graph.compile() initial_state {research_topic: few-shot image classification} result compiled_graph.invoke(initial_state) print(result.state) print(fProduced artifacts: {list(result.artifacts.keys())})在这个例子中literature_review节点会获得文献搜索和综述的能力而methodology_critique节点则专注于审核。即使它们背后是同一个Claude Code模型其输出也会因技能的不同而高度专业化。4.4 创建你自己的自定义技能扩展技能市场非常简单。假设你想添加一个>mkdir -p skills/data-visualization cd skills/data-visualization创建核心的SKILL.md文件。这个文件需要包含一个YAML头frontmatter和详细的Markdown内容。--- name:>from agentworld import AgentGraph, DefaultOperator from agentworld.controller.base import StaticController, ControllerEvent from typing import Dict, Any # 1. 定义几个模拟的控制器实际应用中替换为真实的控制器 def classifier_script(request: Dict[str, Any]): # 模拟分类逻辑 text request.get(state, {}).get(article_text, ) category tech if AI in text or code in text else general return [ ControllerEvent(kindmessage_completed, payload{text: fClassified as: {category}}), ControllerEvent(kindcompleted, payload{state_patch: {article_category: category}}), ] def tech_reviewer_script(request: Dict[str, Any]): return [ ControllerEvent(kindmessage_completed, payload{text: Tech review passed. No factual errors found.}), ControllerEvent(kindcompleted, payload{state_patch: {tech_review: approved}}), ] def general_reviewer_script(request: Dict[str, Any]): return [ ControllerEvent(kindmessage_completed, payload{text: General review completed. Minor style suggestions.}), ControllerEvent(kindcompleted, payload{state_patch: {general_review: approved}}), ] # 2. 创建操作器 classifier_op DefaultOperator(classifier, StaticController(classifier_script)) tech_review_op DefaultOperator(tech_reviewer, StaticController(tech_reviewer_script)) general_review_op DefaultOperator(general_reviewer, StaticController(general_reviewer_script)) # 3. 构建图并定义条件路由 graph AgentGraph(nameconditional-review-flow) graph.add_operator(classifier, classifier_op) graph.add_operator(tech_reviewer, tech_review_op) graph.add_operator(general_reviewer, general_review_op) # 分类节点 graph.add_node( classify, operatorclassifier, objectiveRead the article text and classify it as tech or general., ) # 条件路由根据分类结果决定下一个节点 def route_by_category(state): category state.get(article_category) if category tech: return [tech_review] else: return [general_review] # 两个可能的下游审核节点 graph.add_node( tech_review, operatortech_reviewer, objectivePerform a technical review of the AI/code-related article., dependencies[classify], # 注意这里没有用 condition路由逻辑在 route_by_category 函数中体现 ) graph.add_node( general_review, operatorgeneral_reviewer, objectivePerform a general review of the article., dependencies[classify], ) # 4. 编译图时传入自定义的路由函数 compiled_graph graph.compile(routerroute_by_category) # 自定义路由逻辑 # 5. 运行 initial_state {article_text: The new AI model demonstrates breakthrough performance in code generation.} result compiled_graph.invoke(initial_state) print(fFinal state: {result.state}) # 预期输出会包含 article_category: tech 和 tech_review: approved这个例子展示了如何超越简单的线性流程构建带有条件分支的图。在实际应用中路由逻辑可以更复杂基于多个状态变量进行决策。5.2 实现一个带有人工审核关卡的流水线对于高风险任务我们可能需要在关键节点引入人工审核。AgentWorld的ApprovalGate抽象可以用于此目的但将其与自定义图运行时结合需要一些设计。一种模式是创建一个特殊的“人工审核”节点该节点使用一个会暂停并等待外部输入如通过API、Webhook或命令行的控制器。更简单的演示方式是我们可以模拟一个在状态中设置“待审核”标志并由后续节点检查该标志的流程。from agentworld import AgentGraph, DefaultOperator from agentworld.controller.base import StaticController, ControllerEvent import time def writer_script(request): # 模拟写作并标记需要审核 return [ ControllerEvent(kindmessage_completed, payload{text: Draft completed. Waiting for human approval.}), ControllerEvent(kindcompleted, payload{state_patch: {draft: This is the draft content., needs_approval: True}}), ] def human_approval_simulator_script(request): # 模拟人工审核过程例如等待5秒然后模拟批准 print([SIM] Human is reviewing the draft...) time.sleep(2) # 模拟审核耗时 # 假设审核通过 return [ ControllerEvent(kindmessage_completed, payload{text: Human approval granted.}), ControllerEvent(kindcompleted, payload{state_patch: {needs_approval: False, approved: True}}), ] def publisher_script(request): # 只有在前序节点批准后才执行发布 if request.get(state, {}).get(approved): return [ ControllerEvent(kindmessage_completed, payload{text: Content published successfully.}), ControllerEvent(kindcompleted, payload{state_patch: {published: True}}), ] else: return [ ControllerEvent(kindmessage_completed, payload{text: Publication halted: awaiting approval.}), ControllerEvent(kindcompleted, payload{state_patch: {}}), # 状态不变 ] # 构建图 graph AgentGraph(namehuman-in-the-loop) graph.add_operator(writer, DefaultOperator(writer, StaticController(writer_script))) graph.add_operator(approver, DefaultOperator(approver, StaticController(human_approval_simulator_script))) graph.add_operator(publisher, DefaultOperator(publisher, StaticController(publisher_script))) graph.add_node(write_draft, operatorwriter, objectiveWrite the initial draft.) graph.add_node(human_approval, operatorapprover, objectiveWait for human approval., dependencies[write_draft]) graph.add_node(publish, operatorpublisher, objectivePublish the approved content., dependencies[human_approval]) compiled_graph graph.compile() result compiled_graph.invoke({}) print(fFinal publication status: {result.state.get(published)})在这个模拟中publisher节点检查approved状态实现了简单的关卡逻辑。在真实场景中human_approval节点可以连接到一个真实的用户界面等待用户点击“批准”按钮后再继续流程。5.3 与外部系统集成工作空间作为接口AgentWorld文件系统原生设计的一个巨大优势是易于集成。工作空间目录 (workspace/) 是一个标准的文件夹你的其他脚本或系统可以随时读取或写入。例如你可以在一个节点中让智能体生成一个requirements.txt文件然后在图运行之外用一个传统的Python脚本去安装这些依赖。# 假设这是你的外部脚本在 AgentWorld 运行后执行 import subprocess from pathlib import Path run_root Path(/tmp/agentworld-auto-research-runs/latest_run) requirements_file run_root / workspace/code/requirements.txt if requirements_file.exists(): print(fInstalling dependencies from {requirements_file}) # 注意在生产环境中最好在虚拟环境中进行 result subprocess.run( [pip, install, -r, str(requirements_file)], capture_outputTrue, textTrue ) if result.returncode 0: print(Dependencies installed successfully.) else: print(fInstallation failed: {result.stderr}) else: print(No requirements.txt found.)同样你可以让智能体将分析结果输出为JSON或CSV文件然后由外部的数据可视化仪表板读取并展示。这种基于文件的松耦合使得AgentWorld能够轻松嵌入现有的自动化生态中。6. 故障排查、性能调优与最佳实践在实际使用中你可能会遇到各种问题。以下是一些常见问题的排查思路和优化建议。6.1 常见问题与解决方案问题现象可能原因排查步骤与解决方案运行卡在某个阶段长时间无响应1. AI提供商API超时或故障。2. 智能体陷入循环或生成了极长的输出。3. 控制器流解析出错。1. 检查网络连接和API密钥/CLI认证状态。2. 查看运行目录下的logs.txt和events.jsonl寻找错误或超时记录。3. 为run_auto_research或graph.invoke设置合理的timeout参数。4. 考虑在技能或节点目标中添加更明确的约束防止智能体“跑偏”。阶段未能批准 (approved: false)1. 产物验证失败如缺少必需文件。2. 自动验证逻辑检查未通过如实验被标记为未执行。3. 人工审核被拒绝如果使用manual模式。1. 检查run_manifest.json中该阶段的validation_errors字段。2. 查看工作空间确认智能体是否生成了符合ArtifactRequirement定义的文件。3. 如果使用validation-only模式检查验证函数的逻辑。对于实验阶段确保permission_mode允许代码执行。ClaudeCodeController报错如ClaudeCLIError1.claudeCLI未安装或不在PATH中。2. Claude Code会话认证失败或已过期。3. Claude Code服务本身临时不可用。1. 在终端运行which claude和claude --version确认CLI可用。2. 运行claude auth status检查认证。3. 尝试直接运行一个简单的claude命令看是否正常交互。4. 查看控制器生成的原始命令和输出可能在logs_raw/目录下。技能未按预期生效1. 技能文件夹名称拼写错误。2.SKILL.md文件格式错误如缺少YAML头。3. 技能内容未被正确注入到请求中。1. 确认skills/目录下存在对应名称的文件夹。2. 检查SKILL.md文件确保---分隔的YAML头格式正确。3. 在节点的请求日志中如果开启了详细日志搜索技能名称看其内容是否出现。运行恢复 (--resume-run) 后行为异常1. 运行状态文件 (run_manifest.json,operator_state/) 在手动恢复过程中被损坏。2. 外部依赖如技能定义、控制器配置在两次运行间发生了变化。1.恢复运行是高级功能确保没有手动修改过运行目录内的状态文件。2. 恢复时系统会尝试从检查点继续。如果问题持续考虑放弃该次运行从干净状态重新开始。3. 对于关键任务建议将完整的运行目录进行备份后再尝试恢复操作。产物索引 (artifact_index.json) 为空或不准确1.scan_artifacts函数扫描的目录路径不正确。2. 文件生成在预期目录之外。3. 文件格式无法被识别或解析。1. 确认scan_artifacts被调用时传入的workspace_root路径正确。2. 检查智能体生成的文件是否确实在workspace/的子目录下如workspace/results/,workspace/figures/。3. 产物扫描目前主要针对JSON、文本、图像等常见格式。对于特殊二进制文件可能需要扩展扫描逻辑。6.2 性能调优建议合理设置超时和重试通过--timeout和--max-attempts(或对应的API参数) 控制单个运行和单个阶段的生命周期。对于已知不稳定的步骤如网络请求可以设置更多重试次数。利用提示词缓存AgentWorld在prompt_cache/目录下缓存编译后的提示词。在开发阶段如果频繁修改技能或节点目标可以临时清空此缓存或禁用缓存以确保更改生效。在生产环境缓存能显著提升性能。优化技能设计技能指令应精炼、具体。过于冗长的技能会消耗大量上下文窗口增加API调用成本和延迟。将通用的、不变的知识放在系统提示词中将情境化的、具体的指导放在技能里。选择适当的权限模式bypassPermissions功能最全但风险最高。仅在完全信任智能体且环境隔离的情况下使用。editOnly推荐用于大多数内容生成任务。允许创建、编辑、删除文件但阻止执行命令。更安全但限制了需要代码执行的阶段。更严格的模式你可以基于editOnly实现更细粒度的沙箱例如只允许写入特定目录。分阶段运行与检查点对于超长工作流可以设计成多个独立的子运行每个子运行完成一个大的里程碑。利用AgentWorld本身的检查点机制也可以在关键阶段后手动保存状态便于分段调试和问题隔离。6.3 开发与调试最佳实践从小图开始不要一开始就构建复杂的多节点图。从planner_coder_reviewer.py这样的单控制器、模拟控制器示例开始确保你理解了图编译、节点执行、状态合并的基本流程。善用日志运行目录下的logs.txt提供了高级别的时间线信息而events.jsonl则包含了更原始的运行时事件。在调试时结合两者可以清晰地看到执行流和问题发生点。检查工作空间当智能体的行为不符合预期时第一件事就是去检查workspace/目录。看看它到底生成了什么文件文件内容是什么。这比分析日志更直接。使用静态控制器进行单元测试在为你自定义的图或工作流编写测试时使用StaticController来模拟智能体的响应。这可以让你在不依赖真实AI API的情况下验证你的业务逻辑、状态转换和路由是否正确。版本控制你的技能和工作流定义将skills/目录和你自定义的工作流构建脚本纳入版本控制如Git。这确保了实验的可复现性并方便团队协作。7. 展望与扩展平台生态的构建AgentWorld将自己定位为一个平台基础其路线图也指向了一个更广阔的生态系统。基于当前的基础我们可以预见和探索几个重要的扩展方向。7.1 控制器生态的扩展目前ClaudeCodeController是唯一完全实现的控制器。Codex和OpenClaw的控制器的实现将极大地扩展平台的适用范围。除此之外社区完全可以贡献更多控制器例如本地模型控制器集成像 Llama、CodeLlama 这样的本地大语言模型通过Ollama、vLLM等接口调用。多模态控制器支持接收图像、音频等输入并调用相应的多模态模型。工具增强控制器将外部工具API如数据库查询、云服务操作更紧密地封装成控制器的能力。每个新控制器的集成都意味着AgentWorld能调度一类新的“强智能体”。7.2 技能市场的繁荣当前的技能市场只是一个雏形。一个繁荣的技能平台可能需要技能元数据与搜索为技能添加更丰富的元数据类别、输入/输出格式、适用模型、作者、版本并支持搜索和发现。技能依赖与组合允许技能声明依赖关系例如“数据可视化”技能可能依赖“数据分析”技能产出的特定格式的JSON。技能版本管理与测试像管理软件包一样管理技能版本并提供自动化测试来验证技能的有效性。社区贡献与审核建立一个机制让社区用户可以提交、分享和审核技能。7.3 基准测试与评估体系要推动强智能体工作流的发展一个客观的评估体系必不可少。AgentWorld可以发展出基准测试原语用于定义基准任务一系列标准化的、可评估的任务如“完成一个端到端的机器学习研究项目”、“修复一个包含多个文件的Bug”。自动化评分根据任务目标自动评估运行产物的质量代码正确性、报告完整性、实验严谨性等。生成排行榜比较不同智能体、不同技能组合、不同工作流在相同任务上的表现。这将使AgentWorld不仅是一个构建工具也是一个衡量工具推动整个领域向更可靠、更高效的方向发展。7.4 应用层的创新在AgentWorld提供的稳固基础之上可以构建无数具体的应用自动化研究助手如当前的AutoR用例但可以扩展到更多学科生物、化学、物理。智能代码审查与重构构建一个多智能体流水线自动进行代码质量检查、安全扫描、性能分析和重构建议。自动化内容运营从热点追踪、素材搜集、内容创作、多平台发布到效果分析形成一个闭环的智能内容流水线。教育领域的个性化辅导根据学生的学习数据和问题自动生成个性化的学习路径、练习题目和讲解。这些应用的共同点是都需要可编排的、有状态的、能产生持久化副作用的智能体而这正是AgentWorld所擅长的。我个人在实际使用和探索AgentWorld的过程中最深刻的体会是它将智能体系统的“不确定性”与软件工程的“确定性”做了很好的结合。智能体的创造性输出仍然是不确定的但整个工作流的编排、状态管理、错误恢复、产物追踪变得确定且可控。这种结合使得构建可靠的、可用于生产环境的智能体应用不再是遥不可及的想法。如果你正在严肃地考虑将AI智能体集成到你的核心业务流程中AgentWorld所提供的这套基于文件系统原生的、可恢复的、技能化的架构范式是一个非常值得深入研究和投资的起点。 AgentWorld：构建文件系统原生、可恢复的强智能体工作流平台
1. 项目概述构建文件系统原生的强智能体工作流平台如果你正在尝试构建一个能真正“运行”的智能体系统而不仅仅是调用API那么你很可能已经遇到了一个核心矛盾现有的很多框架把重点放在了“模型能调用什么”上却忽略了智能体作为一个执行单元需要一个真实的会话、一个持久的工作目录、一套权限模型、有副作用的工具调用以及与其他智能体在同一个系统内协作的能力。这正是AgentWorld这个Python包试图解决的底层问题。它不是一个顶层的应用而是一个位于应用之下的平台层为构建像AutoR那样的自动化研究系统或者任何需要强智能体协作的工作流和组织提供可复用的基础构件。简单来说AgentWorld提供了一套“乐高积木”让你可以搭建一个文件系统原生、状态可恢复、执行可追踪的智能体工作流。它的核心设计理念是执行优先这意味着它从第一天起就考虑了智能体在实际运行中会遇到的所有“脏活累活”会话管理、工作空间隔离、检查点、状态回滚、跨阶段交接、产物验证等等。这听起来可能有点抽象但当你需要让一个智能体去执行一段代码、生成一份报告并让另一个智能体去审核这份报告时这些“脏活累活”就成了决定系统能否稳定运行的关键。这个项目目前聚焦于平台的基础层实现包括控制器、操作器、明确的A2A智能体到智能体协议、图运行时、工作空间、清单、阶段、产物等一系列原语。你可以把它看作是智能体世界的“操作系统内核”而具体的应用如自动化研究则是运行在这个内核之上的“应用程序”。注意AgentWorld与许多“提示词编排”框架有本质区别。它不假设智能体只是无状态的文本生成器而是将其视为有状态、可交互、能产生持久化副作用的执行单元。这种设计选择使得它特别适合需要严谨流程、可审计性和可恢复性的生产级场景。2. 核心设计理念与架构拆解2.1 为什么需要“文件系统原生”在传统的智能体编排中状态管理常常是个难题。状态可能存储在内存里、数据库里或者分散在各个提示词的上下文窗口中。AgentWorld选择了一个看似朴素但极其强大的方案将一切状态显式地持久化到文件系统中。每个运行Run都有一个独立的根目录里面包含了目标描述、运行配置、内存记录、阶段清单、产物索引、操作器状态以及实际的工作空间。这种设计带来了几个关键优势可观测性与可调试性你可以直接打开运行目录查看每个阶段生成了什么文件智能体做了什么决策状态是如何演变的。这对于调试复杂的工作流至关重要。可恢复性运行可以被中断、暂停然后从任意一个已完成检查点的阶段恢复。运行时通过维护run_manifest.json等清单文件来跟踪进度和状态。强一致性产物Artifact不再是模糊的文本描述而是文件系统中实实在在的文件。系统可以通过扫描文件并生成artifact_index.json来推断产物模式并进行验证。与现有工具链集成文件是通用的接口。其他脚本、CI/CD流水线、版本控制系统都可以直接与AgentWorld生成的工作空间交互。2.2 核心组件边界与职责AgentWorld的架构清晰地划分了不同组件的职责避免了常见的“上帝对象”问题。理解这些边界是有效使用它的关键。2.2.1 控制器与具体AI提供商的边界控制器是平台与外部AI世界如Claude Code、Codex交互的桥梁。它的职责非常具体会话生命周期管理创建、维持和销毁与特定AI模型的会话。工具策略映射将平台统一的工具调用规范转换为特定AI提供商能理解的格式例如将“执行Python脚本”映射为Claude Code的run_command工具。流式响应解析实时解析AI返回的流式事件如message_start,tool_call,message_completed并将其标准化为平台内部的ControllerEvent。这种隔离意味着如果你想支持一个新的AI模型比如GPT-4 Code Interpreter你只需要实现一个新的控制器而无需改动上层的操作器、运行时或工作流逻辑。项目目前已经实现了ClaudeCodeController并为CodexController和OpenClawController预留了接口。2.2.2 操作器统一的执行单元抽象操作器是控制器之上的抽象层。它定义了一个智能体“节点”应该如何被调用。其核心职责包括组装请求根据节点的目标、角色、技能列表以及当前运行状态组装出发送给控制器的标准化请求。加载技能从本地的技能市场skills/目录动态加载并注入特定领域的指导。规范化输出将控制器返回的原始事件转换为平台内部的结构化消息、工具结果、交接物和状态补丁。DefaultOperator和StageOperator是两种主要的操作器实现。前者用于通用的图节点后者专门用于具有固定合约起草、修复、审核、终版的“阶段”。2.2.3 技能可复用的领域指导模块技能是AgentWorld一个非常巧妙的抽象。它不是一个营销标签而是一个实实在在的、可加载的执行指导包。每个技能是一个文件夹通常包含一个SKILL.md文件里面描述了该技能的使用时机、工作流程、参考案例等。例如research-paper-search技能会指导智能体在开始执行前如何系统地搜索相关论文、数据库和证据链。你可以为工作流中不同的节点分配不同的技能组合。比如“规划者”节点可能加载research-paper-search和experiment-planning技能而“审核者”节点则加载citation-audit和result-audit技能。这样即使它们使用同一个底层的AI模型通过同一个控制器也能表现出完全不同的领域专长和行为模式。2.2.4 A2A协议结构化的智能体间通信智能体之间如何通信很多框架依赖于在提示词里拼接上下文这既脆弱又难以追踪。AgentWorld定义了一个明确的A2A协议规定了智能体间传递的消息、工具调用结果、阶段交接物、产物引用等都必须采用结构化的形式。这确保了通信的可靠性和可追溯性为图运行时进行状态合并和路由决策提供了清晰的数据基础。2.2.5 图运行时调度与状态管理的引擎图运行时是当前最具体的编排子系统但请注意AgentWorld的范围比图运行时更广。它负责节点调度决定下一个执行哪个节点。状态合并将一个节点的输出状态补丁合并到全局运行状态中。检查点与持久化在关键节点后保存运行状态支持恢复和回滚。执行追踪记录所有事件形成完整的执行轨迹。运行时确保了整个工作流的执行是可控、可中断、可恢复的。2.3 与AutoR类应用的关系AgentWorld明确将自己定位在像AutoR这样的具体应用之下。一个AutoR风格的自动化研究系统需要什么它需要一个固定的研究阶段流水线如规划、假设、设计、编码、实验、分析、写作、发布每个阶段都需要起草、审核、产出最终产物并且阶段之间需要有批准的“记忆”进行交接。AgentWorld现在提供的就是构建这类系统所需的所有可复用原语RunWorkspace提供了持久的运行目录。StageSpec和StageOperator定义了阶段合约和执行逻辑。ApprovalGate实现了人工或自动化的审核关卡。append_approved_stage_summary和write_stage_handoff管理着阶段间的记忆传递。scan_artifacts和write_artifact_index负责产物的扫描和验证。examples/auto-research目录下的参考实现完整地演示了如何用AgentWorld的积木搭建出一个八阶段的AutoR式工作流而无需复制或修改AutoR本身的代码。这证明了其作为平台层的有效性和灵活性。3. 从零开始快速上手与核心实操3.1 环境准备与安装首先你需要一个Python 3.11的环境。我强烈建议使用虚拟环境来管理依赖避免污染全局环境。# 克隆仓库 git clone https://github.com/ScienceIntelligence/AgentWorld.git cd AgentWorld # 创建并激活虚拟环境以venv为例 python -m venv .venv source .venv/bin/activate # Linux/macOS # .venv\Scripts\activate # Windows # 以可编辑模式安装包及其依赖 python -m pip install -e .安装完成后运行测试套件是一个好习惯可以确保一切基本功能正常。python -m unittest discover -s tests -v3.2 运行你的第一个智能体图项目提供了一个简单的“规划者-编码者-审核者”顺序图示例。这个例子不依赖任何真实的AI控制器而是使用一个模拟的静态控制器非常适合用来理解图运行时的工作机制。python examples/planner_coder_reviewer.py运行这个脚本你会看到控制台输出展示了图的编译、节点的顺序执行、状态的合并以及产物的创建。这是理解AgentGraph、DefaultOperator和运行时交互的绝佳起点。3.3 体验真实的AutoR式研究流程要运行一个真正“完整”的用例你需要一个能实际执行代码的强智能体。AgentWorld默认集成了ClaudeCodeController它需要你本地安装并认证好Claude Code CLI工具。实操心得在运行真实用例前务必确认你的claudeCLI已正确安装且认证有效。可以运行claude --version和claude auth status来验证。网络环境也可能影响Claude Code的调用请确保稳定的连接。以下命令将启动一个完整的自动化研究流程目标是构建并评估一个手写数字分类模型python examples/auto-research/run.py \ --runs-dir /tmp/agentworld-auto-research-runs \ --approval-mode validation-only \ --permission-mode bypassPermissions \ --max-attempts 2 \ --timeout 7200 \ Build and evaluate a handwritten digit classification model on the scikit-learn digits dataset. Train SVM-RBF, RandomForest, kNN, LogisticRegression, and DecisionTree baselines. The experiment stage must actually execute the Python training script and produce real cross-validation results, held-out test results, confusion matrices, hypothesis verdicts, figures, and a paper-style report. Do not use predicted or literature-only results as a substitute for execution.让我拆解一下这些参数--runs-dir指定运行目录的根路径。所有运行都会作为子目录创建在这里。--approval-mode validation-only这是一个关键设置。它意味着跳过人工审核提示完全依靠系统对阶段产物的自动验证来决定是否批准该阶段。这对于自动化流水线至关重要。--permission-mode bypassPermissions这个模式允许智能体在工作空间内执行命令如运行Python脚本。请注意这仅在受信任的环境中使用。对于更安全的场景可以使用editOnly模式它只允许文件编辑阻止命令执行。--max-attempts 2每个阶段最多重试修复的次数。--timeout 7200整个运行的总超时时间秒。最后的长字符串是本次运行的“目标”它会被写入goal.md并作为整个工作流的起点。运行开始后CLI会实时打印运行状态、阶段进展、Claude会话活动、工具调用、验证结果和修复尝试。如果你只想看最终结果可以加上--quiet参数。3.4 验证运行结果与产物运行结束后如何判断它是否真正成功不能只看run_manifest.json里的run_status: completed。因为即使流程走完了实验也可能因为权限问题而未能实际执行。我们必须检查具体的产物。首先找到最新的运行目录RUN_ROOT$(ls -td /tmp/agentworld-auto-research-runs/* | head -1) echo $RUN_ROOT然后我们可以编写一个简单的Python脚本来进行系统性的验证import json from pathlib import Path run_root Path(RUN_ROOT) # 1. 检查运行清单 manifest_path run_root / run_manifest.json if not manifest_path.exists(): raise FileNotFoundError(Run manifest not found.) manifest json.loads(manifest_path.read_text()) print(fRun ID: {manifest.get(run_id)}) print(fRun Status: {manifest.get(run_status)}) print(fStages Approved: {sum(1 for s in manifest[stages] if s[approved])} / {len(manifest[stages])}) if manifest[run_status] ! completed: raise ValueError(Run did not complete successfully.) # 2. 检查实验结果文件 results_path run_root / workspace/results/results.json if not results_path.exists(): raise FileNotFoundError(Core results file not found.) results json.loads(results_path.read_text()) # 关键执行标记 if results.get(execution_blocker): raise ValueError(fExecution was blocked: {results[execution_blocker]}) if results.get(experiments_executed) is False: raise ValueError(Experiments were not executed (marked as false).) if results.get(exit_code) not in (0, None): raise ValueError(fExperiment script exited with code: {results[exit_code]}) # 3. 检查必需产物是否存在 required_artifacts [ workspace/results/results.json, workspace/results/cv_results.json, workspace/results/test_results.json, workspace/results/hypothesis_verdicts.json, workspace/figures/accuracy_comparison.png, workspace/figures/confusion_matrices.png, workspace/writing/main.tex, workspace/artifacts/paper.pdf, ] missing [art for art in required_artifacts if not (run_root / art).exists()] if missing: print(WARNING: Missing some artifacts:, missing) else: print(SUCCESS: All core artifacts present.) # 4. 可选检查一些具体指标例如交叉验证精度 cv_results_path run_root / workspace/results/cv_results.json if cv_results_path.exists(): cv_data json.loads(cv_results_path.read_text()) print(\nCross-validation Accuracy:) for model, data in cv_data.items(): if isinstance(data, dict): acc data.get(mean_cv_accuracy) if acc is not None: print(f {model}: {acc:.4f})一个成功的运行应该满足1) 运行状态为completed2) 所有阶段都被批准3) 实验结果文件显示没有执行阻塞且实验已执行4) 所有关键的产物文件结果JSON、图表、论文PDF都已生成。3.5 从Python API直接调用除了CLI你也可以直接在Python代码中集成AgentWorld。例如创建一个持久化的运行工作空间from pathlib import Path from agentworld import create_run_workspace workspace create_run_workspace( runs_dirPath(./my_runs), run_iddemo-run-001, goalDemonstrate the creation of a recoverable multi-agent research workflow., config{workflow_type: custom-analysis, version: 1.0}, ) print(fRun root: {workspace.run_root}) print(fMemory file: {workspace.memory}) # 此时文件系统中已经创建了完整的目录结构或者直接运行一个自动化研究任务from pathlib import Path from agentworld import run_auto_research result run_auto_research( goalBuild a compact evaluation report for a digit classifier on the scikit-learn digits dataset., runs_dirPath(./research_runs), approval_modevalidation-only, # 自动验证无需人工介入 permission_modeeditOnly, # 更安全的模式只允许编辑文件 max_attempts3, ) if result.success: print(fResearch completed successfully! Run saved at: {result.workspace.run_root}) print(fApproved stages: {result.approved_stages}) else: print(fResearch failed or was interrupted. Check logs in {result.workspace.run_root})这种编程式接口让你可以轻松地将AgentWorld嵌入到更大的自动化系统或Web服务中。4. 深度解析技能市场与自定义技能4.1 技能是什么为什么需要它在复杂的多智能体工作流中不同的节点往往需要不同的领域知识和行为模式。例如一个负责文献综述的智能体和一个负责代码审查的智能体它们需要的指导截然不同。传统的做法可能是为每个角色编写不同的、冗长的系统提示词但这很难维护和复用。AgentWorld的技能机制将领域指导模块化、包化。每个技能是一个独立的文件夹包含自描述的文档和可能的辅助资源。运行时可以根据节点的配置动态地将对应的技能内容注入到操作器的请求中。这带来了几个好处关注点分离系统提示词负责通用行为技能负责特定领域知识。可复用性一个写好的“论文搜索”技能可以被任何需要此功能的节点使用。可组合性一个节点可以加载多个技能获得复合能力。易于维护和分享技能可以像代码库一样被版本控制、分享和改进。4.2 内置研究技能详解项目在skills/目录下预置了五个研究导向的技能它们共同构成了一个初步的“技能市场”。技能文件夹核心目的关键指导内容research-paper-search执行前进行系统性文献检索指导智能体如何确定搜索关键词、使用哪些学术数据库如arXiv、PubMed、Google Scholar、如何记录论文IDDOI、arXiv ID、如何评估来源可靠性、以及如何整理初步的参考文献列表。它强调“证据先行”避免在缺乏文献支撑的情况下空想方案。literature-synthesis将一组论文转化为结构化知识指导智能体如何阅读论文摘要/引言/结论提取核心主张、研究方法、关键发现、支持证据如何识别不同论文间的共同主题、矛盾之处和研究空白最终输出一个结构化的综述摘要为后续的假设生成和实验设计提供依据。citation-audit审核引用和参考文献的质量指导智能体检查文内引用格式是否正确、是否所有引用都在参考文献列表中列出、参考文献条目信息作者、标题、期刊、年份、DOI是否完整准确、是否存在过度自引或引用可疑来源等问题。这对于生成严谨的学术报告至关重要。experiment-planning设计可执行的实验方案指导智能体如何将研究问题转化为具体的、可验证的假设如何选择合适的数据集、评估指标和基线模型如何设计控制变量如何规划实验步骤、预期产出和潜在风险。确保生成的计划不是空中楼阁而是可以一步步落地执行的。result-audit审核实验结果和结论的稳健性指导智能体如何检查实验结果图表是否清晰、数据是否支持文中的结论、是否与基线进行了公平比较、是否存在统计错误或过拟合迹象、结论是否夸大了结果、是否有未讨论的局限性。这是质量控制的最后一道关卡。4.3 如何在图中使用技能在构建图时你可以为每个节点指定一个技能列表。运行时会在该节点执行前自动加载这些技能的内容并将其作为上下文的一部分提供给智能体。from agentworld import AgentGraph, DefaultOperator from agentworld.controller.claude_code import ClaudeCodeController from pathlib import Path # 1. 创建控制器和操作器 claude_controller ClaudeCodeController() planner_operator DefaultOperator(research_planner, claude_controller) reviewer_operator DefaultOperator(critical_reviewer, claude_controller) # 2. 构建图 graph AgentGraph(nameskill-driven-research) # 添加操作器定义 graph.add_operator(planner, planner_operator) graph.add_operator(reviewer, reviewer_operator) # 添加节点并分配技能 graph.add_node( literature_review, operatorplanner, objectiveConduct a thorough literature review on few-shot learning for image classification., skills[research-paper-search, literature-synthesis], # 规划节点使用搜索和综述技能 roleSenior Research Scientist, ) graph.add_node( methodology_critique, operatorreviewer, objectiveCritically review the proposed methodology for flaws and improvements., skills[citation-audit, result-audit], # 审核节点使用引用和结果审核技能 rolePeer Reviewer, dependencies[literature_review], # 依赖于前一个节点完成 ) # 3. 编译并运行图 compiled_graph graph.compile() initial_state {research_topic: few-shot image classification} result compiled_graph.invoke(initial_state) print(result.state) print(fProduced artifacts: {list(result.artifacts.keys())})在这个例子中literature_review节点会获得文献搜索和综述的能力而methodology_critique节点则专注于审核。即使它们背后是同一个Claude Code模型其输出也会因技能的不同而高度专业化。4.4 创建你自己的自定义技能扩展技能市场非常简单。假设你想添加一个>mkdir -p skills/data-visualization cd skills/data-visualization创建核心的SKILL.md文件。这个文件需要包含一个YAML头frontmatter和详细的Markdown内容。--- name:>from agentworld import AgentGraph, DefaultOperator from agentworld.controller.base import StaticController, ControllerEvent from typing import Dict, Any # 1. 定义几个模拟的控制器实际应用中替换为真实的控制器 def classifier_script(request: Dict[str, Any]): # 模拟分类逻辑 text request.get(state, {}).get(article_text, ) category tech if AI in text or code in text else general return [ ControllerEvent(kindmessage_completed, payload{text: fClassified as: {category}}), ControllerEvent(kindcompleted, payload{state_patch: {article_category: category}}), ] def tech_reviewer_script(request: Dict[str, Any]): return [ ControllerEvent(kindmessage_completed, payload{text: Tech review passed. No factual errors found.}), ControllerEvent(kindcompleted, payload{state_patch: {tech_review: approved}}), ] def general_reviewer_script(request: Dict[str, Any]): return [ ControllerEvent(kindmessage_completed, payload{text: General review completed. Minor style suggestions.}), ControllerEvent(kindcompleted, payload{state_patch: {general_review: approved}}), ] # 2. 创建操作器 classifier_op DefaultOperator(classifier, StaticController(classifier_script)) tech_review_op DefaultOperator(tech_reviewer, StaticController(tech_reviewer_script)) general_review_op DefaultOperator(general_reviewer, StaticController(general_reviewer_script)) # 3. 构建图并定义条件路由 graph AgentGraph(nameconditional-review-flow) graph.add_operator(classifier, classifier_op) graph.add_operator(tech_reviewer, tech_review_op) graph.add_operator(general_reviewer, general_review_op) # 分类节点 graph.add_node( classify, operatorclassifier, objectiveRead the article text and classify it as tech or general., ) # 条件路由根据分类结果决定下一个节点 def route_by_category(state): category state.get(article_category) if category tech: return [tech_review] else: return [general_review] # 两个可能的下游审核节点 graph.add_node( tech_review, operatortech_reviewer, objectivePerform a technical review of the AI/code-related article., dependencies[classify], # 注意这里没有用 condition路由逻辑在 route_by_category 函数中体现 ) graph.add_node( general_review, operatorgeneral_reviewer, objectivePerform a general review of the article., dependencies[classify], ) # 4. 编译图时传入自定义的路由函数 compiled_graph graph.compile(routerroute_by_category) # 自定义路由逻辑 # 5. 运行 initial_state {article_text: The new AI model demonstrates breakthrough performance in code generation.} result compiled_graph.invoke(initial_state) print(fFinal state: {result.state}) # 预期输出会包含 article_category: tech 和 tech_review: approved这个例子展示了如何超越简单的线性流程构建带有条件分支的图。在实际应用中路由逻辑可以更复杂基于多个状态变量进行决策。5.2 实现一个带有人工审核关卡的流水线对于高风险任务我们可能需要在关键节点引入人工审核。AgentWorld的ApprovalGate抽象可以用于此目的但将其与自定义图运行时结合需要一些设计。一种模式是创建一个特殊的“人工审核”节点该节点使用一个会暂停并等待外部输入如通过API、Webhook或命令行的控制器。更简单的演示方式是我们可以模拟一个在状态中设置“待审核”标志并由后续节点检查该标志的流程。from agentworld import AgentGraph, DefaultOperator from agentworld.controller.base import StaticController, ControllerEvent import time def writer_script(request): # 模拟写作并标记需要审核 return [ ControllerEvent(kindmessage_completed, payload{text: Draft completed. Waiting for human approval.}), ControllerEvent(kindcompleted, payload{state_patch: {draft: This is the draft content., needs_approval: True}}), ] def human_approval_simulator_script(request): # 模拟人工审核过程例如等待5秒然后模拟批准 print([SIM] Human is reviewing the draft...) time.sleep(2) # 模拟审核耗时 # 假设审核通过 return [ ControllerEvent(kindmessage_completed, payload{text: Human approval granted.}), ControllerEvent(kindcompleted, payload{state_patch: {needs_approval: False, approved: True}}), ] def publisher_script(request): # 只有在前序节点批准后才执行发布 if request.get(state, {}).get(approved): return [ ControllerEvent(kindmessage_completed, payload{text: Content published successfully.}), ControllerEvent(kindcompleted, payload{state_patch: {published: True}}), ] else: return [ ControllerEvent(kindmessage_completed, payload{text: Publication halted: awaiting approval.}), ControllerEvent(kindcompleted, payload{state_patch: {}}), # 状态不变 ] # 构建图 graph AgentGraph(namehuman-in-the-loop) graph.add_operator(writer, DefaultOperator(writer, StaticController(writer_script))) graph.add_operator(approver, DefaultOperator(approver, StaticController(human_approval_simulator_script))) graph.add_operator(publisher, DefaultOperator(publisher, StaticController(publisher_script))) graph.add_node(write_draft, operatorwriter, objectiveWrite the initial draft.) graph.add_node(human_approval, operatorapprover, objectiveWait for human approval., dependencies[write_draft]) graph.add_node(publish, operatorpublisher, objectivePublish the approved content., dependencies[human_approval]) compiled_graph graph.compile() result compiled_graph.invoke({}) print(fFinal publication status: {result.state.get(published)})在这个模拟中publisher节点检查approved状态实现了简单的关卡逻辑。在真实场景中human_approval节点可以连接到一个真实的用户界面等待用户点击“批准”按钮后再继续流程。5.3 与外部系统集成工作空间作为接口AgentWorld文件系统原生设计的一个巨大优势是易于集成。工作空间目录 (workspace/) 是一个标准的文件夹你的其他脚本或系统可以随时读取或写入。例如你可以在一个节点中让智能体生成一个requirements.txt文件然后在图运行之外用一个传统的Python脚本去安装这些依赖。# 假设这是你的外部脚本在 AgentWorld 运行后执行 import subprocess from pathlib import Path run_root Path(/tmp/agentworld-auto-research-runs/latest_run) requirements_file run_root / workspace/code/requirements.txt if requirements_file.exists(): print(fInstalling dependencies from {requirements_file}) # 注意在生产环境中最好在虚拟环境中进行 result subprocess.run( [pip, install, -r, str(requirements_file)], capture_outputTrue, textTrue ) if result.returncode 0: print(Dependencies installed successfully.) else: print(fInstallation failed: {result.stderr}) else: print(No requirements.txt found.)同样你可以让智能体将分析结果输出为JSON或CSV文件然后由外部的数据可视化仪表板读取并展示。这种基于文件的松耦合使得AgentWorld能够轻松嵌入现有的自动化生态中。6. 故障排查、性能调优与最佳实践在实际使用中你可能会遇到各种问题。以下是一些常见问题的排查思路和优化建议。6.1 常见问题与解决方案问题现象可能原因排查步骤与解决方案运行卡在某个阶段长时间无响应1. AI提供商API超时或故障。2. 智能体陷入循环或生成了极长的输出。3. 控制器流解析出错。1. 检查网络连接和API密钥/CLI认证状态。2. 查看运行目录下的logs.txt和events.jsonl寻找错误或超时记录。3. 为run_auto_research或graph.invoke设置合理的timeout参数。4. 考虑在技能或节点目标中添加更明确的约束防止智能体“跑偏”。阶段未能批准 (approved: false)1. 产物验证失败如缺少必需文件。2. 自动验证逻辑检查未通过如实验被标记为未执行。3. 人工审核被拒绝如果使用manual模式。1. 检查run_manifest.json中该阶段的validation_errors字段。2. 查看工作空间确认智能体是否生成了符合ArtifactRequirement定义的文件。3. 如果使用validation-only模式检查验证函数的逻辑。对于实验阶段确保permission_mode允许代码执行。ClaudeCodeController报错如ClaudeCLIError1.claudeCLI未安装或不在PATH中。2. Claude Code会话认证失败或已过期。3. Claude Code服务本身临时不可用。1. 在终端运行which claude和claude --version确认CLI可用。2. 运行claude auth status检查认证。3. 尝试直接运行一个简单的claude命令看是否正常交互。4. 查看控制器生成的原始命令和输出可能在logs_raw/目录下。技能未按预期生效1. 技能文件夹名称拼写错误。2.SKILL.md文件格式错误如缺少YAML头。3. 技能内容未被正确注入到请求中。1. 确认skills/目录下存在对应名称的文件夹。2. 检查SKILL.md文件确保---分隔的YAML头格式正确。3. 在节点的请求日志中如果开启了详细日志搜索技能名称看其内容是否出现。运行恢复 (--resume-run) 后行为异常1. 运行状态文件 (run_manifest.json,operator_state/) 在手动恢复过程中被损坏。2. 外部依赖如技能定义、控制器配置在两次运行间发生了变化。1.恢复运行是高级功能确保没有手动修改过运行目录内的状态文件。2. 恢复时系统会尝试从检查点继续。如果问题持续考虑放弃该次运行从干净状态重新开始。3. 对于关键任务建议将完整的运行目录进行备份后再尝试恢复操作。产物索引 (artifact_index.json) 为空或不准确1.scan_artifacts函数扫描的目录路径不正确。2. 文件生成在预期目录之外。3. 文件格式无法被识别或解析。1. 确认scan_artifacts被调用时传入的workspace_root路径正确。2. 检查智能体生成的文件是否确实在workspace/的子目录下如workspace/results/,workspace/figures/。3. 产物扫描目前主要针对JSON、文本、图像等常见格式。对于特殊二进制文件可能需要扩展扫描逻辑。6.2 性能调优建议合理设置超时和重试通过--timeout和--max-attempts(或对应的API参数) 控制单个运行和单个阶段的生命周期。对于已知不稳定的步骤如网络请求可以设置更多重试次数。利用提示词缓存AgentWorld在prompt_cache/目录下缓存编译后的提示词。在开发阶段如果频繁修改技能或节点目标可以临时清空此缓存或禁用缓存以确保更改生效。在生产环境缓存能显著提升性能。优化技能设计技能指令应精炼、具体。过于冗长的技能会消耗大量上下文窗口增加API调用成本和延迟。将通用的、不变的知识放在系统提示词中将情境化的、具体的指导放在技能里。选择适当的权限模式bypassPermissions功能最全但风险最高。仅在完全信任智能体且环境隔离的情况下使用。editOnly推荐用于大多数内容生成任务。允许创建、编辑、删除文件但阻止执行命令。更安全但限制了需要代码执行的阶段。更严格的模式你可以基于editOnly实现更细粒度的沙箱例如只允许写入特定目录。分阶段运行与检查点对于超长工作流可以设计成多个独立的子运行每个子运行完成一个大的里程碑。利用AgentWorld本身的检查点机制也可以在关键阶段后手动保存状态便于分段调试和问题隔离。6.3 开发与调试最佳实践从小图开始不要一开始就构建复杂的多节点图。从planner_coder_reviewer.py这样的单控制器、模拟控制器示例开始确保你理解了图编译、节点执行、状态合并的基本流程。善用日志运行目录下的logs.txt提供了高级别的时间线信息而events.jsonl则包含了更原始的运行时事件。在调试时结合两者可以清晰地看到执行流和问题发生点。检查工作空间当智能体的行为不符合预期时第一件事就是去检查workspace/目录。看看它到底生成了什么文件文件内容是什么。这比分析日志更直接。使用静态控制器进行单元测试在为你自定义的图或工作流编写测试时使用StaticController来模拟智能体的响应。这可以让你在不依赖真实AI API的情况下验证你的业务逻辑、状态转换和路由是否正确。版本控制你的技能和工作流定义将skills/目录和你自定义的工作流构建脚本纳入版本控制如Git。这确保了实验的可复现性并方便团队协作。7. 展望与扩展平台生态的构建AgentWorld将自己定位为一个平台基础其路线图也指向了一个更广阔的生态系统。基于当前的基础我们可以预见和探索几个重要的扩展方向。7.1 控制器生态的扩展目前ClaudeCodeController是唯一完全实现的控制器。Codex和OpenClaw的控制器的实现将极大地扩展平台的适用范围。除此之外社区完全可以贡献更多控制器例如本地模型控制器集成像 Llama、CodeLlama 这样的本地大语言模型通过Ollama、vLLM等接口调用。多模态控制器支持接收图像、音频等输入并调用相应的多模态模型。工具增强控制器将外部工具API如数据库查询、云服务操作更紧密地封装成控制器的能力。每个新控制器的集成都意味着AgentWorld能调度一类新的“强智能体”。7.2 技能市场的繁荣当前的技能市场只是一个雏形。一个繁荣的技能平台可能需要技能元数据与搜索为技能添加更丰富的元数据类别、输入/输出格式、适用模型、作者、版本并支持搜索和发现。技能依赖与组合允许技能声明依赖关系例如“数据可视化”技能可能依赖“数据分析”技能产出的特定格式的JSON。技能版本管理与测试像管理软件包一样管理技能版本并提供自动化测试来验证技能的有效性。社区贡献与审核建立一个机制让社区用户可以提交、分享和审核技能。7.3 基准测试与评估体系要推动强智能体工作流的发展一个客观的评估体系必不可少。AgentWorld可以发展出基准测试原语用于定义基准任务一系列标准化的、可评估的任务如“完成一个端到端的机器学习研究项目”、“修复一个包含多个文件的Bug”。自动化评分根据任务目标自动评估运行产物的质量代码正确性、报告完整性、实验严谨性等。生成排行榜比较不同智能体、不同技能组合、不同工作流在相同任务上的表现。这将使AgentWorld不仅是一个构建工具也是一个衡量工具推动整个领域向更可靠、更高效的方向发展。7.4 应用层的创新在AgentWorld提供的稳固基础之上可以构建无数具体的应用自动化研究助手如当前的AutoR用例但可以扩展到更多学科生物、化学、物理。智能代码审查与重构构建一个多智能体流水线自动进行代码质量检查、安全扫描、性能分析和重构建议。自动化内容运营从热点追踪、素材搜集、内容创作、多平台发布到效果分析形成一个闭环的智能内容流水线。教育领域的个性化辅导根据学生的学习数据和问题自动生成个性化的学习路径、练习题目和讲解。这些应用的共同点是都需要可编排的、有状态的、能产生持久化副作用的智能体而这正是AgentWorld所擅长的。我个人在实际使用和探索AgentWorld的过程中最深刻的体会是它将智能体系统的“不确定性”与软件工程的“确定性”做了很好的结合。智能体的创造性输出仍然是不确定的但整个工作流的编排、状态管理、错误恢复、产物追踪变得确定且可控。这种结合使得构建可靠的、可用于生产环境的智能体应用不再是遥不可及的想法。如果你正在严肃地考虑将AI智能体集成到你的核心业务流程中AgentWorld所提供的这套基于文件系统原生的、可恢复的、技能化的架构范式是一个非常值得深入研究和投资的起点。