EAP onboarding quickstart ¶

Use this page when you already know what agent you want to onboard and need the shortest path from an empty project repo to an EAP staging test.

For the full model and review expectations, read Onboard an agent to EAP.

flowchart LR
    A["1. Define AGENTS.md And Skills"] --> B["2. Plan MCP Access"]
    B --> C["3. Test With Codex"]
    C --> D["4. Register The Project"]
    D --> E["5. Validate And Promote"]

1. Define AGENTS.md And Skills ¶

Create or clone a project repo with this minimum layout:

<your-project-repo>/
├── AGENTS.md
├── .agents/
│   └── skills/
│       └── <skill-name>/
│           └── SKILL.md
└── .codex/                         # optional, local authoring only
    ├── config.toml                 # optional local model/MCP config
    └── agents/                     # optional Codex custom subagents
        └── <subagent>.toml

The root AGENTS.md defines durable project instructions in Markdown. Create one skill per real capability under .agents/skills/<skill-name>/SKILL.md.

Keep each skill focused:

• describe when it should trigger
• list required inputs
• document tool or MCP usage
• state expected output
• include references or scripts only when the skill needs them

See Write AGENTS.md and Author skills for details.

2. Plan MCP Access ¶

List every external system the agent needs to reach. Each production MCP must be declared in the project's Registry YAML and must authorize the EAP machine account that calls it.

See Plan MCP dependencies before writing the Registry YAML.

3. Test Locally With Codex ¶

Run Codex from the project repository root before asking EAP to deploy it.

1. Run codex login using an approved local authentication method.
2. Start codex from the repository root.
3. Confirm Codex summarizes the expected AGENTS.md instructions and lists the project skills.
4. Add local MCP servers to .codex/config.toml or ~/.codex/config.toml when the smoke test needs them.
5. Run at least one representative prompt in a fresh Codex thread.

Record:

• input
• Codex version and local model
• local MCP configuration used for the test, without secret values
• expected skill or MCP usage
• expected evidence in the response
• actual result
• any gap to fix before staging

Local Codex proves instruction and skill behavior. It does not prove EAP's production model, identity, generated MCP configuration, or approval behavior; staging proves those controls.

4. Register The Project ¶

Open a PR to enterprise-agent-platform-registry with a file under:

registry/<team>/<project>.yaml

Use this shape:

version: 1
agent_runtime: codex

repo:
  url: https://sqbu-github.cisco.com/stap/<your-project-repo>.git
  branch: main

mcp:
  emsapi:
    type: remote
    url: https://aiops-mcp.webex.com/emsapi/mcp/
    auth:
      type: client_credentials
      token_url: https://idbroker.webex.com/idb/oauth2/v1/access_token
      client_id_env: AIOPS_MCP_CLIENT_ID
      client_secret_env: AIOPS_MCP_CLIENT_SEC
      scope: openid

authorized_myid_groups:
  - <myid-group>

authorized_client_ids: []

env_overrides:
  stage:
    repo:
      branch: dev

Set agent_runtime: codex explicitly, and add only the MCP servers your skills actually use.

See Register with enterprise-agent-platform-registry for the complete schema and review expectations.

5. Validate And Promote ¶

Work in this order:

1. Push the agent repo change to dev.
2. Open paired PRs: one for the agent repo and one for enterprise-agent-platform-registry.
3. Link the local Codex smoke-test result in both PRs.
4. Ask the EAP platform team to deploy staging.
5. Invoke the codex runtime agent in EAP staging and record the result.
6. After staging is green, merge the agent repo change to main.
7. Merge the Registry PR.
8. Ask the EAP platform team to deploy production.

See Test and promote for staging and production expectations.

Ready Checklist ¶

Before asking for EAP review, confirm:

• the agent repo has dev and main
• the repo has a non-empty root AGENTS.md
• every project skill has .agents/skills/<name>/SKILL.md
• the Registry YAML includes agent_runtime: codex
• the MCP inventory matches the Registry YAML
• MyID groups and CI client IDs are correct
• no secrets are committed
• local Codex smoke-test output is linked in the PR
• staging deploy and validation are requested before production