Matchplane Agent Integration

---
name: matchplane-agent-integration
description: Connect buyer and seller agents to MatchPlane's bounded Agent, Skill, MCP, routing, and retrieval contracts. Use when adding an external agent, designing buyer/seller handoff, exposing MCP tools, or reviewing token ownership and contact-consent boundaries.
---

# MatchPlane Agent Integration

Use the same integration shape for buyers and sellers. The role changes the intent and allowed
tools; identity, platform scope, audit, and consent rules do not change.

## Integration workflow

1. Declare the current store path, party side, and a domain-neutral narrative. Never put
   category-specific fields in the mall request unless the selected store owns that schema.
2. Authenticate with a Better Auth session for a human chat or an organization API key for a
   machine agent. Keep the key server-side and request only the smallest `platform:read`,
   `retrieval:query`, or marketplace permission needed.
3. Call the mall route boundary once. Treat selected stores, `source`, and `degraded` as advisory
   routing evidence, not as permission to disclose contact details or settle money.
4. At each selected store, invoke only the MCP tools advertised by its immutable manifest. The
   store owns its catalogue, vector store, embeddings, and ranking Skill; stores never route to
   other stores.
5. Return canonical asset/merchant references and explainable reasons. Ask the root to verify
   active listing state, seller authorization, exposure billing, and consent before introducing
   parties.
6. Release WeChat/phone/contact data only through the platform contact-consent flow after both
   parties opt in. A successful AI match is never consent.

## Token and failure policy

External buyer/seller agents pay for their own model calls. Mall-initiated selection has bounded
candidate, input/output, rate, and timeout limits with an auditable `cost_bearer: "platform"`
ledger. Do not retry a degraded response in a loop; surface it and let the caller decide whether
to try another provider.

Use [references/agent-envelope.md](references/agent-envelope.md) for request/result fields and
the minimal MCP tool contract. The normative JSON schemas remain in `docs/agent-mcp-skill-protocol-v1.json`,
`docs/platform-routing-protocol-v1.json`, and `docs/retrieval-protocol-v1.json`.