Keiki

https://onkeiki.com/docs
Admin
Keiki is an AI agent platform that enables businesses to build, host, and deploy autonomous agents...
Tokens:97,576
Snippets:635
Trust Score:6.1
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install @onkeiki/agents and Postgres storage with bun

Source: https://onkeiki.com/docs/sdk

Install the SDK and the Postgres storage adapter using bun. Required before using the SDK.

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

--------------------------------

### Install @onkeiki/agents-plugins with bun

Source: https://onkeiki.com/docs/cloud-agents

Adds the plugins package to your project. Run this command to install the package before using any plugins.

```bash
bun add @onkeiki/agents-plugins
```

--------------------------------

### Install @onkeiki/ai-sdk with bun

Source: https://onkeiki.com/docs/ai-sdk

Install the required packages for the AI SDK integration. Use this command in your project to add @onkeiki/ai-sdk, ai, and @ai-sdk/mcp.

```sh
bun add @onkeiki/ai-sdk ai @ai-sdk/mcp
```

--------------------------------

### Install @onkeiki/eve

Source: https://onkeiki.com/docs/eve

Install the @onkeiki/eve package. Requires Node.js 24 or later. Alternatively, run npx @onkeiki/cli init to set up the integration automatically.

```sh
npm install @onkeiki/eve
```

--------------------------------

### Install Hermes harness with curl

Source: https://onkeiki.com/docs/harnesses

Runs the Keiki harness installer on a host machine. Requires a Keiki API key and installs Hermes, enables its OpenAI-compatible API server, registers Keiki's MCP server and observability plugin, stores the local Hermes key as an encrypted secret, and points the agent at the host. Safe to run again. Options are passed via CONNECTIVITY; set HERMES_BIN if the binary is not on PATH, and HERMES_INSIDE_GATEWAY=1 when running inside the gateway to skip the restart.

```sh
curl -fsSL https://<your-keiki-host>/api/v1/harness/install.sh \
  | KEIKI_API_KEY=sk_live_… bash
```

--------------------------------

### createServer

Source: https://onkeiki.com/docs/sdk

Starts the turn-handling HTTP server. This is what kit.serve() wraps.

```APIDOC
## createServer

### Description
Starts the turn-handling HTTP server. This is what `kit.serve()` wraps.

### Method
Function

### Signature
`createServer`

### Returns
HTTP server instance
```

--------------------------------

### GET /ping

Source: https://onkeiki.com/docs/external-channel-evals

Setup check for the external channel eval driver.

```APIDOC
## GET /ping?driver=imessage

### Description
A setup check that returns the agent, driver, channel, and target for the given driver. It never claims a run.

### Method
GET

### Endpoint
/api/v1/evals/channel/ping

### Parameters
#### Query Parameters
- **driver** (string) - Required - The driver to check, e.g., `imessage`.

### Response
#### Success Response (200)
- **agent_id** (string) - The agent identifier.
- **driver** (string) - The driver name.
- **channel** (string) - The channel name.
- **target** (string) - The target handle.

#### Response Example
{
  "agent_id": "agent_...",
  "driver": "imessage",
  "channel": "sms",
  "target": "+15550001111"
}
```

--------------------------------

### Install @onkeiki/flue and @flue/runtime

Source: https://onkeiki.com/docs/flue

Install the required packages for integrating Flue with Keiki. Use a current Node release for local development; Cloudflare targets need nodejs_compat because the channel signing helper uses the Node-compatible crypto API.

```sh
npm install @onkeiki/flue @flue/runtime
```

--------------------------------

### Start tunnel supervisor with curl and sh

Source: https://onkeiki.com/docs/external-harness

Run this command after starting your HTTP server. It downloads and executes the tunnel script, setting KEIKI_API_KEY and PORT. TUNNEL defaults to cloudflared, HARNESS to external, KEIKI_HOME to ~/.keiki. The script verifies the key and harness, warns if nothing is listening on PORT, and starts a detached supervisor that manages only the tunnel.

```sh
curl -fsSL https://<your-keiki-host>/api/v1/harness/tunnel.sh \
  | KEIKI_API_KEY=sk_live_… PORT=8789 sh
```

--------------------------------

### Install Hermes with public URL connectivity

Source: https://onkeiki.com/docs/harnesses

Installs the Hermes harness using a public URL for connectivity. Requires a Keiki API key, the Keiki host URL, and the HERMES_PUBLIC_URL environment variable.

```sh
curl -fsSL https://<your-keiki-host>/api/v1/harness/install.sh \
  | KEIKI_API_KEY=sk_live_… CONNECTIVITY=public-url \
    HERMES_PUBLIC_URL=https://hermes.example.com bash
```

--------------------------------

### Install Hermes with relay connectivity

Source: https://onkeiki.com/docs/harnesses

Installs the Hermes harness using the default relay mode. Requires a Keiki API key and the Keiki host URL.

```sh
curl -fsSL https://<your-keiki-host>/api/v1/harness/install.sh \
  | KEIKI_API_KEY=sk_live_… CONNECTIVITY=relay bash
```

--------------------------------

### Install @onkeiki/agents with bun

Source: https://onkeiki.com/docs/cloud-agents

Adds the @onkeiki/agents package to your project.

```bash
bun add @onkeiki/agents
```

--------------------------------

### POST /runs

Source: https://onkeiki.com/docs/external-channel-evals

Starts an external channel eval run.

```APIDOC
## POST /runs

### Description
Starts an external channel eval run. Returns run details, target, eligible cases, and excluded cases.

### Method
POST

### Endpoint
/api/v1/evals/channel/runs

### Parameters
#### Request Body
- **driver** (string) - Required - The driver name: `imessage`, `sms`, `slack`, `telegram`, `whatsapp`, `email`, or `x`.
- **case_ids** (array of strings) - Optional - Specific case IDs to run.

### Request Example
{
  "driver": "imessage",
  "case_ids": ["case_1", "case_2"]
}

### Response
#### Success Response (200)
- **run_id** (string) - The run identifier.
- **driver** (string) - The driver name.
- **target** (object) - The target channel and handle.
- **cases** (array) - List of eligible cases with id, name, prompt, and history.
- **excluded** (array) - List of excluded cases with id, name, and reason.
- **quiet_ms** (number) - Quiet period in milliseconds.
- **timeout_ms** (number) - Timeout in milliseconds.

#### Response Example
{
  "run_id": "evalrun_...",
  "driver": "imessage",
  "target": { "channel": "sms", "handle": "+15550001111" },
  "cases": [
    {
      "id": "...",
      "name": "SMS: answers in one message",
      "prompt": "...",
      "history": [{ "role": "user", "content": "..." }]
    }
  ],
  "excluded": [{ "id": "...", "name": "Retries a failing tool", "reason": "mocked tools" }],
  "quiet_ms": 8000,
  "timeout_ms": 180000
}

### Error Handling
- **409** - A channel run for the agent is already in flight, or the agent has no active line on the channel.
- **400** - No case is eligible.
```

--------------------------------

### Capability manifest example (JSONC)

Source: https://onkeiki.com/docs/capabilities

A complete example of a capability manifest in JSONC format. It shows the required fields like slug, version, title, description, runtime, uses, secrets, tools, http, prompt, loops, entities, and templates. The runtime is 'render-template' and the manifest includes a tool named 'render_cards'.

```jsonc
{
  "slug": "cards",              // unique per publisher, [a-z0-9-]
  "version": "1.0.0",           // semver; installs pin an exact version
  "title": "Cards",
  "description": "Render swipeable image card carousels and deliver them as one media message.",

  // How the capability's tools run. One of:
  //   render-template  slides rendered to images by the rendering service
  //   openapi          an OpenAPI source plus OAuth (the user-connections path)
  //   codemode         a small program the agent writes over granted namespaces
  //   mcp              an MCP server source
  //   builtin          a Keiki builtin (official capabilities only)
  "runtime": "render-template",

  // The host namespaces this capability may reach. A namespace you do not
  // list here is not available to it.
  "uses": ["loops", "entities"],

  // Secrets the installer provides. They are resolved per call and never handed
  // to code the model wrote.
  "secrets": [
    { "name": "RENDER_SERVICE_URL", "required": false, "description": "Override the shared rendering service." }
  ],

  // The tools this capability adds to an agent.
  "tools": [
    {
      "name": "render_cards",
      "description": "...",
      "inputSchema": { "type": "object", "properties": { /* ... */ } },
      "run": { "kind": "render-template", "template": "story" }
    }
  ],

  // The hosts the `http` namespace may reach (required with uses: ["http"]).
  // A leading "*." matches subdomains. HTTPS only.
  "http": { "allow": ["api.example.com"] },

  // Guidance added to the agent's system prompt while the capability is installed.
  "prompt": "Use render_cards only for genuinely multi-beat stories...",

  // Loop presets registered while installed (requires uses: ["loops"]).
  "loops": [
    { "name": "daily-digest", "scheduleType": "cron", "scheduleExpression": "0 8 * * *", "quiet": true, "prompt": "..." }
  ],

  // The entities this capability stores data in (requires uses: ["entities"]).
  "entities": ["digest_state"],

  // Card templates uploaded to the rendering service for your account
  // (render-template runtime only).
  "templates": [
    { "name": "story", "source": "...tsx source...", "inputSchema": { "fields": [ /* ... */ ] } }
  ]
}
```

--------------------------------

### AgentKitInstance.serve({ port?, host? })

Source: https://onkeiki.com/docs/sdk

Starts the HTTP server that receives turn requests from the platform and runs the loop on your machine. It syncs first.

```APIDOC
## AgentKitInstance.serve({ port?, host? })

### Description
Starts the HTTP server that receives turn requests from the platform and runs the loop on your machine. It syncs first.

### Method
function

### Parameters
- **port** (number) - Optional - The port to listen on.
- **host** (string) - Optional - The host to bind to.

### Returns
- **Promise** - Resolves when the server starts.
```

--------------------------------

### GET /api/v1/traces?status=error

Source: https://onkeiki.com/docs/partner-deployments

Lists traces with a given status. The example shows listing failed traces.

```APIDOC
## GET /api/v1/traces?status=error

### Description
Lists traces with a given status. The example shows listing failed traces.

### Method
GET

### Endpoint
/api/v1/traces

### Parameters
#### Query Parameters
- **status** (string) - Optional - Filter traces by status. Example: error.

### Response
#### Success Response (200)
- **traces** (array) - List of trace objects.

#### Response Example
{
  "traces": []
}
```

--------------------------------

### Configure MCP plugin with sandbox

Source: https://onkeiki.com/docs/cloud-agents

Shows how to configure the mcp() plugin, which requires sandbox() and throws at boot without it. The example sets maxServers, userCanAdd, and a list of servers.

```ts
import { sandbox, mcp } from '@onkeiki/agents-plugins'

const kit = AgentKit.create({
  // ...
  plugins: [
    sandbox({ persistent: true }),
    mcp({
      maxServers: 5,
      userCanAdd: true,
      servers: [{ url: 'https://my-internal-mcp.example.com/mcp' }],
    }),
  ],
})
```

--------------------------------

### Initialize Keiki CLI

Source: https://onkeiki.com/docs/cli

Run in your application directory to initialize the Keiki external harness. Detects the framework from package.json dependencies and writes the appropriate integration files.

```sh
npx @onkeiki/cli init
```

--------------------------------

### create

Source: https://onkeiki.com/docs/sdk

Creates a Keiki agent kit instance with configuration for API key, name, number resolution, storage, and agent settings. Returns a kit object with `sync()` and `serve()` methods.

```APIDOC
## create

### Description
Creates a Keiki agent kit instance with configuration for API key, name, number resolution, storage, and agent settings. Returns a kit object with `sync()` and `serve()` methods.

### Method
create

### Endpoint
create

### Parameters
#### Request Body
- **apiKey** (string) - Required - API key for the Keiki platform.
- **name** (string) - Required - Name of the agent.
- **resolveNumber** (function) - Required - Function that resolves the phone number to use, given a context.
- **storage** (object) - Required - Storage adapter for the agent.
- **agent** (object) - Required - Agent configuration.
  - **model** (string) - Required - Model identifier.
  - **maxSteps** (number) - Required - Maximum number of steps.
  - **historyLimit** (number) - Required - History limit.
  - **systemPrompt** (function) - Required - Function that returns the system prompt.
  - **tools** (array) - Required - List of tools.

### Request Example
```ts
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: [],
  },
})
```

### Response
#### Success Response
- **kit** (object) - The kit instance with `sync()` and `serve()` methods.

#### Response Example
```ts
const kit = create({ ... })
```
```

--------------------------------

### GET /api/v1/keys

Source: https://onkeiki.com/docs/cloud-agents

Lists all API keys for the organization.

```APIDOC
## GET /api/v1/keys

### Description
Lists all API keys for the organization.

### Method
GET

### Endpoint
https://<your-host>/api/v1/keys

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token with admin or key management permissions.
- **X-Org-Id** (string) - Required - The organization ID.

### Response
#### Success Response (200)
- **keys** (array) - List of API key objects.

#### Response Example
[
  {
    "id": "key-id",
    "name": "Production Agent",
    "scopes": ["*"]
  }
]
```

--------------------------------

### Create AgentKit with plugins

Source: https://onkeiki.com/docs/cloud-agents

Shows how to create an AgentKit instance with various plugins: memory, browser, steering, media, observability, and alerts. The agent config includes model, maxSteps, historyLimit, systemPrompt, and custom tools. The kit.sync() call is required to sync the agent.

```ts
import { AgentKit } from '@onkeiki/agents'
import { memory, browser, steering, media, observability, alerts } from '@onkeiki/agents-plugins'

const kit = AgentKit.create({
  apiKey: process.env.KEIKI_API_KEY!,
  name: 'My Agent',

  plugins: [
    memory({ autoRetrieve: true }),
    browser({ handoff: true, screenshotDelivery: true }),
    steering({ debounceWindow: '2 seconds', midTurnStrategy: 'interrupt', maxBatch: 5 }),
    media({ audio: 'transcribe', image: 'describe', video: 'describe', document: 'extract' }),
    observability({ exporters: [braintrustExporter({ apiKey: '...', projectName: 'my-agent' })] }),
    alerts({ alerts: [dailyBriefing] }),
  ],

  agent: {
    model: '<model-id>',
    maxSteps: 10,
    historyLimit: 40,
    systemPrompt: () => `...`,
    tools: [myCustomTool],  // only your custom tools here
  },
})

await kit.sync()
```

--------------------------------

### GET /api/v1/evals/diffs

Source: https://onkeiki.com/docs/evals

Reads a comparison between two runs.

```APIDOC
## GET /api/v1/evals/diffs

### Description
Reads a comparison between two runs.

### Method
GET

### Endpoint
/api/v1/evals/diffs

### Parameters
#### Query Parameters
- **diff_id** (string) - Required - The ID of the comparison to read.

### Response
#### Success Response (200)
- **diff** (object) - The comparison data.

#### Response Example
{
  "diff": {}
}
```

--------------------------------

### Create and sync or serve a Keiki agent with @onkeiki/agents

Source: https://onkeiki.com/docs/sdk

Defines an agent with `create()`, configuring API key, name, resolveNumber, storage, and agent options. Then either syncs to the cloud with `kit.sync()` or runs the loop yourself with `kit.serve()` (commented out).

```ts
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 })
```

--------------------------------

### AgentKitInstance.sync()

Source: https://onkeiki.com/docs/sdk

Pushes the full declarative config to the platform, including system prompt, tools, policies, model limits, harness, feature flags, loop presets, connections, capabilities, alerts, and secrets. Run on every deploy.

```APIDOC
## AgentKitInstance.sync()

### Description
Pushes the full declarative config to the platform: rendered system prompt, merged tools, 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.

### Method
function

### Parameters
None.

### Returns
- **Promise** - Resolves when the sync completes.
```

--------------------------------

### GET /api/v1/traces/{trace-id}

Source: https://onkeiki.com/docs/cloud-agents

Retrieves a single trace with all of its spans.

```APIDOC
## GET /api/v1/traces/{trace-id}

### Description
Retrieves a single trace with all of its spans.

### Method
GET

### Endpoint
https://<your-host>/api/v1/traces/{trace-id}

### Parameters
#### Path Parameters
- **trace-id** (string) - Required - The ID of the trace to retrieve.

### Response
#### Success Response (200)
- **id** (string) - The trace ID.
- **model** (string) - The model used.
- **tokens_in** (integer) - Number of input tokens.
- **tokens_out** (integer) - Number of output tokens.
- **steps** (integer) - Number of steps.
- **duration** (number) - Duration in seconds.
- **spans** (array) - List of spans, each with inputs, outputs, errors, and metadata.

#### Response Example
{
  "id": "trace-id",
  "model": "model-name",
  "tokens_in": 123,
  "tokens_out": 456,
  "steps": 5,
  "duration": 1.23,
  "spans": [
    {
      "type": "model",
      "input": "...",
      "output": "...",
      "error": null,
      "metadata": {}
    }
  ]
}
```

--------------------------------

### Sync config to Keiki with kit.sync()

Source: https://onkeiki.com/docs/cloud-agents

Pushes config, tools, and plugins to Keiki; Keiki runs everything. Use after configuring the agent.

```ts
await kit.sync() // push config, tools and plugins to Keiki; Keiki runs everything
```

--------------------------------

### GET /api/v1/developer/usage

Source: https://onkeiki.com/docs/cloud-agents

Checks usage for the API key or agent.

```APIDOC
## GET /api/v1/developer/usage

### Description
Checks usage for the API key or agent.

### Method
GET

### Endpoint
https://<your-host>/api/v1/developer/usage

### Authentication
Bearer token (API key)

### Request Example
```bash
curl -H "Authorization: Bearer $API_KEY" https://<your-host>/api/v1/developer/usage
```

### Response
#### Success Response (200)
- **usage** (object) - Usage details.

#### Response Example
(Not provided in source)

```

--------------------------------

### CapabilityLoop, CapabilityLoopProbe, CapabilityLoopTrigger

Source: https://onkeiki.com/docs/sdk

Types for loop presets registered while installed.

```APIDOC
## CapabilityLoop, CapabilityLoopProbe, CapabilityLoopTrigger

### Description
Loop presets registered while installed.
```

--------------------------------

### kit.serve()

Source: https://onkeiki.com/docs/sdk

Runs the agentic loop yourself, self-hosting the agent. Optionally accepts a port number for the server.

```APIDOC
## kit.serve()

### Description
Runs the agentic loop yourself, self-hosting the agent. Optionally accepts a port number for the server.

### Method
serve

### Endpoint
kit.serve()

### Parameters
#### Query Parameters
- **port** (number) - Optional - Port number for the server.

### Request Example
```ts
await kit.serve({ port: 8789 })
```

### Response
#### Success Response
No return value specified.

#### Response Example
```ts
await kit.serve({ port: 8789 })
```
```

--------------------------------

### GET /api/v1/evals/runs/:id/transcript

Source: https://onkeiki.com/docs/evals

Retrieves the turn transcript for a specific run.

```APIDOC
## GET /api/v1/evals/runs/:id/transcript

### Description
Retrieves the turn transcript for a specific run.

### Method
GET

### Endpoint
/api/v1/evals/runs/:id/transcript

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the run.

### Response
#### Success Response (200)
- **transcript** (object) - The turn transcript.

#### Response Example
{
  "transcript": {}
}
```

--------------------------------

### Create and sync an AgentKit agent

Source: https://onkeiki.com/docs/cloud-agents

Creates an AgentKit with API key, name, resolveNumber, and agent config, then syncs it. The systemPrompt uses user, now, and context. Requires KEIKI_API_KEY and SMS_LINE environment variables.

```ts
// src/index.ts
import { Effect } from 'effect'
import { AgentKit } from '@onkeiki/agents'

const kit = AgentKit.create({
  apiKey: process.env.KEIKI_API_KEY!,
  name: 'My Agent',

  resolveNumber: (ctx) => Effect.succeed(process.env.SMS_LINE!),

  agent: {
    model: '<model-id>',
    maxSteps: 10,
    historyLimit: 40,

    systemPrompt: ({ user, now, context }) => [
      `You are a helpful assistant.`,
      `Current time: ${now.toISOString()}`,
      context.memorySummary ? `\nAbout this user:\n${context.memorySummary}` : '',
    ].join('\n'),

    tools: [],
  },
})

await kit.sync()
```

--------------------------------

### GET /api/v1/evals/runs/:id/cases

Source: https://onkeiki.com/docs/evals

Retrieves per-case results for a specific run.

```APIDOC
## GET /api/v1/evals/runs/:id/cases

### Description
Retrieves per-case results for a specific run.

### Method
GET

### Endpoint
/api/v1/evals/runs/:id/cases

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the run.

### Response
#### Success Response (200)
- **cases** (array) - The per-case results.

#### Response Example
{
  "cases": []
}
```

--------------------------------

### GET /api/v1/evals/suggestions

Source: https://onkeiki.com/docs/evals

Retrieves suggested evaluation cases derived from your conversations.

```APIDOC
## GET /api/v1/evals/suggestions

### Description
Retrieves suggested evaluation cases derived from your conversations.

### Method
GET

### Endpoint
/api/v1/evals/suggestions

### Response
#### Success Response (200)
- **suggestions** (array) - The list of suggested cases.

#### Response Example
{
  "suggestions": []
}
```

--------------------------------

### CapabilityRef

Source: https://onkeiki.com/docs/sdk

Type for installing a published capability by exact publisher, slug, and version.

```APIDOC
## CapabilityRef

### Description
Install a published capability by exact `publisher`/`slug`/`version`.

### Type
`CapabilityRef`
```

--------------------------------

### Configure Keiki push dispatchUrl

Source: https://onkeiki.com/docs/eve

Configure the external harness with push connectivity and the dispatchUrl pointing to the mounted route POST /keiki/v1/dispatch. The timeoutMs is set to '10 minutes'.

```ts
const kit = AgentKit.create({
  // ...
  harness: {
    type: 'external',
    connectivity: 'push',
    dispatchUrl: 'https://your-eve-app.example/keiki/v1/dispatch',
    timeoutMs: '10 minutes',
  },
})
```

--------------------------------

### GET /api/v1/evals/cases/versions?agent_id=

Source: https://onkeiki.com/docs/evals

Retrieves the revision history of cases for a given agent.

```APIDOC
## GET /api/v1/evals/cases/versions?agent_id=

### Description
Retrieves the revision history of cases for a given agent.

### Method
GET

### Endpoint
/api/v1/evals/cases/versions?agent_id=

### Parameters
#### Query Parameters
- **agent_id** (string) - Required - The ID of the agent whose case versions are to be retrieved.

### Response
#### Success Response (200)
- **versions** (array) - The list of case revisions.

#### Response Example
{
  "versions": []
}
```
Tokens:
Raw