Skip to content

V1 Agent Backends

weego edited this page Nov 15, 2026 · 2 revisions

执行后端与 Codex

简体中文 | English

适用版本:v1.0.0。「模型 Provider」提供模型 API;「Agent 后端」负责整个任务轮次。Codex CLI 属于后者,不是 base_url 的替代值。

场景 入口 边界
对话、Python 工具、记忆、流式 默认 LightAgent(...) 不自动给模型 shell 或工作区写权限。
让本机 Codex 完成一个工作区任务 LightAgent(backend="codex") 或显式 CodexBackend(...) 本机 POSIX、已认证的 CLI;使用 CLI 沙箱,不接管原生逐工具策略。
可信应用显式授权工作区执行 NativeBackend / WorkspaceExecutionProvider 在宿主机执行不等于隔离;强隔离由适配器实现。
在流程中运行外部后端 BackendWorkerAdapter 候选结果仍需 LightDAG 的独立验收。
可重连的后台任务 ExecutionService 工厂、权限、恢复和审批由宿主管理,不依赖 Codex。

用本机 Codex CLI 做一次只读调用

先安装并认证 Codex CLI,再运行 codex --version 和 codex login status。此适配器只兼容 CLI 的 0.160.x 协议,验收记录使用过 0.160.0。缺少命令、权限或协议不匹配时会明确失败,不会自动回落到原生模型调用。基础 LightAgent 安装不安装 CLI,也无需给 Codex 模式另填模型 API key。

以下示例使用空的临时工作区和只读沙箱,请求一次短文本,会消耗已登录账户用量:

from pathlib import Path
from tempfile import TemporaryDirectory

from LightAgent import BackendSessionStore, CodexBackend, LightAgent

with TemporaryDirectory() as directory:
    root = Path(directory)
    workspace = root / "workspace"
    workspace.mkdir()
    backend = CodexBackend(
        sandbox="read-only",
        session_store=BackendSessionStore(root / "sessions"),
    )
    agent = LightAgent(name="codex-guide", backend=backend)
    result = agent.run(
        "不用工具,使用中文回复一句简短问候。",
        workspace=str(workspace),
        execution_timeout=120,
        result_format="object",
    )
    if result.error:
        raise RuntimeError(result.error)
    print(result.content)

简写 LightAgent(backend="codex") 默认采用 workspace-write,只有明确需要编辑受控工作区时才考虑。CLI 适配器复用认证但不继承用户的模型、MCP、Hooks 配置;检测到不支持的项目级 Codex 配置时拒绝执行。若显式传 SecurityContext,访问模型服务须获网络授权;这和沙箱内程序的网络权限不同。不要因为 CLI 请求要联网就允许工作区命令联网。

只想检查本机兼容性时可运行 CodexBackend().probe(),它不请求模型。不能把 workspace 参数当作对操作系统读取范围的承诺;高敏感数据应放在独立隔离环境。Codex 模式不桥接原生 Python Tools、Memory、工具 Guardrails 或原生重试/预算参数。不支持 stream=True,通过 on_backend_event 观察进度;事件可能含文件和输入内容,不应原样公开。

显式恢复与取消

  • 应用保存本地 session_id 和 agent.last_backend_result.session_id。后者是 Codex 会话 ID,下一轮应作为 backend_session_id 传入;不要用本地 ID 或「最近一次」替代。
  • 使用同一个已校验工作目录、Agent 名称、用户和项目、权限、CLI home、适配器配置及控制目录。任何绑定改变都创建新会话。控制目录应为私有目录,并位于工作区之外;临时示例退出后不可用于恢复。
  • 传入 CancellationToken 或 execution_timeout 管理活动调用。取消不撤销已发生的外部效果。需要故障后核对,再考虑重试,不自动重放未知结果。
# 接续成功的第一轮。第一轮也应传入相同的本地 session_id。
external_id = agent.last_backend_result.session_id
continued = agent.run(
    "继续上一轮,用一句话总结。",
    workspace=str(workspace),
    session_id="guide-session",
    backend_session_id=external_id,
    execution_timeout=120,
    result_format="object",
)
if continued.error:
    raise RuntimeError(continued.error)
print(continued.content)

原生工作区、App Server 与 Worker

  • LocalWorkspaceProvider(allow_host_execution=True) 是可信宿主显式授权的执行路径,不是容器或安全沙箱。它提供工作区 shell 与受检查的文件编辑;不要用它承载不受信模型任务。需要文件、网络和资源隔离时,由应用提供并验证隔离后端;不可以静默降级。
  • AgentBackend.execute(BackendRequest) 返回 BackendResult;主机可用 NativeBackend(agent_factory, execution_provider) 或自定义适配器。后端的成功状态不是内容已验收,仍可交给 LightDAG Verifier。
  • CodexAppServerBackend 是实验路径,不同于默认的 codex exec。App Server 动态工具使用受限工具桥及 schema/CapabilityGate 校验;桥接模式独立于 MCP SDK,和外部 MCP 传输不是同一层。涉及正式部署时先核对协议、线程恢复和隔离边界,再做真实验收。

完整参数、绑定规则和离线契约见 工作区参考 与 公开 API 清单。

Clone this wiki locally