| 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
- 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.
- 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.
- 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.
- 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.
- 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.
- 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 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.
