Agent Catalog & Typed Contracts

A multi-agent system that stores only display names and prompts is orchestrating by guesswork. A “Researcher” returns free text while a “Publisher” expects structured JSON; one agent exposes a high-impact tool with no clear authority; another handoff sends customer data to an agent with no defined memory boundary. A successful demo does not make these interfaces compatible.

The lesson artifact is Agent Catalog & Typed Contract Registry v1. Each agent receives a stable identity, version, purpose, owner, typed input/output contract, tools, handoffs, authority class, data/memory boundary, guardrails, failure/retry semantics, compatibility, deprecation and evidence.

First rule: an agent name and a good prompt are not a callable contract.

Route orientation and owned boundary

AGN-003 owns the catalog and typed-contract outcome. AGN-002 owns evidence/confidence recommendation logic; AGN-004 owns the Agent Authority Matrix. This lesson does not grant new authority or replace a memory policy. It records the interfaces and boundaries that orchestration must be able to validate before delegation.

Foundation learners start with a field map and a baseline. Experienced learners may compress definitions, but they must still pass versioning, schema compatibility, tool/handoff contract, authority linkage and failure-semantics gates.

AGN-001 is a hard prerequisite and AGN-002 is soft. Fragile prerequisite evidence activates a bounded bridge rather than lowering the AGN-003 outcome.

Mental model: an agent is a versioned contractual endpoint

Treat each catalog entry like an endpoint a caller can inspect without reading the internal prompt:

1. Identity: agent_id, agent_version, purpose, owner_ref.
2. Interface: input_schema_ref, output_schema_ref, structured_output_mode.
3. Capabilities and delegation: tool_contract_ids, handoff_contract_ids, authority_class, allowed_actions, forbidden_actions.
4. Data boundary: data_classification, memory_boundary_ref, guardrail_refs.
5. Failure behavior: failure_states, retry_contract_ref.
6. Evolution state: compatibility_state, deprecation_state, catalog_status, evidence_ref.

A typed contract must type non-success too. HOLD, INCOMPATIBLE, DEPRECATED and UNKNOWN are healthy states when evidence is not strong enough for active delegation.

Foundations: external FACT versus local DESIGN

Current OpenAI Agents SDK documentation models an agent as an LLM configured with instructions and tools plus optional behavior such as handoffs, guardrails and structured outputs. Its function-schema layer represents function parameters with a Pydantic model and derived JSON Schema, and recommends strict JSON schema to improve the likelihood of correct structured tool input. JSON Schema Draft 2020-12 provides a standardized vocabulary for describing and validating JSON structure.

Those are FACTS about mechanisms. MAKNOW’s required catalog fields, compatibility states, authority classes and release gates are local DESIGN.

Keep three boundaries explicit:

• schema validates structure; it does not authorize a side effect;
• structured output improves interface reliability; it does not prove business semantics;
• an SDK can expose a tool or handoff; local authority must still permit its use.

Deep explanation of the registry and gates

The core contract has 21 columns:

agent_id, agent_version, purpose, owner_ref, input_schema_ref, output_schema_ref, structured_output_mode, tool_contract_ids, handoff_contract_ids, authority_class, allowed_actions, forbidden_actions, data_classification, memory_boundary_ref, guardrail_refs, failure_states, retry_contract_ref, compatibility_state, deprecation_state, catalog_status, evidence_ref.

Gate 1 — Stable identity

agent_id is stable; incompatible behavior must not hide under an unchanged version. If the output schema changes while the version stays constant, catalog admission is held.

Gate 2 — Typed input/output

The caller should not infer free-text conventions from a prompt. Input and output need traceable schema references. Optional-to-required changes are potentially breaking and must trigger compatibility recomputation.

Gate 3 — Tools and authority

Registering a tool is not permission to execute it. A new high-impact tool needs corresponding authority and allowed actions. Adding refund.execute to a READ_RECOMMEND agent is a mismatch even when its function schema is valid.

Gate 4 — Handoff dependency

A handoff is a contract dependency. If a new version removes a handoff while a consumer still requires it, that consumer is incompatible and orchestration must not silently activate the new version.

Gate 5 — Data/memory boundary

Every entry needs a data classification and memory-boundary reference. Workflow membership cannot infer permission to share data or memory.

Gate 6 — Failure and retry semantics

States such as timeout, validation_error, guardrail_block, tool_denied and handoff_unavailable should be nameable. Retry needs its own contract; blind retries around side effects are unsafe.

Gate 7 — Compatibility and deprecation

Keep COMPATIBLE, REVIEW_REQUIRED, INCOMPATIBLE and UNKNOWN distinct. DEPRECATED means “do not choose for new consumers,” not “old evidence disappears.” Final catalog status must agree with compatibility and deprecation.

Worked examples

1. Healthy baseline: research-agent v1.2.0

Input is ResearchRequest@1, output is ResearchBrief@2, structured mode is strict, tools are web.search and docs.read, handoff targets editor-agent, authority is READ_RECOMMEND, data class is PUBLIC_OR_APPROVED_INTERNAL, and memory is bounded to run/session. Failure states and retry rules are named and current consumers accept the output schema. Result: ACTIVE / COMPATIBLE.

2. Wrong shortcut: schema changes, version does not

The team changes output from ResearchBrief@2 to ResearchBrief@3 and adds a required field, but leaves agent_version=1.2.0. The agent’s own tests may pass while old consumers break. The version gate returns HOLD_VERSION_NOT_INCREMENTED.

3. High-impact tool without new authority

support-agent gains refund.execute while authority_class=READ_RECOMMEND and allowed actions remain read/recommend. A correct JSON Schema does not create refund permission. Result: HOLD_AUTHORITY_NOT_RECOMPUTED.

4. Transfer: a new version removes a handoff

publisher-agent v2 changes its output schema and removes a handoff to legal-review-agent. Two consumers still expect v1 output and one still requires legal review. The new version may be cataloged, but incompatible consumers must move to INCOMPATIBLE or HOLD until migration; the baseline decision is not an oracle.

Failure modes

• Prompt folklore: the interface exists only inside prompt prose.
• Display-name identity: similar agents have no stable id/version.
• Schema-without-semantics: JSON is valid while business meaning or authority is wrong.
• Version camouflage: breaking schema or handoff changes hide under the same version.
• Tool creep: a tool is added without recomputing authority.
• Handoff drift: consumers depend on a handoff the producer removed.
• Memory ambiguity: memory boundary is unknown while the entry is still ACTIVE.
• Failure collapse: all failures become one generic exception and blind retry.
• Deprecation contradiction: an entry is deprecated yet advertised as active for new consumers.
• Baseline oracle: a prior decision is copied after constraints change.

Alternatives and trade-offs

Loose contracts reduce onboarding friction but push integration debt into runtime. Typed contracts cost more up front but expose incompatible delegation earlier. Strict schemas improve structural reliability but can make evolution harder when over-constrained. Conservative versioning slows migration but makes consumer breakage visible.

A centralized catalog improves discoverability and auditing at the cost of governance overhead. A distributed catalog improves team autonomy but makes compatibility audits harder. None of these trade-offs justify removing authority, provenance or explicit compatibility states.

Experienced bridge

For every agent change, answer seven questions:

1. What is the stable id/version?
2. How did the input/output contract change?
3. Which tools or handoffs were added or removed?
4. Does authority still cover exactly those changes?
5. Did the data or memory boundary change?
6. What compatibility state does each existing consumer get?
7. How do failure/retry and deprecation change?

If any answer is UNKNOWN, do not default to ACTIVE.

Guided and independent practice

Inspect derived_text/tables/AGN-003-T1.csv, then run:

python -B lab/AGN-003-LAB1/learner/run_checks.py

For independent practice, create a new version that changes the output schema and removes one handoff. Recompute the catalog entry and consumer states without reading the baseline decision label. Consumers that still require the old schema or handoff must be incompatible or held; silent upgrade is forbidden.

Verification evidence

Passing means the registry and decision are reproducible from visible fixtures. The lab must reject at least:

• changed output schema with unchanged version;
• high-impact tool added without authority recomputation;
• required handoff removed while a consumer depends on it;
• optional-to-required input change without incompatible/review state;
• decisive evidence missing while status is forced to ACTIVE;
• baseline decision reused in transfer.

No hidden reasoning or network access is needed for the oracle.

Assessment and transfer

Assessment covers boundary retrieval, mutation diagnosis and transfer. In transfer, publisher-agent v2 changes its output schema and removes one handoff. The learner must identify which consumers migrate, which become INCOMPATIBLE or HOLD, and why.

“Bump the version” is not enough. A strong answer traces versioning, schema compatibility, handoff dependency, authority and consumer state together. Copying the baseline decision fails transfer.

References and freshness

• OpenAI Agents SDK — Agents: current agent, tool, handoff, guardrail and structured-output semantics.
• OpenAI Agents SDK — Function schema: Pydantic model, JSON Schema and strict-schema recommendation.
• JSON Schema Draft 2020-12: specification and validation vocabulary for JSON structure.
• Frozen Lesson Bible lesson://AGN-003: local MAKNOW authority for fields, compatibility states and release gates.

Agents SDK claims are rechecked by 2026-10-18 or earlier on material change. JSON Schema 2020-12 is recorded as the stable specification baseline. This lesson performs no live action, billing mutation or persistence of real user data.