AG2 Extraction Notes

This document preserves the Meta Museum-relevant AG2 patterns extracted from the

temporary `metagenauto/` reference repository before that folder was removed from

the app workspace.

Decision

Meta Museum keeps the current TypeScript `AgentTask` contract layer as the public

and testable boundary. AG2 remains a future execution engine behind that boundary,

not a replacement for the existing review-first API.

Current production rule:

without human approval.

paths, and review state.

• Agents draft, score, reconcile, and review.
• Agents do not publish, merge identities, clear rights, deploy, or install tools
• Every agent-facing result must preserve citations, rights warnings, refusal

Extracted AG2 Runtime Rules

predicate or explicit terminate target.

• Target runtime from the reference repo was AG2 `0.13.2`, imported as `autogen`.
• Use a centralized `make_agent()` factory for AI-only agents.
• AI-only agents use `human_input_mode="NEVER"`.
• Human approver agents use `human_input_mode="ALWAYS"` and `llm_config=False`.
• Executor-only agents use `llm_config=False`.
• Every autonomous agent must have `max_consecutive_auto_reply`.
• Use at least two termination controls: turn/round caps plus a termination
• Keep `code_execution_config=False` unless code execution is the explicit job.
• Avoid exposing secrets through tool parameters or client-visible schemas.
• Do not use cached LLM responses in eval gates or production decision paths.

Agent Factory Pattern

The useful reference design was:

• resolve a named model tier (`cheap`, `mid`, `strong`, `hub`);
• apply shared constructor defaults;
• inject structured output schemas only when needed;
• create either a `ConversableAgent` or `AssistantAgent`;
• create executor and human-proxy agents through separate helper constructors.

Meta Museum mapping:

| AG2 idea | Meta Museum owner |

|---|---|

| `make_agent()` bounded constructor | future `services/agents/ag2-bridge` |

| AI-only default | current agent profiles remain review-only |

| executor-only proxy | future server-side tool executor |

| human proxy | existing `approvalRequired: true` and future review queue |

| structured response schema | existing Zod contracts and future Pydantic bridge |

Tool Registration Rules

AG2 distinguishes caller and executor agents:

• caller exposes a tool schema to the model;
• executor runs the actual function.

Rules to retain:

any write.

• Tool descriptions must be specific and auditable.
• Tool return values should be normalized JSON or compact text records.
• Secrets belong in server-side dependency contexts, not tool arguments.
• One credential boundary should have one explicit context object.
• Tools that mutate state must return a proposed diff or review packet before

Museum-specific first tools for an AG2 bridge:

• `search_records`
• `build_mapping_assist_plan`
• `find_reconciliation_candidates`
• `scan_rights_and_provenance`
• `draft_curatorial_text`
• `create_agent_task_review_packet`

Orchestration Patterns To Keep

Use AG2 only where the pattern earns its complexity.

Preferred:

tasks.

• Star / hub-and-spoke for cross-agent review, with one hub enforcing policy.
• Pipeline for fixed ordered workflows such as mapping review then import review.
• Triage-with-tasks for decomposing mixed user requests into typed specialist
• Redundant review for high-risk claims where two reviewers compare evidence.
• Escalation for cheap deterministic checks before expensive reasoning.

Avoid as default:

• organic group chats for standards-critical workflows;
• autonomous mutation/self-improvement against production code;
• public A2A endpoints before auth, rate limits, and approval gates exist.

Human Approval Gates

The reference repo had seven useful gate classes. Meta Museum should adapt them

to cultural-heritage workflows:

| Gate | Meta Museum equivalent |

|---|---|

| `phase_transition` | roadmap/status claim changes |

| `mutation_acceptance` | agent-authored code or config changes |

| `production_deploy` | public deploy or release |

| `external_tool_install` | new agent tool, MCP server, connector, or crawler |

| `safeguard_policy_change` | rights, citation, sensitivity, or refusal policy |

| `a2a_endpoint_exposure` | public or LAN-visible agent endpoint |

| `story_proposal` | agent-authored backlog item or roadmap scope |

Additional museum gates to add before AG2 execution:

• identity merge / `equivalent` write;
• rights clearance or reuse status upgrade;
• public Wiki/MediaWiki/Wikibase publish;
• provenance claim rewrite;
• sensitive-record disposition;
• bulk import activation from an AI-generated mapping.

Eval Gate Pattern

The valuable pattern is not the old test files themselves; it is the discipline:

1. Write an eval case before adding a new agent capability.

1. Keep structural gates runnable without live LLM calls.

1. Add behavioral gates for grounded outputs, refusals, and policy violations.

1. Require all prior gates to remain green.

1. Treat eval regressions as blockers, not warnings.

Meta Museum already has the right local equivalent:

• `tests/api/agents-run.test.ts`
• AI eval gate scripts and `/api/ai-evals/summary`
• closeout guard and README/roadmap currency rule
• citation/refusal tests for AI chat/query/content flows

Next AG2 bridge acceptance:

• AG2 bridge can be disabled with no API contract change.
• Same request returns the same `AgentTask` envelope shape in local and AG2 modes.
• Every AG2 output validates against existing Zod contracts.
• Timeout, refusal, tool error, and partial-output cases are tested.

Observability Pattern

Keep the fault-tolerant tracing shape:

• tracing setup must never crash request paths;
• no endpoint means no-op tracing;
• missing SDK means no-op tracing;
• trace capture of LLM messages must be explicitly enabled;
• do not export sensitive traces to third-party backends without approval.

Useful span categories:

• agent run;
• tool call;
• approval request;
• LLM call;
• citation retrieval;
• rights/provenance scan;
• refusal;
• human approval outcome.

AG-UI / A2A Notes

Do not make AG-UI or A2A the first bridge. Start with an internal server-side AG2

adapter called by the existing Next route. Consider AG-UI or A2A only after:

• persistent AgentTask history exists;
• approval queue UI exists;
• auth/rate limits are tested;
• trace IDs connect the Next request and AG2 run;
• shutdown/timeout behavior is proven.

If A2A is later exposed:

• default to loopback only;
• publish minimal agent cards;
• require auth and rate limiting;
• treat endpoint exposure as a human approval gate.

What Was Not Ported

The temporary repo included useful but non-essential systems that should not be

copied into Meta Museum now:

• its Next.js command-hub UI;
• its ticket system;
• Slack/Discord/Telegram agents;
• mutation/self-improvement engine;
• Chroma-specific project memory;
• Google Drive toolkit;
• book quote library;
• its roadmap and council personas.

Those are reference ideas only. Meta Museum's domain agents are Clio, Mercator,

Janus, Themis, and Calliope, and their job is museum-data review with evidence

and human oversight.

Recommended Bridge Sequence

1. Done: persist AgentTask run history in managed `agent-tasks.json` storage and

expose the editor-gated `/api/agents/tasks` review queue.

1. Done: add an internal, disabled-by-default AG2 bridge boundary behind

`src/services/agents.ts` for Mercator and Janus, with timeout, contract

validation, and local fallback behavior.

1. Done: implement the local Python AG2 worker endpoint in

`services/ag2-worker`, exposing `POST /ag2/agents/run` and `GET /health`.

1. Done: validate AG2 output through the existing TypeScript bridge contract

plus Python service-level tests for Mercator, Janus, approval refusal, and

scope limits.

1. Done: add route-to-bridge trace propagation plus timeout/refusal coverage

around the worker boundary.

1. Done: add deployment/runtime docs for enabling

`METAMUSEUM_AG2_BRIDGE_ENABLED` in `docs/ops/ag2-worker.md` and

`docs/env.md`.

1. Done: add live-worker eval artifacts and production sign-off policy through

`pnpm ag2:worker:eval` / `pnpm ag2:worker:eval:check`.

1. Only then consider A2A/AG-UI or multi-agent group-chat execution.