AI SDK Adapter - API Reference

Functions, types, and options exported by @corti/ai-sdk-adapter

Complete API documentation for the @corti/ai-sdk-adapter package.

Functions

convertToParams()

Converts an array of CortiUIMessage objects (from the Vercel AI SDK useChat hook) into A2A MessageSendParams ready to send to a Corti agent.

function convertToParams(
  messages: CortiUIMessage[],
  credentials?: ExpertCredential[]
): MessageSendParams;

Parameter	Type	Required	Description
messages	CortiUIMessage[]	Yes	The messages array from useChat.
credentials	ExpertCredential[]	No	Credentials for MCP servers.

Returns: MessageSendParams — an A2A-compatible params object you can pass to client.sendMessage() or client.sendMessageStream().

Automatic behavior:

• Extracts contextId from the last assistant message to maintain conversation context.
• Includes taskId only when the last assistant message has state: 'input-required'.
• Attaches credentials only on the first message.

---

toUIMessageStream()

Converts an A2A streaming response into a UI message stream compatible with the Vercel AI SDK’s createUIMessageStreamResponse().

function toUIMessageStream(
  a2aStream: AsyncIterable<StreamEvent>,
  options?: StreamConversionOptions
): ReadableStream;

Parameter	Type	Required	Description
a2aStream	AsyncIterable<StreamEvent>	Yes	The stream returned by client.sendMessageStream().
options	StreamConversionOptions	No	Configuration including lifecycle callbacks.

Returns: ReadableStream — a stream you can pass to createUIMessageStreamResponse({ stream }).

---

createA2AClientFactory()

Creates a factory for building A2A clients that are pre-configured with Corti authentication.

function createA2AClientFactory(
  cortiClient: CortiClient
): A2AClientFactory;

Parameter	Type	Required	Description
cortiClient	CortiClient	Yes	An authenticated CortiClient instance from @corti/lib.

Returns: A2AClientFactory — a factory with a createFromUrl(url, agentId) method to build A2A clients.

Usage:

import { createA2AClientFactory } from '@corti/ai-sdk-adapter';
import { CortiClient } from '@corti/lib';

const corti = new CortiClient({ /* config */ });
const factory = createA2AClientFactory(corti);

const agentUrl = await corti.agents.getCardUrl("YOUR_AGENT_ID");
const client = factory.createFromUrl(agentUrl.toString(), '');

---

createFetchImplementation()

Creates a fetch-compatible function that automatically injects Corti authentication headers into every request. This is the lower-level primitive used internally by createA2AClientFactory(), but you can use it directly when you need a custom A2A client setup.

function createFetchImplementation(
  client: CortiClient
): (input: string | URL | Request, init?: RequestInit) => Promise<Response>;

Parameter	Type	Required	Description
client	CortiClient	Yes	An authenticated CortiClient instance from @corti/sdk.

Returns: A fetch-compatible function (input, init?) => Promise<Response> that adds Corti authentication to outgoing requests.

Usage:

import { createFetchImplementation } from '@corti/ai-sdk-adapter';
import { CortiClient } from '@corti/sdk';
import { ClientFactory } from '@a2a-js/sdk/client';

const corti = new CortiClient({ /* config */ });
const fetch = createFetchImplementation(corti);

// Use with A2A ClientFactory directly
const factory = new ClientFactory({ fetch });

---

Types

CortiUIMessage

Extends the standard Vercel AI SDK UIMessage with A2A-specific metadata and data parts.

import type { CortiUIMessage } from '@corti/ai-sdk-adapter';

Metadata fields:

Field	Type	Description
contextId	string	Conversation context identifier.
taskId	string	Task identifier for multi-turn interactions.
history	object[]	Conversation history from the A2A response.
credits	number	Credits consumed by this response.
state	string	Task state (e.g., 'completed', 'input-required').

Custom data parts:

Part discriminator	Type	Description
data-text	CortiTextPart	Text content with an optional name.
data-json	CortiJSONPart	Structured JSON data with a name.
data-status-update	CortiStatusUpdate	Status update from the agent.

---

CortiTextPart

A text data part. Alias for string.

type CortiTextPart = string;

---

CortiJSONPart

A JSON data part. Alias for JSONValue from @ai-sdk/provider.

type CortiJSONPart = JSONValue;

---

CortiStatusUpdate

A status update emitted by the agent during streaming.

type CortiStatusUpdate = {
  state: string;
  message?: string;
};

Field	Type	Required	Description
state	string	Yes	Current task state.
message	string	No	Optional human-readable status message.

---

ExpertCredential

Credentials for authenticating with MCP servers connected to a Corti agent.

type ExpertCredential =
  | {
      mcp_name: string;
      token: string;
      type: 'bearer';
    }
  | {
      mcp_name: string;
      client_id: string;
      client_secret: string;
      type: 'oauth2.0';
    };

Field	Type	Description
mcp_name	string	Name of the MCP server to authenticate with.
token	string	Bearer token (when type is 'bearer').
client_id	string	OAuth client ID (when type is 'oauth2.0').
client_secret	string	OAuth client secret (when type is 'oauth2.0').
type	'bearer' | 'oauth2.0'	Authentication method.

---

StreamConversionOptions

Options passed to toUIMessageStream() to configure stream behavior.

interface StreamConversionOptions {
  callbacks?: {
    onStart?: () => void;
    onEvent?: (event: StreamEvent) => void;
    onFinish?: (state: TaskStatus) => void;
    onError?: (error: Error) => void;
    onAbort?: () => void;
  };
}

Callback reference:

Callback	Parameters	Description
onStart	—	Called when streaming begins.
onEvent	event: StreamEvent	Called on each new event from the A2A stream.
onFinish	state: TaskStatus	Called when the stream completes with the final task status.
onError	error: Error	Called if an error occurs during streaming.
onAbort	—	Called when the stream is aborted by the client.