Author Sdk

Author an SDK driver (AIP-33)

Use when wrapping an in-process SDK as a conformant driver for AIP-14 TOOL contracts. SDKs are the right kind for self-hosted models, first-party convenience wrappers, and performance-critical paths where subprocess (CLI) or network (HTTP, MCP) latency is unacceptable.

Process

1. Identity: pick id ending in -sdk, set name, description, version, kind: sdk, package, package_manager.
2. Install + version_check: derive from package_manager:
   • npm / pnpm / yarn → install.method matches; version_check uses node -e "console.log(require('PACKAGE/package.json').version)".
   • pip / poetry → version_check uses python -c "import PACKAGE; print(PACKAGE.__version__)".
   • cargo → version_check uses cargo pkgid PACKAGE.
   • go → version_check uses go list -m PACKAGE.
   • local → vendored install, no version check (or workspace-relative package.json read).
3. Identify auth pattern:
   • Env-var read at construction: SDK reads a known env var (OPENAI_API_KEY); declare in auth.state.env.
   • Constructor arg: SDK takes apiKey in constructor; declare auth.state.env and rely on the runtime's secret-injection.
   • No auth: self-hosted models, offline tools — omit auth.
4. Per-tool dispatch: for each TOOL ref, author metadata.sdk:
   • function_ref (dotted: default, createImage, images.create, Client.images.create).
   • args_template only when contract input keys differ from SDK function args, OR when the function takes positional args (_0, _1, _2).
   • result_extract (JSONPath-lite) when the SDK return shape differs from the contract output.
   • cost_override.cost_units_per_call (millicents).
5. Streaming (when contract supports it): declare streaming.mode: "async-iterator" (or "callback"); per-tool override via metadata.sdk.streaming.
6. Sandbox + region + policy:
   • network.egress for SDKs that make HTTP calls under the hood (most LLM SDKs); [] for self-hosted offline.
   • region (US, EU, self-hosted, global).
   • policy_tags (third-party-llm, self-hosted, pii-safe, no-third-party).
7. Validate against SDK.schema.json AND DRIVER.schema.json.
8. Wire: loadProvider(...); the SDK runtime imports the package + resolves function refs at registration.

Common mistakes

• Forgetting import_style for non-default cases — Python, Rust, Go SDKs need explicit declaration.
• Constructor with secret in the manifest — secrets MUST be resolved via auth.state.env, not hardcoded in client_options.
• Wide network.egress — even SDKs that "should be offline" often phone home for telemetry; verify via tcpdump and declare the actual hosts.
• Module-load I/O — some SDKs do work at import time (open files, register handlers); hosts SHOULD warn on unexpected I/O at registration.
• Streaming generators not cancelled on abort — hosts MUST honour signal.abort() and break the loop. Driver authors test this explicitly.
• Missing package_version — without it, the resolver can't enforce version compatibility; SDK upgrades silently break tools.