AutoGPT Forge 实战指南配置、分层权限体系与 Agent Protocol 架构解析【免费下载链接】AutoGPTAutoGPT is the vision of accessible AI for everyone, to use and to build on. Our mission is to provide the tools, so that you can focus on what matters.项目地址: https://gitcode.com/GitHub_Trending/au/AutoGPT本文以classic/forge目录下的 README 为主线系统讲解 AutoGPT Forge——AutoGPT 生态中用于构建 AI Agent 的核心自主框架从安装运行、.env与 YAML 权限配置到双层工作区 单 Agent权限检查机制的源码级实现以及支撑其运行的 Agent Protocol API 与组件化Components架构。读完后你将能够独立启动 Forge Agent 服务、按风险等级精细化控制 Agent 的命令执行权限并理解任务/步骤/产物Task/Step/Artifact这条核心执行链路。一、Forge 是什么由什么组成README 将 AutoGPT Forge 定位为一个用于构建 AI Agent 的核心自主 Agent 框架Core autonomous agent framework for building AI agents。从源码结构看它由三个层次构成Agent Protocol 层forge/agent_protocol/ 提供基于 FastAPI 的任务协议服务围绕 Task任务、Step步骤、Artifact产物三个核心模型组织执行流程组件层forge/components/ 下的组件读文件、执行代码、网页搜索等为 Agent 提供具体能力可通过协议插拔框架层forge/agent/ 提供BaseAgent/ForgeAgent负责把 LLM 调用、组件管道、权限检查编排成提议动作 → 执行 → 反馈的循环。服务入口非常简洁forge/app.py 只做三件事——读取DATABASE_STRING环境变量创建数据库、以本地workspace/目录作为文件存储、实例化ForgeAgent并返回其 FastAPI 应用# classic/forge/forge/app.py database_name os.getenv(DATABASE_STRING) workspace get_storage(FileStorageBackendName.LOCAL, root_pathPath(workspace)) database AgentDB(database_name, debug_enabledFalse) agent ForgeAgent(databasedatabase, workspaceworkspace) app agent.get_agent_app()二、快速开始按照 README所有命令均在classic/目录forge/的父目录下执行Forge 依赖由 classic/pyproject.toml 中的 Poetry 项目统一管理# Install (one-time setup) cd classic poetry install # Configure cp .env.example .env # Edit .env with your OPENAI_API_KEY # Run poetry run python -m forgeAgent 服务默认运行在http://localhost:8000。需要说明的是从当前仓库快照看classic/目录下并未附带.env.example文件若复制失败可按后文配置清单直接手动创建.env。入口链路与 README 描述可一一印证。python -m forge实际执行 forge/main.py它打印 ASCII Logo版本号 v0.2.0、配置日志、加载.env后以 uvicorn 启动服务# classic/forge/forge/__main__.py (核心片段) port os.getenv(PORT, 8000) configure_logging() logger.info(fAgent server starting on http://localhost:{port}) load_dotenv() uvicorn.run( forge.app:app, hostlocalhost, portint(port), log_levelerror, reloadTrue, # 开发模式热重载 reload_dirsos.path.dirname(os.path.dirname(__file__)), reload_includes[ f{os.path.basename(os.path.dirname(__file__))}/**/*.py, .*, .env, # .env 变更也会触发重载 ], )两个值得注意的细节PORT环境变量在此处被读取默认 8000与 README 中的PORT8000配置项对应且热重载监控了.env文件——修改环境变量无需手动重启服务。三、配置体系环境变量与 YAML 权限文件README 将配置分为两类控制运行行为的环境变量以及控制 Agent 行为边界的 YAML 权限文件。3.1 环境变量.envREADME 给出的完整变量清单如下# Required OPENAI_API_KEYsk-... # Optional LLM settings SMART_LLMgpt-4o # Model for complex reasoning FAST_LLMgpt-4o-mini # Model for simple tasks EMBEDDING_MODELtext-embedding-3-small # Optional search providers TAVILY_API_KEYtvly-... SERPER_API_KEY... GOOGLE_API_KEY... GOOGLE_CUSTOM_SEARCH_ENGINE_ID... # Optional infrastructure LOG_LEVELDEBUG # DEBUG, INFO, WARNING, ERROR DATABASE_STRINGsqlite:///agent.db # Agent Protocol database PORT8000 # Server port FILE_STORAGE_BACKENDlocal # local, s3, or gcs结合源码各变量的实际落点为变量消费位置说明OPENAI_API_KEYLLM 调用forge/llm/providers/openai.py唯一必填项。Forge 内置多供应商 LLM 抽象OpenAI、Anthropic、Groq 及 multi 组合见 forge/llm/providers/SMART_LLM/FAST_LLM双模型策略复杂推理走 SMART、简单任务走 FAST。从源码看watchdog 组件在检测到 Agent 陷入循环时会从 FAST_LLM 切换到 SMART_LLM 重新思考见 watchdog.py 的注释EMBEDDING_MODEL向量嵌入默认text-embedding-3-small嵌入模型清单定义在 openai.py 的OPEN_AI_EMBEDDING_MODELSTAVILY_API_KEY等网页搜索组件搜索供应商可选键供 web 组件调用LOG_LEVELforge/logging/config.py取值 DEBUG/INFO/WARNING/ERRORDATABASE_STRINGforge/app.py 第 8 行Agent Protocol 数据库连接串如sqlite:///agent.db存储 Task/Step/Artifact 元数据PORTforge/main.py 第 35 行服务端口默认 8000FILE_STORAGE_BACKENDforge/config/base.py 第 15 行from_envFILE_STORAGE_BACKEND默认LOCAL文件存储后端local / s3 / gcs对应实现位于 forge/file_storage/local.py、s3.py、gcs.py其中FILE_STORAGE_BACKEND有三套后端实现但要注意默认ForgeAgent应用在 app.py 中是直接以FileStorageBackendName.LOCAL构造工作区存储的切换后端主要影响组件级如文件管理组件的存储配置。3.2 工作区权限文件.autogpt/autogpt.yaml这是所有 Agent 共享的工作区级权限文件。README 给出的示例allow: - read_file({workspace}/**) - write_to_file({workspace}/**) - list_folder({workspace}/**) - web_search(*) deny: - read_file(**.env) - read_file(**.key) - execute_shell(rm -rf:*) - execute_shell(sudo:*)实际代码中的出厂默认值定义在 workspace_settings.py 第 18–41 行的WorkspaceSettings模型中比 README 示例更严格多覆盖了.env.*派生文件、.pem证书文件并把危险 shell 规则写得更为精确# classic/forge/forge/config/workspace_settings.py默认值节选 allow[ read_file({workspace}/**), write_file({workspace}/**), list_folder({workspace}/**), finish(*), ], deny[ read_file(**.env), read_file(**.env.*), read_file(**.key), read_file(**.pem), execute_shell(rm:-rf **), execute_shell(rm:-r **), execute_shell(sudo:**), ]WorkspaceSettings.load_or_create(workspace)的行为是文件存在则加载校验不存在则用默认值生成.autogpt/autogpt.yaml并落盘文件头自动附带 Auto-generated and updated as you grant permissions 注释——也就是说你在交互中授予的永久允许会持续追加进这个文件。3.3 Agent 级权限文件.autogpt/agents/{id}/permissions.yaml针对单个 Agent 的覆盖配置README 示例allow: - execute_python(*) deny: - execute_shell(*)对应实现是 workspace_settings.py 中的AgentPermissions模型load_or_create读取permissions.yaml不存在时返回空权限而不建文件add_permission在获得 Agent 级批准后自动把泛化模式写入 allow 列表并持久化。文件注释明确写着 These override workspace-level permissions这些权限覆盖工作区级别权限。四、工作区目录结构README 描述的标准目录布局{workspace}/ ├── .autogpt/ │ ├── autogpt.yaml # Workspace permissions │ ├── ap_server.db # Agent Protocol database │ └── agents/ │ └── AutoGPT-{agent_id}/ │ ├── state.json # Agent state │ ├── permissions.yaml # Agent permissions │ └── workspace/ # Agents working directory与源码的对应关系autogpt.yaml由WorkspaceSettings.save()写入.autogpt/permissions.yaml由AgentPermissions.save()写入 Agent 数据目录workspace_settings.py 会先mkdir(parentsTrue, exist_okTrue)Agent 数据目录采用AutoGPT-{agent_id}命名ForgeAgent在 forge_agent.py 第 70 行用uuid4()生成agent_id。五、权限检查机制Forge 的安全核心这是 README 技术含量最高的部分也是本篇的重点。权限管理的完整实现位于 forge/permissions.py核心类为CommandPermissionManager。5.1 检查顺序First Match WinsREADME 给出的检查顺序Agent deny 列表 → 拒绝Workspace deny 列表 → 拒绝Agent allow 列表 → 允许Workspace allow 列表 → 允许询问用户 → 交互式批准check_command() 的实现与之一致并额外插入了一步会话级拒绝同一会话内被用户拒绝过的具体命令精确参数串会记入_session_denied集合再次出现时直接拒绝、不再弹窗。若最终没有任何规则命中且没有可用的prompt_fn例如非交互场景命令同样被拒绝——这是 fail-closed 设计。5.2 批准的作用域ApprovalScope交互式批准不只是允许一次而是带作用域的四态枚举# classic/forge/forge/permissions.py class ApprovalScope(str, Enum): ONCE once # 仅允许这一次不持久化 AGENT agent # 对此 Agent 永久允许 WORKSPACE workspace # 对全部 Agent 永久允许 DENY deny # 拒绝选择AGENT/WORKSPACE批准后check_command会先调用_generalize_pattern()把具体参数泛化为模式再通过AgentPermissions.add_permission()/WorkspaceSettings.add_permission()持久化到对应 YAML 文件后续相同模式的命令在 allow 阶段即被自动放行并通过on_auto_approve回调通知上层用于审计日志。选择DENY时用户附带的反馈文本feedback会随结果返回供主循环改走do_not_execute()路径把反馈回传给 LLM而不是执行该命令——这正是 ForgeAgent.do_not_execute 的用武之地。5.3 模式语法与匹配算法模式格式为command_name(glob_pattern)README 示例模式含义read_file({workspace}/**)允许读取工作区内任意文件execute_shell(python:**)允许执行 Python 命令web_search(*)允许所有网页搜索特殊标记{workspace}会被替换为实际工作区路径**匹配任意路径含/*只匹配非/字符。_pattern_matches() 的实现揭示了匹配算法细节先按^(\w)\((.)\)$解析出命令名与参数模式命令名必须精确相等read_file的模式绝不匹配write_to_file再展开{workspace}占位符然后把 glob 转成正则——**先被转义还原为.**还原为[^/]*最后做全串匹配。_format_args()定义了各命令的参数规范化规则这直接决定模式怎么对齐文件操作read_file/write_file/write_to_file/create_file/list_folder统一解析为绝对路径相对路径相对工作区并resolve()以处理符号链接Shell/Python 执行execute_shell/execute_python格式化为可执行文件:参数取命令第一个词为可执行文件因此rm -rf /tmp/foo归一为rm:-rf /tmp/foo——这也解释了为什么默认 deny 规则要写成execute_shell(rm:-rf **)而非rm -rf:*网页操作web_search用查询串、read_webpage用 URL 作为匹配串其他命令所有参数值用:连接无参数时归一为*。5.4 模式泛化规则批准时写入文件的不是原始参数而是泛化后的模式_generalize_pattern()的规则为工作区内的文件 →read_file({workspace}/父目录/*)授权一个目录而非单个文件工作区外的文件 → 保留精确绝对路径shell 命令 →execute_shell(可执行文件:**)授权整个可执行文件web_search→web_search(**)read_webpage→ 提取域名生成read_webpage(*example.com*)其他命令 →command_name(**)。5.5 测试用例印证classic/forge/tests/test_permissions.py 为上述每条规则提供了可验证断言例如rm -rf /、rm -rf ~、sudo su等变体全部命中默认 deny.env、.key、.pem读取一律拒绝Agent 级 deny 可压过工作区级 allowtest_check_command_agent_deny_overrides_workspace_allow会话内重复的拒绝不再触发弹窗test_check_command_session_denialAGENT作用域批准后同一可执行文件的不同参数直接自动放行test_agent_approval_auto_approves_subsequent_calls。这些测试是验证权限行为是否与本文描述一致的最直接依据。六、Agent 运行时Agent Protocol 与组件体系6.1 Agent Protocol APIProtocolAgent.get_agent_app()agent_protocol/agent.py构建 FastAPI 应用标题 AutoGPT Forge、自述为 Modified version of The Agent Protocol协议路由挂载在/ap/v1前缀下api_router.pyCORS 白名单预置了 localhost:5000/8000/8080 等开发端口。若存在前端构建产物classic/frontend/build/web会挂载到/app并把根路径 307 重定向到/app/index.html。协议的核心抽象是三个模型agent_protocol/models/Taskcreate_task接收输入串 任意附加输入字典落库后返回任务 IDStepexecute_step是 Agent 逻辑的注入点一步之内可以做任何事也可以在输出中请求继续下一步Artifactcreate_artifact支持文件上传分块 1MB 读取后写入工作区agent_createdFalse标记为用户创建get_artifact以流式响应 Content-Disposition: attachment头返回下载。6.2 任务执行循环ForgeAgent 的双继承ProtocolAgentBaseAgent把协议与组件管道缝合起来。execute_step的主流程self.db.create_step(...)记录步骤propose_action()收集指令DirectiveProvider管道、命令清单CommandProvider管道、消息历史MessageProvider管道组装ChatPrompt含由命令生成的 function specs调用 LLM 得到ActionProposalexecute(proposal)在命令列表中倒序查找与tool.name匹配的命令并调用AgentTerminated视为正常结束AgentException转为ActionErrorResultrun_pipeline(AfterExecute.after_execute, result)让各组件在每次执行后做收尾如动作历史、数据落库。注意 README 的ForgeAgent.propose_action()目前以未实现逻辑的 finish 提案作为占位实现注释指向classic/original_autogpt/agents/agent.py的complete_and_parse作为完整 LLM 解析示例——换言之forge/提供的是框架与协议骨架而自带完整 LLM 循环的成品 Agent 在original_autogpt中两者共享同一套forge组件库。6.3 组件体系ComponentsForgeAgent 构造器 注册的内置组件包括SystemComponent提供finish命令并注入提示词、TodoComponent多步任务跟踪、ArchiveHandlerComponent、ClipboardComponent、DataProcessorComponent、HTTPClientComponent、MathUtilsComponent、TextUtilsComponent。组件系统的完整约定见 components/README.md要点自动发现在__init__中通过self.xxx SomeComponent()赋值的组件会被自动检测组件是继承AgentComponent或实现若干协议CommandProvider、MessageProvider、DirectiveProvider、AfterExecute等见 agent/protocols.py的类配置化继承ConfigurableComponent[BM]的组件可携带 pydantic 配置模型支持UserConfigurable(from_envENV_VAR_NAME, excludeTrue)从环境变量读取敏感值如 API key并在序列化时打码整个 Agent 的组件配置可经 JSON 文件 CLI 参数--component-config-file config.json注入文档中给出了CodeExecutorConfiguration、FileManagerConfiguration、WebSeleniumConfiguration等字段的完整示例排序默认按组件名字母序执行可用run_after(其他组件)声明依赖或在__init__中显式赋值self.components列表完全接管顺序此时必须列全所有组件动态启停设置_enabledbool 或 lambda与_disabled_reason可条件性禁用组件设None可移除父类组件错误与重试ComponentEndpointError/EndpointPipelineError/ComponentSystemError三级异常由框架捕获默认重试 3 次后再抛出。七、LLM 供应商抽象OPENAI_API_KEY虽是必填项但 Forge 的 LLM 层是多供应商设计。从源码结构看forge/llm/providers/ 包含 OpenAIopenai.py含OPEN_AI_EMBEDDING_MODELS嵌入模型表、Anthropicanthropic.py、Groqgroq.py以及多模型组合multi.py实现共享schema.py与_openai_base.py基类classic/forge/tests/ 中的test_openai_base_provider.py、test_anthropic_provider.py、test_multi_provider.py等测试覆盖了各供应商的消息序列化与调用行为。SMART_LLM/FAST_LLM的双模型配置则服务于 watchdog 组件的循环检测 → 换强模型重想策略。八、实践要点小结启动验证poetry run python -m forge后访问http://localhost:8000协议接口在/ap/v1前缀下改.env会自动热重载改代码同样会重载reloadTrue仅适合开发环境。权限设计顺序先收紧 workspace deny保护密钥文件与危险 shell再按 Agent 职责授予 agent 级 allow任何交互批准都会自动泛化并回写 YAML权限策略因此是越用越具体的积累过程建议定期审查.autogpt/autogpt.yaml。模式书写shell 类模式必须遵循可执行文件:参数归一格式如execute_shell(cat:**)文件类模式用{workspace}占位符可跨机器迁移**与*的差异能否跨/直接决定授权粒度。扩展路径需要新能力时优先写组件实现协议 挂到self上需要新 LLM 行为时参考original_autogpt的完整 Agent 实现权限、重试、日志、配置序列化均由框架兜底。适用前提本文基于当前仓库快照Forge 入口 Logo 标注版本 v0.2.0ForgeAgent.propose_action()当前为占位实现若要得到一个开箱即跑的完整 Agent应以classic/original_autogpt为运行对象二者共用classic/下的同一 Poetry 环境与组件库。【免费下载链接】AutoGPTAutoGPT is the vision of accessible AI for everyone, to use and to build on. Our mission is to provide the tools, so that you can focus on what matters.项目地址: https://gitcode.com/GitHub_Trending/au/AutoGPT创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
AutoGPT Forge 实战指南配置、分层权限体系与 Agent Protocol 架构解析【免费下载链接】AutoGPTAutoGPT is the vision of accessible AI for everyone, to use and to build on. Our mission is to provide the tools, so that you can focus on what matters.项目地址: https://gitcode.com/GitHub_Trending/au/AutoGPT本文以classic/forge目录下的 README 为主线系统讲解 AutoGPT Forge——AutoGPT 生态中用于构建 AI Agent 的核心自主框架从安装运行、.env与 YAML 权限配置到双层工作区 单 Agent权限检查机制的源码级实现以及支撑其运行的 Agent Protocol API 与组件化Components架构。读完后你将能够独立启动 Forge Agent 服务、按风险等级精细化控制 Agent 的命令执行权限并理解任务/步骤/产物Task/Step/Artifact这条核心执行链路。一、Forge 是什么由什么组成README 将 AutoGPT Forge 定位为一个用于构建 AI Agent 的核心自主 Agent 框架Core autonomous agent framework for building AI agents。从源码结构看它由三个层次构成Agent Protocol 层forge/agent_protocol/ 提供基于 FastAPI 的任务协议服务围绕 Task任务、Step步骤、Artifact产物三个核心模型组织执行流程组件层forge/components/ 下的组件读文件、执行代码、网页搜索等为 Agent 提供具体能力可通过协议插拔框架层forge/agent/ 提供BaseAgent/ForgeAgent负责把 LLM 调用、组件管道、权限检查编排成提议动作 → 执行 → 反馈的循环。服务入口非常简洁forge/app.py 只做三件事——读取DATABASE_STRING环境变量创建数据库、以本地workspace/目录作为文件存储、实例化ForgeAgent并返回其 FastAPI 应用# classic/forge/forge/app.py database_name os.getenv(DATABASE_STRING) workspace get_storage(FileStorageBackendName.LOCAL, root_pathPath(workspace)) database AgentDB(database_name, debug_enabledFalse) agent ForgeAgent(databasedatabase, workspaceworkspace) app agent.get_agent_app()二、快速开始按照 README所有命令均在classic/目录forge/的父目录下执行Forge 依赖由 classic/pyproject.toml 中的 Poetry 项目统一管理# Install (one-time setup) cd classic poetry install # Configure cp .env.example .env # Edit .env with your OPENAI_API_KEY # Run poetry run python -m forgeAgent 服务默认运行在http://localhost:8000。需要说明的是从当前仓库快照看classic/目录下并未附带.env.example文件若复制失败可按后文配置清单直接手动创建.env。入口链路与 README 描述可一一印证。python -m forge实际执行 forge/main.py它打印 ASCII Logo版本号 v0.2.0、配置日志、加载.env后以 uvicorn 启动服务# classic/forge/forge/__main__.py (核心片段) port os.getenv(PORT, 8000) configure_logging() logger.info(fAgent server starting on http://localhost:{port}) load_dotenv() uvicorn.run( forge.app:app, hostlocalhost, portint(port), log_levelerror, reloadTrue, # 开发模式热重载 reload_dirsos.path.dirname(os.path.dirname(__file__)), reload_includes[ f{os.path.basename(os.path.dirname(__file__))}/**/*.py, .*, .env, # .env 变更也会触发重载 ], )两个值得注意的细节PORT环境变量在此处被读取默认 8000与 README 中的PORT8000配置项对应且热重载监控了.env文件——修改环境变量无需手动重启服务。三、配置体系环境变量与 YAML 权限文件README 将配置分为两类控制运行行为的环境变量以及控制 Agent 行为边界的 YAML 权限文件。3.1 环境变量.envREADME 给出的完整变量清单如下# Required OPENAI_API_KEYsk-... # Optional LLM settings SMART_LLMgpt-4o # Model for complex reasoning FAST_LLMgpt-4o-mini # Model for simple tasks EMBEDDING_MODELtext-embedding-3-small # Optional search providers TAVILY_API_KEYtvly-... SERPER_API_KEY... GOOGLE_API_KEY... GOOGLE_CUSTOM_SEARCH_ENGINE_ID... # Optional infrastructure LOG_LEVELDEBUG # DEBUG, INFO, WARNING, ERROR DATABASE_STRINGsqlite:///agent.db # Agent Protocol database PORT8000 # Server port FILE_STORAGE_BACKENDlocal # local, s3, or gcs结合源码各变量的实际落点为变量消费位置说明OPENAI_API_KEYLLM 调用forge/llm/providers/openai.py唯一必填项。Forge 内置多供应商 LLM 抽象OpenAI、Anthropic、Groq 及 multi 组合见 forge/llm/providers/SMART_LLM/FAST_LLM双模型策略复杂推理走 SMART、简单任务走 FAST。从源码看watchdog 组件在检测到 Agent 陷入循环时会从 FAST_LLM 切换到 SMART_LLM 重新思考见 watchdog.py 的注释EMBEDDING_MODEL向量嵌入默认text-embedding-3-small嵌入模型清单定义在 openai.py 的OPEN_AI_EMBEDDING_MODELSTAVILY_API_KEY等网页搜索组件搜索供应商可选键供 web 组件调用LOG_LEVELforge/logging/config.py取值 DEBUG/INFO/WARNING/ERRORDATABASE_STRINGforge/app.py 第 8 行Agent Protocol 数据库连接串如sqlite:///agent.db存储 Task/Step/Artifact 元数据PORTforge/main.py 第 35 行服务端口默认 8000FILE_STORAGE_BACKENDforge/config/base.py 第 15 行from_envFILE_STORAGE_BACKEND默认LOCAL文件存储后端local / s3 / gcs对应实现位于 forge/file_storage/local.py、s3.py、gcs.py其中FILE_STORAGE_BACKEND有三套后端实现但要注意默认ForgeAgent应用在 app.py 中是直接以FileStorageBackendName.LOCAL构造工作区存储的切换后端主要影响组件级如文件管理组件的存储配置。3.2 工作区权限文件.autogpt/autogpt.yaml这是所有 Agent 共享的工作区级权限文件。README 给出的示例allow: - read_file({workspace}/**) - write_to_file({workspace}/**) - list_folder({workspace}/**) - web_search(*) deny: - read_file(**.env) - read_file(**.key) - execute_shell(rm -rf:*) - execute_shell(sudo:*)实际代码中的出厂默认值定义在 workspace_settings.py 第 18–41 行的WorkspaceSettings模型中比 README 示例更严格多覆盖了.env.*派生文件、.pem证书文件并把危险 shell 规则写得更为精确# classic/forge/forge/config/workspace_settings.py默认值节选 allow[ read_file({workspace}/**), write_file({workspace}/**), list_folder({workspace}/**), finish(*), ], deny[ read_file(**.env), read_file(**.env.*), read_file(**.key), read_file(**.pem), execute_shell(rm:-rf **), execute_shell(rm:-r **), execute_shell(sudo:**), ]WorkspaceSettings.load_or_create(workspace)的行为是文件存在则加载校验不存在则用默认值生成.autogpt/autogpt.yaml并落盘文件头自动附带 Auto-generated and updated as you grant permissions 注释——也就是说你在交互中授予的永久允许会持续追加进这个文件。3.3 Agent 级权限文件.autogpt/agents/{id}/permissions.yaml针对单个 Agent 的覆盖配置README 示例allow: - execute_python(*) deny: - execute_shell(*)对应实现是 workspace_settings.py 中的AgentPermissions模型load_or_create读取permissions.yaml不存在时返回空权限而不建文件add_permission在获得 Agent 级批准后自动把泛化模式写入 allow 列表并持久化。文件注释明确写着 These override workspace-level permissions这些权限覆盖工作区级别权限。四、工作区目录结构README 描述的标准目录布局{workspace}/ ├── .autogpt/ │ ├── autogpt.yaml # Workspace permissions │ ├── ap_server.db # Agent Protocol database │ └── agents/ │ └── AutoGPT-{agent_id}/ │ ├── state.json # Agent state │ ├── permissions.yaml # Agent permissions │ └── workspace/ # Agents working directory与源码的对应关系autogpt.yaml由WorkspaceSettings.save()写入.autogpt/permissions.yaml由AgentPermissions.save()写入 Agent 数据目录workspace_settings.py 会先mkdir(parentsTrue, exist_okTrue)Agent 数据目录采用AutoGPT-{agent_id}命名ForgeAgent在 forge_agent.py 第 70 行用uuid4()生成agent_id。五、权限检查机制Forge 的安全核心这是 README 技术含量最高的部分也是本篇的重点。权限管理的完整实现位于 forge/permissions.py核心类为CommandPermissionManager。5.1 检查顺序First Match WinsREADME 给出的检查顺序Agent deny 列表 → 拒绝Workspace deny 列表 → 拒绝Agent allow 列表 → 允许Workspace allow 列表 → 允许询问用户 → 交互式批准check_command() 的实现与之一致并额外插入了一步会话级拒绝同一会话内被用户拒绝过的具体命令精确参数串会记入_session_denied集合再次出现时直接拒绝、不再弹窗。若最终没有任何规则命中且没有可用的prompt_fn例如非交互场景命令同样被拒绝——这是 fail-closed 设计。5.2 批准的作用域ApprovalScope交互式批准不只是允许一次而是带作用域的四态枚举# classic/forge/forge/permissions.py class ApprovalScope(str, Enum): ONCE once # 仅允许这一次不持久化 AGENT agent # 对此 Agent 永久允许 WORKSPACE workspace # 对全部 Agent 永久允许 DENY deny # 拒绝选择AGENT/WORKSPACE批准后check_command会先调用_generalize_pattern()把具体参数泛化为模式再通过AgentPermissions.add_permission()/WorkspaceSettings.add_permission()持久化到对应 YAML 文件后续相同模式的命令在 allow 阶段即被自动放行并通过on_auto_approve回调通知上层用于审计日志。选择DENY时用户附带的反馈文本feedback会随结果返回供主循环改走do_not_execute()路径把反馈回传给 LLM而不是执行该命令——这正是 ForgeAgent.do_not_execute 的用武之地。5.3 模式语法与匹配算法模式格式为command_name(glob_pattern)README 示例模式含义read_file({workspace}/**)允许读取工作区内任意文件execute_shell(python:**)允许执行 Python 命令web_search(*)允许所有网页搜索特殊标记{workspace}会被替换为实际工作区路径**匹配任意路径含/*只匹配非/字符。_pattern_matches() 的实现揭示了匹配算法细节先按^(\w)\((.)\)$解析出命令名与参数模式命令名必须精确相等read_file的模式绝不匹配write_to_file再展开{workspace}占位符然后把 glob 转成正则——**先被转义还原为.**还原为[^/]*最后做全串匹配。_format_args()定义了各命令的参数规范化规则这直接决定模式怎么对齐文件操作read_file/write_file/write_to_file/create_file/list_folder统一解析为绝对路径相对路径相对工作区并resolve()以处理符号链接Shell/Python 执行execute_shell/execute_python格式化为可执行文件:参数取命令第一个词为可执行文件因此rm -rf /tmp/foo归一为rm:-rf /tmp/foo——这也解释了为什么默认 deny 规则要写成execute_shell(rm:-rf **)而非rm -rf:*网页操作web_search用查询串、read_webpage用 URL 作为匹配串其他命令所有参数值用:连接无参数时归一为*。5.4 模式泛化规则批准时写入文件的不是原始参数而是泛化后的模式_generalize_pattern()的规则为工作区内的文件 →read_file({workspace}/父目录/*)授权一个目录而非单个文件工作区外的文件 → 保留精确绝对路径shell 命令 →execute_shell(可执行文件:**)授权整个可执行文件web_search→web_search(**)read_webpage→ 提取域名生成read_webpage(*example.com*)其他命令 →command_name(**)。5.5 测试用例印证classic/forge/tests/test_permissions.py 为上述每条规则提供了可验证断言例如rm -rf /、rm -rf ~、sudo su等变体全部命中默认 deny.env、.key、.pem读取一律拒绝Agent 级 deny 可压过工作区级 allowtest_check_command_agent_deny_overrides_workspace_allow会话内重复的拒绝不再触发弹窗test_check_command_session_denialAGENT作用域批准后同一可执行文件的不同参数直接自动放行test_agent_approval_auto_approves_subsequent_calls。这些测试是验证权限行为是否与本文描述一致的最直接依据。六、Agent 运行时Agent Protocol 与组件体系6.1 Agent Protocol APIProtocolAgent.get_agent_app()agent_protocol/agent.py构建 FastAPI 应用标题 AutoGPT Forge、自述为 Modified version of The Agent Protocol协议路由挂载在/ap/v1前缀下api_router.pyCORS 白名单预置了 localhost:5000/8000/8080 等开发端口。若存在前端构建产物classic/frontend/build/web会挂载到/app并把根路径 307 重定向到/app/index.html。协议的核心抽象是三个模型agent_protocol/models/Taskcreate_task接收输入串 任意附加输入字典落库后返回任务 IDStepexecute_step是 Agent 逻辑的注入点一步之内可以做任何事也可以在输出中请求继续下一步Artifactcreate_artifact支持文件上传分块 1MB 读取后写入工作区agent_createdFalse标记为用户创建get_artifact以流式响应 Content-Disposition: attachment头返回下载。6.2 任务执行循环ForgeAgent 的双继承ProtocolAgentBaseAgent把协议与组件管道缝合起来。execute_step的主流程self.db.create_step(...)记录步骤propose_action()收集指令DirectiveProvider管道、命令清单CommandProvider管道、消息历史MessageProvider管道组装ChatPrompt含由命令生成的 function specs调用 LLM 得到ActionProposalexecute(proposal)在命令列表中倒序查找与tool.name匹配的命令并调用AgentTerminated视为正常结束AgentException转为ActionErrorResultrun_pipeline(AfterExecute.after_execute, result)让各组件在每次执行后做收尾如动作历史、数据落库。注意 README 的ForgeAgent.propose_action()目前以未实现逻辑的 finish 提案作为占位实现注释指向classic/original_autogpt/agents/agent.py的complete_and_parse作为完整 LLM 解析示例——换言之forge/提供的是框架与协议骨架而自带完整 LLM 循环的成品 Agent 在original_autogpt中两者共享同一套forge组件库。6.3 组件体系ComponentsForgeAgent 构造器 注册的内置组件包括SystemComponent提供finish命令并注入提示词、TodoComponent多步任务跟踪、ArchiveHandlerComponent、ClipboardComponent、DataProcessorComponent、HTTPClientComponent、MathUtilsComponent、TextUtilsComponent。组件系统的完整约定见 components/README.md要点自动发现在__init__中通过self.xxx SomeComponent()赋值的组件会被自动检测组件是继承AgentComponent或实现若干协议CommandProvider、MessageProvider、DirectiveProvider、AfterExecute等见 agent/protocols.py的类配置化继承ConfigurableComponent[BM]的组件可携带 pydantic 配置模型支持UserConfigurable(from_envENV_VAR_NAME, excludeTrue)从环境变量读取敏感值如 API key并在序列化时打码整个 Agent 的组件配置可经 JSON 文件 CLI 参数--component-config-file config.json注入文档中给出了CodeExecutorConfiguration、FileManagerConfiguration、WebSeleniumConfiguration等字段的完整示例排序默认按组件名字母序执行可用run_after(其他组件)声明依赖或在__init__中显式赋值self.components列表完全接管顺序此时必须列全所有组件动态启停设置_enabledbool 或 lambda与_disabled_reason可条件性禁用组件设None可移除父类组件错误与重试ComponentEndpointError/EndpointPipelineError/ComponentSystemError三级异常由框架捕获默认重试 3 次后再抛出。七、LLM 供应商抽象OPENAI_API_KEY虽是必填项但 Forge 的 LLM 层是多供应商设计。从源码结构看forge/llm/providers/ 包含 OpenAIopenai.py含OPEN_AI_EMBEDDING_MODELS嵌入模型表、Anthropicanthropic.py、Groqgroq.py以及多模型组合multi.py实现共享schema.py与_openai_base.py基类classic/forge/tests/ 中的test_openai_base_provider.py、test_anthropic_provider.py、test_multi_provider.py等测试覆盖了各供应商的消息序列化与调用行为。SMART_LLM/FAST_LLM的双模型配置则服务于 watchdog 组件的循环检测 → 换强模型重想策略。八、实践要点小结启动验证poetry run python -m forge后访问http://localhost:8000协议接口在/ap/v1前缀下改.env会自动热重载改代码同样会重载reloadTrue仅适合开发环境。权限设计顺序先收紧 workspace deny保护密钥文件与危险 shell再按 Agent 职责授予 agent 级 allow任何交互批准都会自动泛化并回写 YAML权限策略因此是越用越具体的积累过程建议定期审查.autogpt/autogpt.yaml。模式书写shell 类模式必须遵循可执行文件:参数归一格式如execute_shell(cat:**)文件类模式用{workspace}占位符可跨机器迁移**与*的差异能否跨/直接决定授权粒度。扩展路径需要新能力时优先写组件实现协议 挂到self上需要新 LLM 行为时参考original_autogpt的完整 Agent 实现权限、重试、日志、配置序列化均由框架兜底。适用前提本文基于当前仓库快照Forge 入口 Logo 标注版本 v0.2.0ForgeAgent.propose_action()当前为占位实现若要得到一个开箱即跑的完整 Agent应以classic/original_autogpt为运行对象二者共用classic/下的同一 Poetry 环境与组件库。【免费下载链接】AutoGPTAutoGPT is the vision of accessible AI for everyone, to use and to build on. Our mission is to provide the tools, so that you can focus on what matters.项目地址: https://gitcode.com/GitHub_Trending/au/AutoGPT创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
