Platform API

The platform exposes a programmatic API for running agents and reading their results from your own services. The @kraken-ai/platform SDK is the supported surface — it speaks the HTTP API for you with full type safety.

#Overview

Anything you can do in the control plane — run an agent, stream its execution, inspect past runs, read pipeline data — you can do from your own code. The API is HTTP under the hood, but the supported surface is the PlatformClient in @kraken-ai/platform: it handles authentication, request shaping, and event streaming, and infers agent input and output types from your generated definitions.

#Authentication

Programmatic access uses an API key sent as a bearer token. Create and manage keys with the kraken api-keys CLI command or in the control plane under Settings → API Keys. A key is shown once at creation time.

$ kraken api-keys create --name "my-app"

The client reads credentials from the environment, so you rarely pass them in code:

If neither the environment nor explicit constructor options provide a value, the client falls back to credentials stored by kraken login.

#PlatformClient

Construct a PlatformClient and get a typed handle to an agent with client.agent(id). Call generate to start a run; consume stream() for live events and result for the final structured output.

import { PlatformClient } from "@kraken-ai/platform";

// Resolves credentials from KRAKEN_BASE_URL / KRAKEN_API_KEY,
// or from `kraken login`. Pass { baseUrl, apiKey } to override.
const client = new PlatformClient();

const researcher = client.agent("researcher");

const run = await researcher.generate(
  "Summarize the files in the data directory",
);

for await (const event of run.stream()) {
  if (event.type === "text") process.stdout.write(event.content);
}

const output = await run.result;
console.log("Result:", output);

The client also exposes client.agents, client.runs, client.data, and client.pipelines namespaces. After running kraken generate, agent ids autocomplete and each agent’s input, output, and action payloads are fully typed. See the Platform SDK for the complete surface.

#Capabilities

Through the SDK you can:

• Run agents — start a run from your own service and send follow-up messages in the same thread.
• Stream run events — consume text, reasoning, tool, and action events live as the agent executes.
• Handle actions — register typed handlers that fire as the agent emits structured actions during a run.
• Inspect runs — list and retrieve past runs and their outcomes.
• Access pipelines and data — read the datasets your scheduled pipelines produce.

#CLI authentication

For interactive use, kraken login authenticates against a platform instance with a browser-based device-code flow: the CLI prints a code, you approve it in the browser, and the resulting credentials are stored locally. The SDK then picks them up automatically when no environment variables are set. See the CLI reference for the full flow.

#Rate & quotas

Platform usage is metered. Consumption and limits are visible in the control plane, and per-deployment quotas depend on your plan. Design programmatic clients to handle transient errors with retry and backoff, and prefer streaming over polling for live run output.

#Next steps

• Platform SDK — The full PlatformClient surface: agents, runs, data, pipelines, and typed action handlers.
• CLI — Authenticate, manage API keys, and generate types with the kraken command-line interface.
• Deployment — Connect a repository so every push builds and deploys your agents and pipelines.