> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corti.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```ts theme={null}
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()`.

```ts theme={null}
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.

```ts theme={null}
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:**

```ts theme={null}
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.

```ts theme={null}
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:**

```ts theme={null}
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.

```ts theme={null}
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`.

```ts theme={null}
type CortiTextPart = string;
```

***

### `CortiJSONPart`

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

```ts theme={null}
type CortiJSONPart = JSONValue;
```

***

### `CortiStatusUpdate`

A status update emitted by the agent during streaming.

```ts theme={null}
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.

```ts theme={null}
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.

```ts theme={null}
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. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.