> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.astropods.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.astropods.com/_mcp/server.

# AI SDK

`@astropods/adapter-ai-sdk` exports two functions you can use independently:

* `astroTelemetry()` returns AI SDK `experimental_telemetry` settings wired to Astro's OTLP exporter.
* `serve()` connects a `ToolLoopAgent` (`Experimental_Agent`) to Astro's messaging service to make your agent compatible with the Astropods playground.

Targets `ai >= 6.0.0`.

## Install

```bash
bun add @astropods/adapter-ai-sdk
```

## Send telemetry to Astro

Add `astroTelemetry()` into the agent's `experimental_telemetry`:

```typescript
import { Experimental_Agent as Agent } from "ai";
import { openai } from "@ai-sdk/openai";
import { astroTelemetry } from "@astropods/adapter-ai-sdk";

const agent = new Agent({
  model: openai("gpt-4o"),
  instructions: "You are a helpful assistant.",
  experimental_telemetry: astroTelemetry(),
});
```

Use this on its own when you serve the agent from your own framework and want AI traces reported in the dashboard.

## Serve over Astro messaging

To run the agent on Astro messaging, pass it to `serve()`:

```typescript
import { Experimental_Agent as Agent } from "ai";
import { openai } from "@ai-sdk/openai";
import { serve, astroTelemetry } from "@astropods/adapter-ai-sdk";

const instructions = "You are a helpful assistant.";

const agent = new Agent({
  model: openai("gpt-4o"),
  instructions,
  experimental_telemetry: astroTelemetry(),
});

serve(agent, { name: "My Agent", instructions });
```

Passing `instructions` into the `serve()` function allows your agent's system prompt to be visible in the Astropods playground. This is optional. To hide your prompts exclude `instructions` from the `serve` call.

## Verify

Deploy the agent, send it a message, then open the agent's detail page in the dashboard. Traces appear within \~30 seconds.

If nothing shows up:

* Confirm `experimental_telemetry: astroTelemetry()` is on the agent.
* Confirm `OTEL_EXPORTER_OTLP_ENDPOINT` is set in the deployed container.
* Check the container logs for OpenTelemetry export errors.