@ag-kit/shared

Shared Zod schemas and TypeScript types for AG‑Kit request and event payloads

The @ag-kit/shared package centralizes the canonical Zod schemas and TypeScript types used by AG‑Kit servers, clients, and UIs. It defines the request payload for sending messages to an agent and the streaming event payloads returned over Server‑Sent Events (SSE), along with standard message and tool shapes.

Installation

npm

npm install @ag-kit/shared

What you get

• Schemas (Zod): sendMessageInputSchema, sendMessageEventSchema, systemMessageSchema, userMessageSchema, toolMessageSchema, assistantMessageSchema, clientMessageSchema, toolSchema
• Types (generated): SendMessageInput, SendMessageEvent, SystemMessage, UserMessage, ToolMessage, AssistantMessage, ClientMessage, Tool

Request payload

The strongly-typed request body for initiating or continuing a conversation with an agent.

import type { SendMessageInput } from "@ag-kit/shared";

type SendMessageInput = {
  conversationId: string;
  messages?: Array<
    | { role: "system"; content: string }
    | { role: "user"; content: string }
    | { role: "tool"; content: string; toolCallId: string }
    | {
        role: "assistant";
        content?: string;
        toolCalls?: Array<{
          id: string;
          type: "function";
          function: { name: string; arguments: string };
        }>;
      }
  >;
  resume?: { interruptId: string; payload: unknown };
  tools?: Array<{ name: string; description: string; parameters: any }>;
};

Validate at runtime with Zod when needed:

import { sendMessageInputSchema } from "@ag-kit/shared";

sendMessageInputSchema.parse(jsonBody);

Streaming events (SSE)

Agents respond by streaming a sequence of typed events over SSE.

import type { SendMessageEvent } from "@ag-kit/shared";

type SendMessageEvent =
  | { type: "text"; content: string }
  | { type: "tool-call-start"; toolCallId: string; toolCallName: string }
  | { type: "tool-call-args"; toolCallId: string; delta: string }
  | { type: "tool-call-end"; toolCallId: string }
  | { type: "tool-result"; toolCallId: string; result: string }
  | { type: "interrupt"; id: string; reason: string; payload: unknown };

Message shapes

Standardized message variants used in requests and by UIs:

type SystemMessage = { role: "system"; content: string };
type UserMessage = { role: "user"; content: string };
type ToolMessage = { role: "tool"; content: string; toolCallId: string };
type AssistantMessage = {
  role: "assistant";
  content?: string;
  toolCalls?: Array<{
    id: string;
    type: "function";
    function: { name: string; arguments: string };
  }>;
};
type ClientMessage = SystemMessage | UserMessage | ToolMessage | AssistantMessage;

Tool definition shape

Describe tools available to the agent (type only; UI/client execution is defined in @ag-kit/ui-react).

type Tool = {
  name: string;
  description: string;
  parameters: any; // shape of the tool input; commonly a Zod schema in UIs
};

Exports

// Schemas (Zod)
systemMessageSchema
userMessageSchema
toolMessageSchema
assistantMessageSchema
clientMessageSchema
toolSchema
sendMessageInputSchema
sendMessageEventSchema

// Types
SendMessageInput
ClientMessage
SystemMessage
UserMessage
ToolMessage
AssistantMessage
Tool
SendMessageEvent

See also

• Server overview — HTTP adapters and SSE endpoint that use these types
• React UI — client-side hooks that consume these events and message types