SDK reference

@onkeiki/agents is the SDK you use to define, configure, sync and self-host a Keiki agent. It is Effect-based and declarative: you describe the agent once, then either push it to the cloud with kit.sync() or run the loop yourself with kit.serve(). This page is the complete public API surface — the export list in packages/core/src/index.ts is canonical, and everything it exports appears here.

bun add @onkeiki/agents @onkeiki/agents-storage-postgres

import { Effect } from 'effect'
import { create } from '@onkeiki/agents'
import { PostgresStorage } from '@onkeiki/agents-storage-postgres'

const kit = create({
  apiKey: process.env.KEIKI_API_KEY!,
  name: 'My Agent',
  resolveNumber: (ctx) => Effect.succeed(process.env.SMS_LINE!),
  storage: PostgresStorage({ connectionString: process.env.DATABASE_URL! }),
  agent: {
    model: 'google/gemini-3.5-flash',
    maxSteps: 10,
    historyLimit: 40,
    systemPrompt: ({ now }) => `You are a helpful assistant. Current time: ${now.toISOString()}`,
    tools: [],
  },
})

// Cloud-served: the platform runs the agentic loop.
await kit.sync()

// Self-hosted: run the loop yourself instead.
// await kit.serve({ port: 8789 })

Cloud configuration in depth — tools, plugins, managed features, observability, storage, numbers and alerts — is covered in Cloud-served agents; this page maps the surface itself.

Agent lifecycle

• kit.sync() pushes the full declarative config to the platform: the rendered system prompt, merged tools (bundled for cloud execution), tool policies, model and step/history limits, harness, feature flags, loop presets, user connections, capabilities, alerts and developer secrets. It is the infrastructure-as-code operation; run it on every deploy.

• kit.serve({ port?, host? }) starts the HTTP server that receives turn requests from the platform and runs the loop on your machine. It syncs first.

• harness selects the turn runner. It defaults to { type: 'flue' } (Keiki-hosted); { type: 'hermes' } selects Hermes (guide). For an app that runs its own async loop, such as eve, Flue or AI SDK, use the external harness:

  TypeScript

  harness: {
    type: 'external',
    connectivity: 'push',
    dispatchUrl: 'https://agent.example.com/keiki/turn',
    timeoutMs: '5 minutes',
  }

  For relay mode, set connectivity: 'relay' and omit dispatchUrl. For an outside agent that long-polls instead of receiving a push, set connectivity: 'inbox' and also omit dispatchUrl; it uses a harness API key to claim turns. See the external harness contract. Unlike kit.serve(), which answers inside the same request, an external app accepts the dispatch asynchronously and replies through the turn endpoints. kit.sync() does not create the signing secret: call POST /api/v1/developer/agents/:agentId/harness/signing-secret once and store the returned secret. Include harness on every sync; omitting it sends flue and switches an existing Hermes or external agent back to Flue.

• kit.handleInbound(msg) processes one inbound message programmatically; kit.shutdown() stops gracefully.

• channels is a typed config surface (ChannelConfig) but is not yet forwarded by kit.sync() — identities are provisioned platform-side. Keep using resolveNumber for the SMS line.

The legacy SmsKit / SmsKitConfig / SmsKitInstance names are deprecated aliases of the AgentKit names and still exported.

Tools

ToolPolicy accepts requiredScopes (matched against the speaker's scopes from the identity webhook), approval: 'ask' | 'allow', previewTool, freshnessFields and descriptionArg.

ToolContext exposes phone, user, optional channel, blackboard, platform, userState, secrets, db, optional entityStore, and sandbox.

Alerts

Alerts support conditional delivery (shouldSend), deduplication (dedupKey), and multi-message output. Cloud-served agents register them through kit.sync(); the alerts plugin (below) serves the execution webhook.

Typed entities

Tenant-scoped, schema-validated persistence with generated tools.

Access is scoped by phone, queries are bounded, deletes are soft, and writes are audited.

Plugins

definePlugin builds a composable AgentKitPlugin. A plugin can contribute tools, alerts, HTTP routes and middleware, before/after turn hooks, before/after tool-call hooks, Effect layers, sync-payload transformations, and additive database migrations. Plugin order matters: later plugins see earlier config contributions.

The built-in plugins ship separately in @onkeiki/agents-plugins:

memory, browser, sandbox, executor, steering, media, escalation, observability, alerts, events, mcp, telegram, group-chat helpers (ObservationBuffer, composeGroupTurn, decideGroupTurn, …) and codemode (with entityCodemodeProvider, gmailCodemodeProvider and calendarCodemodeProvider sources).

Capability manifests

Capabilities are the packaging format behind every agent feature, official or yours — see Capabilities for the format and Rich cards for a worked official example. The SDK exports the types; write manifests with satisfies so mistakes fail at compile time:

import type { CapabilityManifest } from '@onkeiki/agents'

const manifest = { /* … */ } satisfies CapabilityManifest

A full manifest included in agent.capabilities is privately published and installed by kit.sync(); a CapabilityRef pins an already published one.

OAuth OpenAPI helpers

Helpers for building least-privilege OAuth OpenAPI documents for MCP and user connections:

oauthOpenApiSpec, googleOpenApiSpec, microsoftOpenApiSpec, OpenApiSpecError, GOOGLE_AUTHORIZATION_URL, GOOGLE_TOKEN_URL, MICROSOFT_AUTHORIZATION_URL, MICROSOFT_TOKEN_URL, and the OpenApiMethod, OpenApiOperation, OpenApiParameter, OpenApiParameterRef, OAuthOpenApiSpec, OAuthOpenApiSpecInput types. They validate duplicate operations, path parameters, methods, scopes, and over-broad provider scopes.

Self-hosting server

Service contracts and adapters

Effect context tags and interfaces for replacing the infrastructure under an agent. Cloud-served agents need none of these; self-hosted runtimes supply a storage adapter, and anything else can be swapped for your own implementation.

Storage adapters ship as separate packages:

Configuration and message types

AgentKitConfig is the top-level config (apiKey, name, agent, resolveNumber or channels, optional storage, harness, event handlers, secrets, ordered plugins). The AgentConfig beneath it and every feature type it composes are exported:

MemoryConfig, BrowserConfig, SandboxConfig, ExecutorConfig, SteeringConfig, MediaConfig, MediaActionConfig, EscalationConfig, EscalationRoute, EventHandlers, ObservabilityConfig, PromptContext, TurnHooks, TurnHookState, TurnReviewState, RetrievedContext, ResolveNumberContext, AcquireLineOpts, PhoneLine, DurationInput, HarnessConfig, StorageBundle, and the channel types ChannelType, ChannelConfig, SmsChannelConfig, TelegramChannelConfig. (ChannelType is open-ended; ChannelConfig currently models only SMS and Telegram.)

Message and user types: InboundMessage, OutboundMessage, StoredMessage, MediaPayload, SendResult, DeliveryStatus, Direction, UserProfile, Subscriber.

These are exported as types only, even where they are Effect schemas internally — build configs declaratively rather than constructing them at runtime.

Where to go next

• Cloud-served agents — the configuration guide for everything above.
• Self-hosting — kit.serve() and full-platform hosting.
• Capabilities and Publishing a capability — package new abilities for your agents or the marketplace.
• Governed actions and Identity and permissions — policy and scope enforcement around every tool call.