Skip to content

Onboard an agent to EAP

This is the entry guide for project owners onboarding an agent to the Codex-based EAP runtime. It introduces the operating model, repository layout, and detailed onboarding steps.

By the end of onboarding you will have:

  • a project repo with Codex AGENTS.md, skills, and staging/production branches
  • a Registry YAML that explicitly selects the Codex runtime and authorizes production configuration
  • local and EAP staging smoke-test records linked from both PRs

Two Planes, Both Reviewed

EAP enforces change review on two planes. Both must pass before activation.

flowchart LR
  subgraph Plane1[Plane 1: Customer agent repo]
    AGENTS[Root AGENTS.md]
    SKILLS[.agents/skills + KB]
  end
  subgraph Plane2[Plane 2: Registry YAML]
    RUNTIME[agent_runtime: codex]
    REPO[repo + branch]
    MCP[mcp allowlist]
    ACCESS[caller allow-lists]
  end
  Plane1 -->|PR review| ACT((Activation))
  Plane2 -->|PR review| ACT
  ACT --> EAP[Codex project runtime]

Review covers risky commands, prompt injection, guardrail bypass, data-exfiltration paths, hard-coded secrets, and privilege expansion. High-risk changes require elevated approval.

Before You Start

You need:

  • a Git repository for the project content
  • a staging branch, commonly dev, and a production branch, commonly main
  • write access to open a PR against enterprise-agent-platform-registry
  • the Cisco MyID groups allowed to invoke the project
  • CI OAuth client IDs for M2M callers
  • Codex CLI, app, or IDE access for local iteration
  • at least one realistic scenario or sample input

Repository Structure

Keep project instructions and reusable workflows in the project repo:

<your-project-repo>/
├── AGENTS.md                       # required project instructions
├── .agents/
│   └── skills/
│       └── <skill-name>/
│           ├── SKILL.md            # required for each skill
│           ├── scripts/            # optional deterministic helpers
│           ├── references/         # optional on-demand context
│           └── assets/             # optional static output material
├── .codex/                         # optional local/project Codex config
│   ├── config.toml                 # local model/MCP defaults; not EAP authorization
│   └── agents/                     # optional custom Codex subagents
│       └── <subagent>.toml
└── README.md

Codex discovers AGENTS.md from the repository root toward the working directory. Add nested AGENTS.md or AGENTS.override.md files only when a subtree genuinely needs narrower instructions.

The Registry side is a separate repo:

enterprise-agent-platform-registry/
└── registry/
    └── <team>/
        └── <project>.yaml

Runtime Identity

The current Codex project manager exposes one EAP runtime agent named codex. The public route therefore uses that agent segment, for example:

POST /agent/<team>/<project>/codex/api/invoke_wait

Project instructions and skills determine how that runtime behaves. Optional Codex custom subagents are internal collaborators; they are not additional EAP route-level agents.

Quick Glossary

Term Meaning
AGENTS.md durable Codex instructions discovered from the repo root to the working directory
skill reusable workflow under .agents/skills/<name>/SKILL.md
Codex thread native runtime session mapped to an EAP conversation
approved MCP MCP server listed under mcp: in Registry YAML and rendered into production Codex config
guardrails gateway-owned developer instructions that project content cannot remove
approval gate runtime pause requiring caller or policy approval for a Codex server request
staging branch repo branch selected by env_overrides.stage.repo.branch, typically dev
production branch branch selected by repo.branch, typically main
smoke test concrete record showing input, environment, expected behavior, and result

Reading Order

  1. Write AGENTS.md — define durable project behavior and optional custom subagents.
  2. Author skills — write reusable SKILL.md workflows.
  3. Plan MCP dependencies — inventory external systems needed by those workflows.
  4. Register with enterprise-agent-platform-registry — select Codex and authorize repo, MCP, model identity, and callers.
  5. Test and promote — local Codex validation → EAP staging → EAP production.

After the first rollout, see Change lifecycle for how the two control planes interact over the life of the project.

Common Mistakes

  • splitting project instructions across agent manifest files instead of using the AGENTS.md instruction chain
  • putting configuration frontmatter in AGENTS.md
  • omitting agent_runtime: codex
  • treating local .codex/config.toml as production MCP or model authorization
  • requesting broad MCP access instead of scoping it to real skills
  • putting secrets in the Registry YAML or project repo
  • skipping EAP staging because local Codex succeeded
  • assuming a merge automatically updates the live runtime; deployment is an explicit platform-team action