Skip to content

V1 Agent Backends en

weego edited this page Nov 15, 2026 · 1 revision

Agent Backends and Codex

简体中文 | 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.

Make one read-only call with the local Codex CLI

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.

Explicit resume and cancellation

  • Save both the local session_id and agent.last_backend_result.session_id. The latter is the Codex session ID and is passed as backend_session_id on 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 CancellationToken or execution_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)

Native workspaces, App Server, and Workers

  • 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 a BackendResult. Use NativeBackend(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.
  • CodexAppServerBackend is experimental and distinct from the default codex exec path. 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.

Clone this wiki locally