Best Practices
Use these principles after choosing an implementation route. Exact fields, status codes, and SDK methods stay in their owner references.
1. Keep the contract explicit
Use the current Protocol v1.0 request and response shape. Treat contract publication, runtime availability, and account access as separate facts.
2. Preserve user intent
Send the user's actual request and its provenance. Do not invent preferences, silently broaden constraints, or present an inferred request as user-provided.
3. Render structured offers
Use the returned title, description, action, and commercial context. Preserve tracked destinations and do not guess fields that the response omitted.
4. Keep Query constraints separate from Offer targeting
Use Category Taxonomy for explicit Query category constraints. Use Location Search for registry lookup, normalization, or preparing Partner Offer-side geo targeting. Query v1.0 has no viewer-location field, so a lookup result is neither Query context nor an automatic next task after Offer Query.
5. Design for recovery
Handle authentication failures, rate limits, retries, empty results, and unavailable runtimes without changing the user's intent or treating a failed request as a valid offer response. Use the API Reference for endpoint behavior and the Protocol source guide for canonical contract details.
Existing SDK integration?
Use the TypeScript migration guide or Python migration guide. Compatibility payloads are intentionally kept out of this page.
Reference map
- Quick Start for the default integration route.
- API Reference for endpoint behavior and reliability details.
- SDK Reference for current language-specific APIs.
- MCP for hosted runtime and tool access.
- Protocol for canonical source ownership.