Agents

An agent is an autonomous worker that perceives data, reasons over it, and takes action. It is the unit you define, deploy, and operate on the platform.

#Overview

An agent perceives through connectors, learns procedures through skills, and produces structured actions. It is the unit you deploy: a single typed definition that the platform builds, runs in an isolated runtime, and governs end to end.

You author agents with the open Platform SDK. Each agent is one file in your project. Pushing the project to a connected repository builds and deploys every agent it contains; from then on, triggers start runs and the control plane streams each run live.

#Defining an agent

An agent is defined with definePlatformAgent from @kraken-ai/platform. The function validates the configuration at definition time and returns a frozen agent draft. You do not pass a name — an agent's identity is its filename: a file at src/agents/researcher.ts is the agent researcher.

import { definePlatformAgent } from "@kraken-ai/platform";
import filesystem from "../connectors/filesystem";
import researchGuidelines from "../skills/research-guidelines";

export default definePlatformAgent({
  model: "google/gemini-3-flash-preview",
  instructions:
    "You are a research agent. Use the filesystem tools to read and analyze files. Follow the research-guidelines skill for methodology.",
  skills: [researchGuidelines],
  connectors: [filesystem],
});

Connectors, skills, actions, and team members are passed as imported module references — not strings. The platform resolves each reference to its governed identity during discovery, so the wiring is type-checked in your editor before anything is deployed.

#Configuration

Every field below is optional except model and instructions. Capability arrays accept the modules you import from elsewhere in the project.

#Models

Models are referenced as provider-qualified strings — provider/model-id. The provider is chosen automatically from the prefix, so switching models is a one-line change with no other code modifications.

• Google — google/gemini-3-flash-preview, google/gemini-3.1-pro-preview.
• OpenAI — openai/gpt-5.4 (provider not yet implemented — selecting it raises a ProviderError).

#Structured output

Pass an outputSchema to constrain the agent's final result to a typed shape. The model is asked to produce JSON matching the schema and the response is validated before the run completes.

import { definePlatformAgent } from "@kraken-ai/platform";
import * as z from "zod";

export default definePlatformAgent({
  model: "google/gemini-3-flash-preview",
  instructions: "Classify the incoming support ticket.",
  outputSchema: z.object({
    category: z.enum(["billing", "technical", "account"]),
    urgency: z.number().describe("0 to 1"),
  }),
});

#Multi-agent teams

An agent becomes an orchestrator by listing other agents as team members. The orchestrator decides when to delegate; each member is itself a full agent with its own model, instructions, and capabilities. A member is wired in by importing it.

import { definePlatformAgent } from "@kraken-ai/platform";
import researcher from "./researcher";

export default definePlatformAgent({
  model: "google/gemini-3-flash-preview",
  instructions:
    "You are a summarizer agent that orchestrates research tasks. Delegate file reading and analysis to your researcher team member, then synthesize their findings into clear summaries.",
  team: { members: [researcher] },
});

Here summarizer delegates to researcher from the previous example. Delegation, like every other tool call, passes through governance and is recorded in the audit trail.

#The low-level SDK

Underneath the Platform SDK is kraken-ai, a standalone agent framework you can run locally with no platform dependency. It gives you the Agent class, tool(), and provider helpers like google() for direct, unmanaged control — useful for prototyping and tests.

import { Agent, tool, google } from "kraken-ai";
import { z } from "zod";

const lookupPrice = tool({
  name: "lookup_price",
  description: "Look up the current price of a product by SKU",
  parameters: z.object({ sku: z.string() }),
  execute: async ({ sku }) => ({ sku, price: 42 }),
});

const agent = new Agent({
  name: "pricing-analyst",
  model: google("gemini-3-flash-preview"),
  instructions: "You are a pricing analyst. Use tools to look up product data.",
  tools: [lookupPrice],
});

const result = await agent.run([
  { role: "user", content: "What is the price of SKU-4821?" },
]);
if (result.status === "complete") {
  console.log(result.output);
}

agent.run() returns a discriminated union: a complete result carries output, messages, and usage, while an interrupted result carries an interrupt and a resume function for human-in-the-loop pauses. See the Agent SDK reference for the full surface.

#Next steps

• Connectors — Give agents governed access to databases, APIs, SaaS tools, and MCP servers.
• Skills — Package composable, versioned procedures an agent loads and executes on demand.
• Triggers — Start an agent's runs on a schedule, from a signed webhook, or in response to platform events.
• Memory — Persist context across runs with scoped, policy-governed knowledge stores.
• Platform SDK — The full definePlatformAgent surface and the PlatformClient for server-side apps.