@agentskit/integrations — for agents

#Install

npm install @agentskit/integrations

#What it is

One descriptor per service (Integration) that every consumer layer projects from — agent tools, connector senders, inbound triggers, OAuth specs, marketplace listings. Eliminates the per-service duplication that otherwise spreads across @agentskit/tools and host runtimes. Dependency-light: only @agentskit/core, with fetch + node:crypto at runtime. The catalog of concrete services is populated in later phases; this entry ships the contract + registry.

#Primary exports (main entry)

• defineIntegration — author an Integration descriptor (auth, actions, triggers, capabilities).
• defineAction — define one action; receives an auth-bound IntegrationHttp client, uses canonical JSON Schema.
• defineTrigger — define one inbound trigger (verify signature + normalize to a uniform event).
• httpJson — shared HTTP helper (query/body/timeout, non-2xx → typed error).
• bindHttp — bind options into a reusable IntegrationHttp client.
• createRegistry — build an isolated catalog instance.
• registerIntegration — register a descriptor into the default catalog.
• getIntegration — look up a descriptor by service slug.
• listIntegrations — list all registered descriptors.
• integrationsByCategory — filter the default catalog by category.
• toToolDefinitions — project a descriptor's actions into legacy ToolDefinition[] (auth-bound), preserving the fn(config) => Tool[] API consumers expect.
• actionToToolDefinition — project a single action into a ToolDefinition.
• httpOptionsFor — build the auth-bound HTTP options for a descriptor + caller config.
• integrationTools — resolve a catalog integration (by slug or descriptor) and project it to ToolDefinition[] in one call.
• integrationToolsFromEnv — project an integration reading its credential from the environment (via the apiKey envHint).
• credentialEnvVar — the conventional env var holding an integration's API key.
• CONFIG_FIELDS — declarative connect-form fields (ConfigField[]) for services that authenticate with structured config (Twilio, Jira, Stripe, …) rather than a single API key; attached to each descriptor's configFields.

#Subpath exports

#Minimal example

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

const ping = defineAction({
  name: 'demo_ping',
  description: 'Echo a message.',
  schema: { type: 'object', properties: { message: { type: 'string' } }, required: ['message'] },
  sideEffect: 'read',
  execute: (args, http) => http({ method: 'POST', path: '/ping', body: { message: args.message } }),
})

export const demo = defineIntegration({
  name: 'demo',
  displayName: 'Demo',
  categories: ['example'],
  http: { baseUrl: 'https://api.example.com' },
  auth: { kind: 'apiKey', header: 'authorization', prefix: 'Bearer ' },
  actions: [ping],
  capabilities: {},
})

#Scaffolding

pnpm gen:integration <name>   # copies services/_template → services/<name>

#Related

• Tools — @agentskit/tools (legacy integration home; being unified here).