EAP architecture ¶

This page describes the architecture of the Enterprise Agent Platform (EAP) as it ships today: its internal components, how a request reaches an Agent, how the gateway and project runtime cooperate, and which external surfaces callers use.

It complements the higher-level platform overview, which describes the end-to-end operating model and responsibility boundaries, and runtime and governance, which describes the controls applied during execution.

Platform Components ¶

Component	Responsibility
Browser UI	provides the EAP chat experience for authenticated human users
EAP gateway	authenticates and authorizes callers, routes requests to projects, owns EAP conversation state, and translates AG-UI (deprecated), Simple Agent API, and ACP traffic
Registry sync and configuration generation	loads the approved project entry, selects the registered repository and branch, and generates project-scoped runtime configuration
Codex project runtime	runs one project-scoped `codex app-server` process that owns Codex threads and turns
PostgreSQL	stores gateway-owned conversation and task state
Project-scoped proxy	routes production model and remote or shared MCP traffic using the project's approved configuration

Codex is the primary runtime for EAP projects. New Registry entries select it explicitly with agent_runtime: codex.

Runtime Services And Controls ¶

Service or control	Role
Platform guardrails	supply non-overridable platform instructions when EAP creates or resumes a Codex thread
Keeper Vault + Kubed	store credentials and inject them into the project runtime without placing secret values in repositories or Registry YAML
Cisco Collab LLM Proxy	provides the managed model path for production execution
Approved MCP configuration	determines which MCP servers and tools are made available to the project runtime
Audit, observability, and emergency controls	record execution context, track runtime health and usage, and allow unsafe or unstable runs to be stopped

Repository-owned scripts, CLIs, and optional repo-local MCP tools are loaded with the selected agent repository. Remote or shared MCP servers run outside that repository and are operated by their respective service owners.

The presence of an MCP implementation or dependency in an agent repository does not enable it in production. EAP makes MCP capabilities available only through approved Registry-derived runtime configuration.

Architecture View ¶

This diagram shows the platform's component and runtime relationships. For the customer-to-platform ownership and review path, see the End-to-End Operating Model. For maintained deployment topology, see Deployment.

Request Lifecycle ¶

sequenceDiagram
    participant Caller as Browser / API / ACP caller
    participant GW as EAP gateway
    participant DB as PostgreSQL
    participant CX as Codex app-server
    participant Tool as Script / CLI / repo-local MCP
    participant PX as Project proxy
    participant LLM as Cisco LLM Proxy
    participant MCP as Approved remote/shared MCP

    Caller->>GW: AG-UI (deprecated) / Agent API / ACP request
    GW->>GW: Authenticate and authorize team/project
    GW->>DB: Load or create EAP conversation
    GW->>CX: Start or resume Codex thread
    CX->>CX: Load AGENTS.md, skills, documents, and tool definitions
    CX->>PX: Model request
    PX->>LLM: Forward with project identity
    LLM-->>PX: Model response and tool calls
    PX-->>CX: Model response

    opt Repository-owned tool execution
        CX->>Tool: Invoke approved repository-owned tool
        Tool-->>CX: Tool result
    end

    opt Remote or shared MCP execution
        CX->>PX: Approved MCP request
        PX->>MCP: Forward with approved authentication
        MCP-->>PX: Tool result
        PX-->>CX: Tool result
    end

    CX-->>GW: Thread and turn events
    GW->>DB: Persist EAP conversation state
    GW-->>Caller: Protocol-specific response or stream

All caller-facing protocols use the same Codex project runtime. The gateway translates Codex thread and turn events into the event model expected by each protocol.

Repository-owned execution remains inside the project runtime boundary. Calls to remote or shared MCP servers use the project-scoped proxy and approved runtime configuration.

Runtime Session Model ¶

EAP and Codex keep separate identifiers for separate responsibilities:

Object	Owner	Purpose
EAP conversation ID	gateway	public ID used by Agent API, AG-UI (deprecated), and ACP callers
Codex thread ID	Codex app-server	native runtime session used for turns, history, interruption, and resume
workspace directory	gateway + project runtime	per-conversation working directory populated from the approved project repository

The gateway stores the Codex thread ID as the conversation's runtime session ID. Codex thread storage does not replace the EAP conversation store.

External Surfaces ¶

EAP exposes three caller-facing protocol surfaces:

AG-UI (deprecated) — browser-native streaming interaction, used by the chat UI
Simple Agent API — HTTP request/response, webhook, and SSE invocation
ACP — Agent Client Protocol over /agent/{team}/{project}/{agent}/acp/ws

Codex projects currently expose one runtime agent named codex. HTTP and WebSocket routes remain scoped under /agent/{team}/{project}/{agent}/....

Control Inputs ¶

Every runtime decision is sourced from a reviewed input:

Input	Role
selected project agent repository	`AGENTS.md`, supporting documents, `.agents/skills`, scripts, CLIs, optional repo-local MCP implementations, human-approval rules, tests, and project assets
`enterprise-agent-platform-registry` project YAML	`agent_runtime`, selected repository and branch, production MCP configuration, LLM identity, caller allow-lists, and credential environment-variable references
generated Codex configuration	model provider, model, approved MCP registrations, runtime features, and OpenTelemetry settings
platform guardrails	non-overridable instructions supplied when EAP creates or resumes a Codex thread
Keeper Vault + Kubed	credentials injected at runtime; secret values are never stored in project repositories or Registry YAML

Remote or shared MCP implementations are not copied into the agent repository. Agent Skills document their dependencies, while the Registry authorizes which MCP capabilities EAP exposes in production.

A repo-local MCP implementation may be stored in the selected repository, but its presence does not automatically enable it in EAP. Production availability still depends on the approved Registry-derived runtime configuration.

The effective runtime contract is the intersection of the approved project content, Registry configuration, generated runtime configuration, platform guardrails, and injected credentials.