Repository navigation
V1 Agent Backends
简体中文 | 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 --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)-
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 传输不是同一层。涉及正式部署时先核对协议、线程恢复和隔离边界,再做真实验收。
LightAgent Wiki - see the repository, releases, and issues.
- Installation and Your First Agent
- Tools and Integrations
- Memory, Sessions, and RAG
- Workflows and Multiple Agents
- Agent Backends and Codex
- Durable Execution, Jobs, and Subagents
- Safety, Observability, and Evaluation
- Usage, Cost Estimates, and Budgets
- Deployment, Migration, and Verification
- 安装与第一个 Agent
- 工具和集成
- 记忆、会话与 RAG
- 工作流与多 Agent
- 执行后端与 Codex
- 持久执行、Jobs 与 Subagents
- 安全、观测与评测
- 用量统计、费用估算与预算
- 部署、升级与验收
- Quick Start
- Core Concepts
- API Reference
- Examples Cookbook
- Migration Guide
- Tools
- Tool Generator
- Memory
- MCP
- Skills
- LightFlow
- Tree of Thought
- Self-Learning
- Multi-Agent
- Tracing and Debugging
- Langfuse Observability
- Model Providers
- browser-use Integration
- Testing and CI
- Deployment Guide
- Architecture
- Security
- Known Limitations
- FAQ
- FAQ 中文
- Roadmap
- Release Process
- Contributing