Actions

Actions are the Act stage of the harness pipeline — structured, typed outputs an agent emits to drive downstream work. They are the controlled way an agent affects the world.

#Overview

Where connectors are how an agent perceives and reaches systems, actions are how an agent commits a decision. An action is a typed, structured output the agent produces — not free-form text — that feeds directly into your tools and workflows. Each action a project defines is a possible terminal decision the agent can make.

Like connectors, actions are plain modules. The file name is the identity: an action at src/actions/approve.ts is the approve action. This makes outbound effects explicit and reviewable — an agent affects the world only through the actions it has been given.

#Defining an action

Author an action with defineAction from @kraken-ai/platform. You provide a displayName, a Zod schema describing the action’s payload, and an optional webhook or in-process handler. The handler’s payload type is inferred from the schema, so it is fully typed end to end.

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

// Identity comes from the filename: src/actions/approve.ts → "approve".
export default defineAction({
  displayName: "Approve",
  schema: z.object({
    reason: z.string().describe("Why the document was approved"),
    confidence: z.number().describe("Confidence score between 0 and 1"),
  }),
  // webhook: "https://<webhook-url>/hooks/approved",
  handler: async (payload) => {
    // payload is fully typed: { reason: string; confidence: number }
    console.log(`Approved (${payload.confidence}): ${payload.reason}`);
  },
});

Attach actions to an agent through the actions array on definePlatformAgent. The agent’s structured output is then constrained to exactly one of the actions it was given. For the full agent definition surface, see Agents.

#Schema & validation

An action’s schema is the contract between the agent and your systems. The agent’s output is validated against the Zod schema before the action is delivered — an action that does not satisfy its schema does not go out.

schemaZodObjectRequired

A Zod object schema describing the action’s payload. The agent’s output is validated against it, and the handler’s payload type is inferred from it.

displayNamestringOptional

Human-readable name for the action, surfaced in the control plane.

webhookstringOptional

URL the validated payload is delivered to. Omit it to handle the action in process instead.

handler(payload) => Promise<void>Optional

In-process function invoked with the typed, validated payload. An alternative to webhook delivery for handling actions in your own code.

#Delivery

Once an action’s payload is validated, the platform delivers it one of two ways:

  • Signed webhook — the payload is sent to the configured webhook URL as a signed request, with automatic retries on transient failure.
  • In-process handler — the typed handler runs in your own code, invoked with the validated payload.

Delivery is not unconditional. The platform validates every action and can require human approval before an action is delivered — a reviewer confirms the decision, and only then does it reach your systems. See Human-in-the-Loop for how approval gates are configured.

Note

Actions make outbound effects explicit and typed, which is what makes a human gate meaningful: a reviewer approves a concrete, structured payload rather than a wall of model text.

#Governance & audit

An action is a real-world effect, so it is policy-evaluated like any other governed operation. Policy decides whether the action is allowed, denied, or escalated to a human before it is delivered, and the outcome is written to the immutable audit trail along with the decision context.

This makes every effect an agent has on your systems reconstructable after the fact: what was proposed, what policy decided, who approved it, and what was ultimately delivered. See Governance & Policies for policy evaluation and Audit & Compliance for the audit trail.

#Next steps

  • Human-in-the-Loop — Configure approval gates so a reviewer confirms a structured action payload before it is delivered.
  • Connectors — The other side of the harness: how agents perceive data and reach the tools they act through.
  • Platform SDK — Full reference for defineAction, schemas, webhooks, in-process handlers, and the PlatformClient.