Pimsy LLM

Custom Connectors

Conceptual

Wrapping an internal API into typed, policy-aware tools.

A custom connector is a manifest plus a set of tool definitions. Generating it from an OpenAPI document is usually the fastest correct path.

connectors/inventory/manifest.ts
import { defineConnector } from class="tok-str">"@pimsy/sdk";

export default defineConnector({
  name: class="tok-str">"inventory",
  displayName: class="tok-str">"Warehouse Inventory",
  baseUrl: class="tok-str">"https://inventory.internal.example.com",
  auth: {
    type: class="tok-str">"oauth2_client_credentials",
    tokenUrl: class="tok-str">"https://auth.internal.example.com/token",
    scopes: [class="tok-str">"inventory.read", class="tok-str">"inventory.adjust"]
  },
  rate: { requestsPerSecond: class="tok-num">10, burst: class="tok-num">20 },
  tools: [
    { module: class="tok-str">"./tools/lookup", scope: class="tok-str">"connector.inventory", effectClass: class="tok-str">"read_external" },
    { module: class="tok-str">"./tools/adjust", scope: class="tok-str">"connector.inventory.write", effectClass: class="tok-str">"external_write",
      idempotency: class="tok-str">"required", approval: class="tok-str">"always" }
  ],
  errorMap: {
    class="tok-num">404: class="tok-str">"not_found",
    class="tok-num">409: class="tok-str">"precondition_failed",
    class="tok-num">429: class="tok-str">"rate_limited",
    class="tok-str">"5xx": class="tok-str">"upstream_5xx"
  }
});

Checklist before shipping#

  1. 1Every write operation supports an idempotency key.
  2. 2Errors map onto the runtime taxonomy so retries behave correctly.
  3. 3Descriptions state the trigger condition and the meaning of an empty result.
  4. 4Effect classes are honest — a "sync" endpoint that emails customers is communication.
  5. 5Rate limits reflect what the upstream actually tolerates under concurrency.
  6. 6A dry-run or preview mode exists for destructive operations.

Last updated 2026-09-07