Context Plugins: Typed SDK References for Agent API Integration

Coding agents write working API calls. They struggle to write shippable API calls. The gap is not authentication or endpoint discovery. The gap is idempotent retries, rate-limit backoff, token refresh cycles, and pagination state.

APIMatic built a context registry that combines prose documentation with typed SDK reference code. They call the format a Context Plugin. The registry injects language-specific context when the agent touches an API integration. Across their benchmarks, this approach boosted one-shot production readiness by 34%, letting Sonnet match Opus baseline performance on the same integration tasks.

Twenty-four plugins are live for production APIs: Slack, Google Maps, Notion, Stripe, Twilio, Adyen. The registry is open for community use.

Most coding agents handle the happy path. They read OpenAPI specs, find the right endpoint, construct a request, and parse the response. The code runs. It is not production-ready.

Production-ready means:

OpenAPI specs do not teach these patterns. Markdown documentation dumps describe them in prose, but agents struggle to translate prose into correct retry logic. AGENTS.md files add context, but they are unstructured and language-agnostic.

APIMatic identified the gap by running integration benchmarks. Agents consistently missed production details even when the documentation mentioned them. The problem was not missing information. The problem was the format.

A Context Plugin is a structured bundle of API knowledge. It contains:

The registry injects the plugin when the agent starts working on an integration. The injection is automatic. The agent does not need to ask for it.

The registry watches for:

import stripe

, from slack_sdk import WebClient

)services/stripe_client.py

, lib/slack.ts

)When a trigger fires, the registry injects the relevant Context Plugin into the session. The agent sees typed examples in the language it is writing. It sees retry logic implemented correctly. It sees token refresh handled before the request, not after the 401.

A Context Plugin for Stripe in Python might include:

import stripe

stripe.api_key = os.environ["STRIPE_SECRET_KEY"]

payment_intent = stripe.PaymentIntent.create(
    amount=2000,
    currency="usd",
    idempotency_key=f"order_{order_id}",  # Prevents duplicate charges
    automatic_payment_methods={"enabled": True},
)

try:
    customer = stripe.Customer.create(email=email)
except stripe.error.RateLimitError as e:
    time.sleep(2 ** retry_count)
    customer = stripe.Customer.create(email=email)

The prose annotation explains why idempotency_key

matters. The code shows where to put it. The agent copies the pattern.

The key difference is typed SDK reference code. When the agent sees idempotency_key=f"order_{order_id}"

in a working example, it understands where the key goes and how to construct it. When it reads "use an idempotency key to prevent duplicate charges" in prose, it guesses.

APIMatic tested Context Plugins against three baselines:

The benchmark measured production readiness, not just working code. A task passed if the generated code handled retries, rate limits, and auth correctly on the first attempt.

Results across 24 APIs:

The 34% improvement (from 58% to 78%) came from typed examples. Sonnet with Context Plugins matched Opus baseline performance without plugins.

The registry is a web service. You install a plugin by adding it to your agent configuration. The registry does not run locally. It injects context over the network when the agent session starts.

context.apimatic.io

The registry returns a structured payload. The payload includes SDK code, prose annotations, and production patterns. The agent merges this into its working context.

The registry is stateless. It does not track sessions or store agent history. It returns the same context for every request. The agent manages session state locally.

This design keeps the registry simple. It also means the registry cannot adapt context based on what the agent already tried. If the agent makes the same mistake twice, the registry will not notice.

The registry does not see your code. It does not see your API keys. It does not see the agent's conversation history.

The agent sends a trigger signal (import statement, file pattern, or explicit query). The registry returns public documentation and SDK examples. No secrets cross the boundary.

Your API keys stay in your environment variables. The agent reads them locally. The Context Plugin shows where to read them (os.environ["STRIPE_SECRET_KEY"]

), but it does not provide the value.

The registry does not expose metrics about plugin usage. You cannot see how often the agent requested Stripe context or whether it used the retry pattern.

The agent logs its own activity. If you want to track Context Plugin effectiveness, you need to instrument the agent. Look for:

APIMatic published their benchmark methodology. You can replicate it to measure plugin effectiveness in your own environment.

The registry serves static context. If Stripe ships a breaking change, the plugin will not update automatically. You will need to wait for APIMatic to publish a new version.

Mitigation: Check the plugin version before starting a new integration. The registry shows the last update date for each plugin.

The registry injects language-specific context. If you switch languages mid-session (start in Python, then write a TypeScript client), the agent might see Python examples when it needs TypeScript.

Mitigation: The registry detects language from import statements and file extensions. Keep language boundaries clear in your project structure.

If you work on multiple APIs in one session, the agent might receive context for all of them. This bloats the context window and slows the agent.

Mitigation: Work on one API integration at a time. Clear the session before switching to a different API.

The registry has 24 plugins. If you need an API that is not covered, you fall back to OpenAPI specs or markdown docs.

Mitigation: APIMatic accepts community contributions. You can build a plugin for your API and submit it to the registry.

Use Context Plugins when:

Avoid Context Plugins when:

The registry solves a real problem: agents write working code but miss production details. Typed SDK examples close that gap better than prose or schemas. The trade-off is dependency on an external service and limited coverage (24 APIs so far).

If your integration is in the registry and you ship code daily, the 34% improvement in one-shot readiness is worth the dependency. If you are building custom integrations or need air-gapped operation, stick with local MCP servers and curated documentation.