Agent Engines

Every entry in the Agent Catalog is labelled with the engine that executes it. The catalog is unified — one list, one review flow, one governance model — but engines differ fundamentally in where the agent runs, how instructions reach it, and who enforces its tools.

How Engines Differ

For the two GitHub-executed engines, publishing an agent means only "CodeCargo may invoke this" — the platform cannot narrow what the workflow or Copilot touches at runtime. Only the CodeCargo engine treats the grant as a runtime ceiling the platform itself enforces.

CodeCargo

The built-in code-editor agent. It runs in an isolated CodeCargo workspace under the platform's full tool plane: CargoWall egress control, credential-isolating MCP sidecars, granted-tool enforcement, runtime tool approvals, and CodeCargo-native triggers (schedules, GitHub releases, external webhooks, Dispatch).

CodeCargo agents are the only engine you author in CodeCargo itself — in the UI, or as a git-backed file. The file format is documented in the CodeCargo Agent Spec.

GitHub Actions (gh-aw)

A GitHub Agentic Workflow is a markdown file with YAML frontmatter under .github/workflows/, which the gh aw CLI compiles into a <name>.lock.yml GitHub Actions workflow — the lock file is what actually runs. CodeCargo detects both halves during organization sync and imports each source file into the catalog as a gh-aw agent (lock files are compiled artifacts and are never cataloged as agents themselves). See Agentic Workflows for the detection and governance-metadata details.

Imported gh-aw agents arrive as Needs review with an empty prompt — deliberate, because the markdown body belongs to GitHub Actions, not to CodeCargo. Tools declared in the workflow's frontmatter appear as its requested tools for review.

Compiled and Dispatchable

Each gh-aw agent card shows its compiled state:

• Compiled (green) — a paired .lock.yml exists on the default branch, so GitHub can run the workflow.
• Not compiled (amber) — no compiled lock file was detected next to the source. Until one exists, GitHub cannot run this agent at all. To fix it, run gh aw compile and commit the resulting .lock.yml; the next sync picks it up.

Compiled is necessary but not sufficient for CodeCargo to start the workflow: the lock must also declare a workflow_dispatch trigger. A compiled workflow without one can only run from its own GitHub triggers — CodeCargo catalogs and governs it, but cannot launch it. Agents that can't be dispatched appear disabled (with the reason) in binding pickers rather than being hidden.

Running a gh-aw Agent from CodeCargo

A published gh-aw agent can be run two ways: bind it to an Agentic Job (manual, scheduled, release, or webhook triggers all work), or let Dispatch bind it to a plan step. Either way, CodeCargo triggers the compiled workflow via the GitHub Actions workflow_dispatch API, on the repository's default branch, using the organization's GitHub App identity.

Before dispatching, CodeCargo checks — at bind time, at plan preflight, and again at dispatch — that the agent is Published (and parseable), that the compiled lock exists and declares workflow_dispatch, and that the execution entitlement is enabled. Any failure blocks the run with the specific reason rather than silently downgrading.

Observing Runs

A gh-aw run appears as an ordinary run in the job's run history and the run viewer, but it creates no CodeCargo workspace — the work happens on GitHub. CodeCargo:

• records the invocation and links it to the resulting GitHub Actions run,
• tracks live status via workflow-run webhooks (with API polling as a backstop),
• maps the Actions conclusion to the run outcome and composes a summary with a link to the Actions run — the Actions run is where the output lives,
• waits up to 12 hours for the workflow to finish before abandoning the watch (the Actions run itself is unaffected).

Canceling the run in CodeCargo stops the watch. Fan-out, auto-PR attribution, and interrupts — CodeCargo-workspace features — don't apply to gh-aw runs.

Limits

• Dispatch happens on the default branch only.
• CodeCargo never authors, edits, or compiles gh-aw files — compiling is your job via the gh aw CLI.
• Runtime enforcement (egress, tools) is GitHub's; CodeCargo audits the declared configuration but cannot narrow it.
• gh-aw is a GitHub technical preview with an evolving schema; files CodeCargo can't parse are cataloged as unparsed and are never runnable.

GitHub Copilot

The Copilot engine covers two shapes that share one governance model.

Custom Agents

Copilot custom agents are files GitHub already honors: .github/agents/<name>.md in a repository, or — for organization-wide agents — agents/<name>.md at the root of the org's .github (or .github-private) repository. CodeCargo's repository scan imports them so admins get governance visibility over agents that are already live for Copilot; importing changes nothing about how GitHub treats them.

Organization-wide agents carry an Organization-wide badge in the catalog — the source line shows one repo, but the agent is available everywhere Copilot runs in the org.

If two non-retired Copilot agents resolve to the same agent name (for example a repo-level and an org-level file with the same stem), the catalog surfaces a naming conflict warning rather than guessing — GitHub doesn't document which definition wins.

The Copilot Coding Agent

Each organization's catalog also contains one file-less entry named Copilot coding agent — GitHub's built-in agent, shipped by GitHub rather than defined by any file in your repositories. Publishing it controls whether CodeCargo may hand it work; retiring it is an explicit admin action (a scan never removes it).

How Copilot Runs Work

Running a Copilot-engine agent creates a Copilot coding-agent task via GitHub's API, as the triggering user — the user must have a linked GitHub identity, and the resulting work is attributed to Copilot on their behalf. Unlike gh-aw, the caller's prompt (with job inputs substituted) is delivered verbatim as the task prompt. The result is a pull request opened by Copilot; the run links to it.

Where the task runs depends on the agent: repository-level custom agents run in the repository where they're defined; the system agent and organization-wide agents run in the binding's primary repository.

Limits

• Copilot agent files use GitHub's format — CodeCargo-specific fields like mcp-servers: and inputs: are ignored for this engine.
• Detection is default-branch only, and enterprise-level agents in orgs CodeCargo doesn't sync stay invisible.
• Copilot agents can't be edited or committed from CodeCargo — they're GitHub's to author.