Skip to main content
The AgentStack TypeScript SDK builds on the Agent2Agent Protocol (A2A) and provides two layers:
  • A2A extensions and helpers that map agent demands to client fulfillments and UI metadata.
  • A platform API client that talks to the AgentStack server.
The SDK also exports A2A protocol types and Zod schemas so your UI can stay in sync with the protocol.

​
What the SDK Exports

The public surface of the SDK is grouped into four entrypoints:
  1. agentstack-sdk for everything
  2. agentstack-sdk/api for platform API client, schemas, and types
  3. agentstack-sdk/core for extension helpers and A2A interaction utilities
  4. agentstack-sdk/extensions for A2A extension definitions and types

​
Core Workflows

​
1. Handle agent card demands

Agents declare service demands in their agent card. Use handleAgentCard to read these demands and produce metadata fulfillments. 
import { handleAgentCard } from "agentstack-sdk";

const { demands, resolveMetadata } = handleAgentCard(agentCard);

const metadata = await resolveMetadata({
  llm: async (llmDemands) => {
    return {
      llm_fulfillments: {
        default: {
          identifier: "llm_proxy",
          api_base: "{platform_url}/api/v1/openai/",
          api_key: contextToken.token,
          api_model: "gpt-4o",
        },
      },
    };
  },
});
Use buildMessageBuilder(agentCard) when you want a helper that turns a user message into a fully formed A2A message with metadata.

​
2. Stream task status updates into UI actions

When you stream A2A task events, handleTaskStatusUpdate maps status updates into actionable UI events. It focuses on auth-required and input-required states, which cover OAuth, secrets, forms, and approvals. 
import { handleTaskStatusUpdate, TaskStatusUpdateType } from "agentstack-sdk";

for await (const event of stream) {
  if (event.kind === "status-update") {
    for (const update of handleTaskStatusUpdate(event)) {
      if (update.type === TaskStatusUpdateType.FormRequired) {
        // Render update.form
      }
    }
  }
}

​
3. Build user metadata

When the user responds to forms, approvals, or canvas requests, use resolveUserMetadata to build message metadata. 
import { resolveUserMetadata } from "agentstack-sdk";

const metadata = await resolveUserMetadata({
  form: { name: "Ada" },
  approvalResponse: { decision: "approve" },
});

​
4. Use the platform API client

buildApiClient exposes the platform API with typed responses and runtime validation. 
import { buildApiClient, createAuthenticatedFetch } from "agentstack-sdk";

const api = buildApiClient({
  baseUrl: "https://your-agentstack-instance.com",
  fetch: createAuthenticatedFetch("token-value"),
});
All API calls return ApiResult<T>. Use unwrapResult if you want exceptions, and then handle errors with isHttpError, isNetworkError, isParseError, and isValidationError.

​
Extension Helpers at a Glance

These helpers are factories. You pass an extension definition once and get back a function tailored to that extension.
  • extractServiceExtensionDemands(extension) returns a function that pulls typed demands for that service from an agent card.
  • fulfillServiceExtensionDemand(extension) returns a function that applies a fulfillment into outgoing metadata for that service.
  • extractUiExtensionData(extension) returns a function that reads typed UI metadata for that extension from messages.
  • buildLLMExtensionFulfillmentResolver(api, token) returns a resolver that maps LLM demands to platform models.

​
Protocol Types and Schemas

The SDK exports A2A protocol types and Zod schemas that match the AgentStack UI usage, including:
  • Message, Part, and Task types
  • TaskStatusUpdateEvent and TaskArtifactUpdateEvent
  • UI and service extension schemas
These exports are useful when building strongly typed UI layers or validating inbound messages.

​
Next Steps