MetaMuseum
Menu
← Documentation home

Canonical Markdown source · Oct 20, 2018

AG2 Worker and Bridge Runbook

ops/ag2-worker.md · 208 lines · SHA-256 50efcd4e3318

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