AG2 Worker and Bridge Runbook

This runbook covers the local review-only AG2 worker and the disabled-by-default

Next.js bridge that can delegate Mercator and Janus review execution.

Service path:

• `services/ag2-worker/`

Bridge owner:

• `src/services/ag2-bridge.ts`

What it does:

request body.

response, HTTP failure, or timeout occurs.

• Exposes `GET /health` for local worker readiness.
• Exposes `POST /ag2/agents/run` for internal, server-side review execution.
• Accepts only Mercator and Janus.
• Preserves the existing `AgentTask` envelope and human approval gate.
• Records trace metadata from `x-request-id`, `traceparent`, and the bridge
• Falls back to local TypeScript review when disabled, missing URL, invalid

What it must not do:

`equivalent` links.

• Publish, merge identities, clear rights, activate imports, or write
• Expose A2A, AG-UI, or LAN/public agent endpoints.
• Accept agents other than Mercator and Janus without new tests and review.
• Run with secrets passed through tool arguments or client-visible schemas.

Install Deps

pnpm ag2:worker:deps

Run Locally

pnpm ag2:worker

Default bind:

• `http://127.0.0.1:7788`

Health Check

curl http://127.0.0.1:7788/health

Expected shape:

{
  "ok": true,
  "service": "ag2-worker",
  "eligibleAgents": ["mercator", "janus"],
  "reviewOnly": true
}

Enable Bridge Locally

Keep the worker loopback-only, start the worker, then start the Next app with

the bridge enabled:

pnpm ag2:worker

In the app environment:

METAMUSEUM_AG2_BRIDGE_ENABLED=1
METAMUSEUM_AG2_BRIDGE_URL=http://127.0.0.1:7788/ag2/agents/run
METAMUSEUM_AG2_BRIDGE_TIMEOUT_MS=5000
pnpm dev

For PowerShell:

$env:METAMUSEUM_AG2_BRIDGE_ENABLED="1"
$env:METAMUSEUM_AG2_BRIDGE_URL="http://127.0.0.1:7788/ag2/agents/run"
$env:METAMUSEUM_AG2_BRIDGE_TIMEOUT_MS="5000"
pnpm dev

Safe Smoke

Run the worker tests first:

pnpm ag2:worker:test

Then run the agent API focused tests:

node --import tsx --test tests/api/agents-run.test.ts

Run the live worker eval artifact check:

pnpm ag2:worker:eval
pnpm ag2:worker:eval:check

Artifacts:

• `artifacts/agents/ag2-worker-eval-latest.json`
• `artifacts/agents/runs/ag2-worker-eval-<timestamp>.json`

The local target may warn when operator sign-off is absent. Production target

checks fail without sign-off.

Manual API smoke:

curl -X POST http://127.0.0.1:3000/api/agents/run \
  -H "content-type: application/json" \
  -H "x-request-id: req-ag2-smoke" \
  -H "traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01" \
  -d "{\"agent\":\"mercator\",\"goal\":\"Review mapping via AG2 worker.\",\"mappingAssist\":{\"sourceProvider\":\"met\",\"sourceFormat\":\"csv\",\"columns\":[\"Object Title\"],\"sampleRows\":[{\"Object Title\":\"Smoke Object\"}]}}"

Pass conditions:

• response `agent` is `mercator`;
• response `bridge.status` is `used`;
• `task.approvalRequired` is `true`;
• `task.inputs.execution.runtime` is `ag2-worker` or AG2-bridge compatible;
• `task.inputs.ag2Bridge.status` is `used`;
• response headers include `x-request-id` and `traceparent`;
• no records are published, merged, imported, or rights-cleared.

Fallback smoke:

METAMUSEUM_AG2_BRIDGE_ENABLED=1
METAMUSEUM_AG2_BRIDGE_URL=
node --import tsx --test tests/api/agents-run.test.ts

Pass condition:

• local review still succeeds and `bridge.status` is `fallback`.

Deployment Rules

private service address.

performance test proves a higher value is safe.

approval.

• Default production posture is `METAMUSEUM_AG2_BRIDGE_ENABLED=0`.
• Staging may enable the bridge only when the worker is bound to loopback or a
• Do not expose the worker directly to the public internet.
• Keep `METAMUSEUM_AG2_BRIDGE_TIMEOUT_MS` at or below `5000` unless a reviewed
• Treat worker URL changes as a deployment/runbook change that requires human
• Keep `/api/agents/tasks` editor-gated so bridge output remains review-only.

Environment Variables

`http://127.0.0.1:7788/ag2/agents/run`)

`production`)

eval pass)

• `METAMUSEUM_AG2_BRIDGE_ENABLED` (default `0`)
• `METAMUSEUM_AG2_BRIDGE_URL` (default unset; local worker URL is
• `METAMUSEUM_AG2_BRIDGE_TIMEOUT_MS` (default `5000`, clamped by bridge code)
• `METAMUSEUM_AG2_WORKER_HOST` (default `127.0.0.1`)
• `METAMUSEUM_AG2_WORKER_PORT` (default `7788`)
• `METAMUSEUM_AG2_WORKER_MAX_RECORDS` (default `50`)
• `METAMUSEUM_AG2_WORKER_MAX_COLUMNS` (default `100`)
• `METAMUSEUM_AG2_EVAL_TARGET` (default `local`; allowed `local`, `staging`,
• `METAMUSEUM_AG2_OPERATOR_NAME` (required for production eval pass)
• `METAMUSEUM_AG2_OPERATOR_SIGNED_AT` (ISO timestamp; required for production
• `METAMUSEUM_AG2_OPERATOR_SCOPE` (required for production eval pass)

Rollback

Set:

METAMUSEUM_AG2_BRIDGE_ENABLED=0

Then restart the Next.js process. The app returns to local TypeScript review

without changing the `/api/agents/run` response contract.

Evidence To Capture

Before enabling outside local development, record:

`approvalRequired: true`

• `pnpm ag2:worker:test`
• `pnpm ag2:worker:eval:check`
• `node --import tsx --test tests/api/agents-run.test.ts`
• `pnpm test`
• `pnpm lint`
• `pnpm build`
• a manual smoke response showing `bridge.status: "used"` and
• rollback confirmation with `bridge.status: "disabled"` or `fallback`
• operator sign-off fields for production: operator, signedAt, and scope