Platform SDK

@kraken-ai/platform is the authoring and client surface for the Kraken platform. Declare agents, connectors, actions, and skills in a typed project, and invoke deployed agents from your own code with the PlatformClient.

#Installation

The @kraken-ai/platform package ships the authoring helpers, the PlatformClient, and the kraken CLI. It is already a dependency of every scaffolded project. To add it to an existing project:

$ pnpm add @kraken-ai/platform

Installing the package makes the kraken binary available for logging in, generating types, and running locally. See the CLI reference.

import {
  definePlatformAgent,
  defineConnector,
  defineTool,
  defineAction,
  definePackagedSkill,
  PlatformClient,
} from "@kraken-ai/platform";
import { z } from "zod";

#definePlatformAgent

definePlatformAgent(config) declares a platform-managed agent. It validates the scalar fields at definition time and returns a frozen draft. The agent's identity comes from its file path (  src/agents/<name>.ts ), never from a config field — so there is no name. Tools and a custom kernel are not permitted: capabilities come from connectors, teams from team.members, all injected by the platform through the governance gateway.

import { definePlatformAgent } from "@kraken-ai/platform";
import slack from "../connectors/slack";
import linear from "../connectors/linear";

// File path → identity = "market-analyst"
export default definePlatformAgent({
  model: "google/gemini-3-flash-preview",
  instructions: "You are a market research analyst.",
  connectors: [slack, linear],
  displayName: "Market Analyst",
});

#defineConnector & defineTool

defineConnector(definition) declares a connector that exposes tools, resources, and prompts to agents through the governed platform. Connector identity comes from the file path ( src/connectors/<name>.ts ). defineTool({ description, input, handler }) defines a single tool inside a connector, inferring the handler argument types from the Zod input schema.

import { defineConnector, defineTool } from "@kraken-ai/platform";
import { z } from "zod";

export default defineConnector({
  displayName: "Orakle",
  description: "Pricing intelligence for retail SKUs",
  requiredEnvVars: ["ORAKLE_API_KEY"],
  tools: {
    priceCheck: defineTool({
      description: "Look up a fair-market price band",
      input: z.object({ sku: z.string(), geo: z.string() }),
      handler: async ({ sku, geo }) => fetchPrice(sku, geo),
    }),
  },
});

requiredEnvVars declares the environment variables the connector needs at runtime; the platform provisions only the declared keys. For the full connector model, including resources and prompts, see Connectors and the Connector SDK.

#defineAction

defineAction({ schema, handler?, webhook? }) declares a standalone action — one of the agent's typed terminal decisions. The handler's payload type is inferred from the Zod schema. Action identity comes from the file path ( src/actions/<name>.ts ). Listing actions in an agent's actions array constrains its structured output to exactly one action.

import { defineAction } from "@kraken-ai/platform";
import { z } from "zod";

export default defineAction({
  schema: z.object({ reason: z.string(), confidence: z.number() }),
  handler: async (payload) => {
    payload.reason;     // string
    payload.confidence; // number
  },
});

See Actions for delivery, webhooks, and acknowledgement semantics.

#definePackagedSkill

definePackagedSkill(input) is the author-side factory for the directory-based Agent Skills layout. The project loader normally synthesizes packaged skills from a SKILL.md directory; this factory exists for tests and inline synthetic skills, and validates the input so invalid frontmatter cannot slip through. See Skills.

#PlatformClient

new PlatformClient(config?) connects to a deployed Kraken platform. config accepts an optional baseUrl and apiKey. When omitted, each value resolves in priority order: explicit config options first, then the KRAKEN_BASE_URL / KRAKEN_API_KEY environment variables (which override stored credentials), then credentials stored by kraken login. A missing endpoint or key throws at construction time.

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

const client = new PlatformClient({
  baseUrl: "https://your-platform.example.com",
  apiKey: process.env.KRAKEN_API_KEY,
});

const handle = client.agent("market-analyst");
const run = await handle.generate("Summarize this week's pricing moves");

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

const output = await run.result;

#AgentHandle

client.agent(id) returns an AgentHandle. When types have been generated with kraken generate, the input, output, and action payloads are inferred per agent.

Stream events are a discriminated union on type:

const handle = client.agent("market-analyst");

handle.onAction("approve", async (payload) => {
  await recordApproval(payload);
});

const run = await handle.generate("Review the Q3 pricing proposal");
const output = await run.result;

#Errors

Authoring and client failures surface as typed errors:

#Next steps

• Connector SDK — The full connector authoring surface: tools, resources, prompts, and the local connector server.
• Pipelines (Python) — Define typed data pipelines and expose their queries to agents and the PlatformClient.
• Platform API — The HTTP API the PlatformClient wraps: agents, threads, runs, data, and pipelines.