@agentskit/integrations

Profile: major-package

Tags: agentskit · typescript · ai-agents

Unified, plug-and-play service integrations for AgentsKit agents — one descriptor per service, projected into tools, connectors, triggers, and auth. Every integration is HTTP/fetch-only: no vendor SDKs are bundled or required (see ADR-0012). HTTP retry, timeout-signal, and bounded-reader behavior uses the @agentskit/net runtime dependency.

Verified proof

• Package metadata and tests live under packages/integrations/.
• Package guide: https://www.agentskit.io/docs/for-agents/integrations
• Stability map: docs/STABILITY.md

How this fits the ecosystem

@agentskit/integrations turns SaaS APIs into agent-ready tools, connectors, triggers, and auth from one service descriptor.

• AgentsKit: compose it with the other packages in this repo to build agents from small, swappable parts.
• Registry: look for ready agents and templates that already use this layer at registry.agentskit.io.
• Playbook: learn the production patterns behind this layer at playbook.agentskit.io.

Docs: package guide · agent handoff

Install

npm install @agentskit/integrations

Quick start

// Most consumers don't author integrations directly — they pull ready-made
// service descriptors from the registry and project them into tools:
import { integrationTools } from '@agentskit/integrations'

export const tools = integrationTools('slack', {
  credential: process.env.SLACK_BOT_TOKEN,
})

Service descriptors live under src/services/. The descriptor declares the service's actions, triggers, auth, and CONFIG_FIELDS; the projection helpers turn one descriptor into the surface each consumer needs (a ToolDefinition for the runtime, a connect-form for an app, a webhook trigger, etc.).

The catalog is a bundled, fetch-only set of ~50 services (ADR-0012). @agentskit/tools consumes this package rather than re-shipping integrations.

Authoring a new integration

import { defineIntegration, defineAction } from '@agentskit/integrations'

export const myService = defineIntegration({
  name: 'my-service',
  http: { baseUrl: 'https://api.example.com' },
  actions: [
    defineAction({
      name: 'send',
      schema: { type: 'object', properties: { to: { type: 'string' } }, required: ['to'] },
      execute: (args, { http }) => http({ method: 'POST', path: '/send', body: args }),
    }),
  ],
})

Execution boundaries (resilience & security)

Projection and HTTP share a small set of safety contracts (ADR-0026):

• HttpToolOptions.signal / ProjectionConfig.signal — caller cancellation composed with the per-request timeout.
• HttpToolOptions.retry — opt-in retries for idempotent methods only: one total attempt by default, with GET / PUT / DELETE retrying 408, 425, 429, 500, 502, 503, and 504 when configured for more attempts. Backoff starts at 100 ms, caps at 2 seconds, and has no jitter. Retry-After is bounded by that cap; delta seconds are rounded to the nearest millisecond by the shared parser. Network errors are not retried.
• Retry seams — sleep(delayMs) remains a one-argument callback; now() supplies the clock for HTTP-date Retry-After values. The overall timeout also ends a pending custom sleep wait.
• Timeout compatibility — composeTimeoutSignal remains deprecated through version 0.10.0 and for at least 90 days. Its cleanup() detaches the compatibility relay; the native timeout signal expires on its own clock.
• Origin-confined auth-bound HTTP — when baseUrl is set, httpJson rejects cross-origin paths and disables automatic redirects so bound credentials cannot leave that origin.
• Derived confirmation — projection forces requiresConfirmation for actions with sideEffect of write, external, or destructive (descriptors cannot opt out).
• ProjectionConfig.fetchUntrusted — policy-enforcing fetch for model-controlled URLs. Direct Whisper (and similar) consumers must inject an egress-policy fetch; the deprecated @agentskit/tools Whisper facade injects safeFetch independently of provider fetch.

Stability

beta — usable in production; the descriptor, registry, and projection contract are shipped, the fetch-only catalog is populated, and execution boundaries are explicit (ADR-0026). Not yet stable: public surface may still move in minor releases with CHANGELOG notes. Prefer ~x.y.z if you need tighter pins.

Maturity and compatibility

• Stability: beta — see docs/STABILITY.md
• Node.js 20+ and TypeScript strict mode
• Published as @agentskit/integrations

Contributing

See CONTRIBUTING.md and the monorepo LICENSE.