Repository navigation
V1 Agent Backends en
简体中文 | English
Applies to v1.0.0. A model provider exposes a model API; an Agent backend runs the entire task turn. The Codex CLI is an Agent backend, not an alternative base_url.
| Scenario | Entry point | Boundary |
|---|---|---|
| Chat, Python tools, memory, and streaming | Default LightAgent(...)
|
Does not automatically grant the model shell or workspace write access. |
| Run a workspace task with local Codex |
LightAgent(backend="codex") or explicit CodexBackend(...)
|
Requires a local POSIX host and an authenticated CLI. Uses the CLI sandbox rather than native per-tool policy. |
| Explicitly authorize workspace execution in a trusted application |
NativeBackend / WorkspaceExecutionProvider
|
Running on the host is not isolation. The adapter must enforce any isolation requirements. |
| Run an external backend as part of a workflow | BackendWorkerAdapter |
Candidate results still need independent LightDAG verification. |
| Reconnect to a background task | ExecutionService | The host owns factories, permissions, recovery, and approvals. Codex is not required. |
Install and authenticate the CLI, then check codex --version and codex login status. This adapter supports only the 0.160.x protocol; acceptance records include testing with 0.160.0. A missing executable, insufficient permissions, or a protocol mismatch causes an explicit failure, rather than a fallback to the native model loop. The base install does not install the CLI. Codex mode does not need a separate model API key in LightAgent.
This example uses an empty temporary workspace and a read-only sandbox. It makes one short request that counts toward the authenticated account's usage:
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)The shorthand LightAgent(backend="codex") defaults to workspace-write. Use it only when the task explicitly requires changes in a controlled workspace. The adapter reuses the CLI's authentication, not the user's model, MCP, or Hooks settings. It refuses unsupported project-level Codex configuration. If you pass an explicit SecurityContext, network access to the model service must be authorized. That is separate from network access for programs running inside the sandbox.
Use CodexBackend().probe() to check local compatibility without a model request. The workspace argument is not a guarantee of the operating system's read boundary. Put sensitive data in a separately isolated environment. Codex mode does not bridge native Python tools, memory, per-tool Guardrails, or native retry/budget parameters. It does not support stream=True; use on_backend_event for progress. Events may contain input or file contents, so do not publish them unredacted.
- Save both the local
session_idandagent.last_backend_result.session_id. The latter is the Codex session ID and is passed asbackend_session_idon the next turn. Do not substitute the local ID or use the most recent session implicitly. - Reuse the same verified workspace, Agent name, user and project, permissions, CLI home, adapter configuration, and control directory. Start a new session when a binding changes. The control directory is private and outside the workspace. The temporary example cannot resume after it exits.
- Manage active calls with a
CancellationTokenorexecution_timeout. Cancellation cannot undo external effects. Check what happened before deciding to retry; unknown outcomes are not replayed automatically.
# 接续成功的第一轮。第一轮也应传入相同的本地 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)is an explicit trusted-host execution path, not a container or a security sandbox. It provides workspace shell access and checked edits. Do not use it for untrusted model tasks. Supply and verify an isolated backend for filesystem, network, or resource constraints; never silently downgrade isolation. -
AgentBackend.execute(BackendRequest)returns aBackendResult. UseNativeBackend(agent_factory, execution_provider)or a custom adapter. A backend success result is not independent validation; it can still be submitted to a LightDAG Verifier. -
CodexAppServerBackendis experimental and distinct from the defaultcodex execpath. Its dynamic tools use a restricted bridge with schema validation and CapabilityGate checks. The bridge does not require the MCP SDK and is not the same as external MCP transport. Check protocol, thread resume, and isolation limits and run integration acceptance before deploying it.
See the Workspace Execution Reference and Public API Inventory for arguments, bindings, and offline contracts.
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