ZhuLinsen/daily_stock_analysis · error · AgentBackendConfigError

unsupported_agent_arch

unsupported_agent_arch

Error message

Codex Agent currently supports single-agent Chat only

What it means

AgentBackendConfigError (code 'unsupported_agent_arch') raised in the agent factory when the resolved backend is codex_app_server but config.agent_arch is not 'single'. The Codex App-Server backend implements only the single-agent chat flow, so requesting 'multi' (or any other arch value) with that backend is a configuration contradiction that fails fast at executor construction.

Source

Thrown at src/agent/factory.py:402

def build_agent_chat_executor(config=None, skills: Optional[List[str]] = None):
    """Build the backend-neutral executor used only by Agent Chat endpoints."""
    if config is None:
        from src.config import get_config

        config = get_config()

    from src.agent.agent_backend import (
        AgentBackendConfigError,
        LiteLLMAgentBackend,
        resolve_agent_backend_id,
    )
    from src.agent.chat_executor import AgentChatExecutor

    backend_id = resolve_agent_backend_id(config)
    arch = str(getattr(config, "agent_arch", "single") or "single").strip().lower()
    if backend_id == "codex_app_server" and arch != "single":
        raise AgentBackendConfigError(
            "unsupported_agent_arch",
            "Codex Agent currently supports single-agent Chat only",
        )
    if backend_id == "litellm" and arch == "multi":
        return build_agent_executor(config, skills=skills)

    registry = get_tool_registry()
    prompt_state = resolve_skill_prompt_state(config, skills=skills)
    if backend_id == "litellm":
        from src.agent.llm_adapter import LLMToolAdapter

        context_llm_adapter = LLMToolAdapter(config)
        backend = LiteLLMAgentBackend(registry, context_llm_adapter)
    else:
        from src.agent.codex_agent_backend import CodexAgentBackend
        from src.agent.tool_surface import ToolSurface

        context_llm_adapter = None

View on GitHub (pinned to 5159bd72e8)

Solutions

  1. Set agent_arch to 'single' (or remove it so the 'single' default applies) when using the codex_app_server backend.
  2. Or switch the backend away from codex_app_server (e.g. to litellm) if you need multi-agent mode.
  3. Audit .env / config for contradictory pairs (backend id vs agent_arch) at startup and fail with a clear message before any agent runs.

Example fix

# before (.env)
AGENT_BACKEND=codex_app_server
AGENT_ARCH=multi

# after
AGENT_BACKEND=codex_app_server
AGENT_ARCH=single
Defensive patterns

Strategy: validation

Validate before calling

def agent_config_is_consistent(config) -> bool:
    arch = str(getattr(config, "agent_arch", "single") or "single").strip().lower()
    backend = str(getattr(config, "agent_backend", "litellm")).strip().lower()
    return not (backend == "codex_app_server" and arch != "single")

Try / catch

from src.agent.agent_backend import AgentBackendConfigError

try:
    executor = build_executor(config)
except AgentBackendConfigError as e:
    if e.error_code == "unsupported_agent_arch":
        config.agent_arch = "single"  # or surface a config UI error
        executor = build_executor(config)

Prevention

When it happens

Trigger: Building the agent executor while AGENT_BACKEND/codex_app_server is the resolved backend id and agent_arch is set to 'multi' (or any string other than 'single' after strip/lower). With backend 'litellm' and arch 'multi' a different executor is built instead, so the error is specific to the codex_app_server + non-single combination.

Common situations: Env files copied between deployments that mix a Codex backend with multi-agent settings; enabling multi-agent orchestration while an experimental Codex backend flag is still on; defaulting agent_arch to something nonstandard in a shared config template.

Related errors

AI-assisted analysis of ZhuLinsen/daily_stock_analysis@5159bd72e8 (2026-08-15). Data as JSON: /api/errors/2a8f7a2125e84ccf. Report an issue: GitHub.