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

# Migrating from Assistants API to Agents API

> Guide to migrating your integration from the legacy Assistants API to the new Agents API

<Info>
  The Agents API is the next generation of our API, designed for better compatibility with modern AI SDKs like the Vercel AI SDK.
</Info>

## Overview

The Agents API represents a significant improvement over the Assistants API, with the main goal of providing native compatibility with industry-standard AI SDKs. The key difference is the removal of custom input/output transformations in favor of standard formats.

### Why Migrate?

* **Vercel AI SDK compatibility**: Works natively with AI SDK 5's `useChat` function
* **Standard formats**: Uses industry-standard message formats instead of custom transformations
* **Better streaming**: Native support for AI SDK streaming patterns
* **Future-proof**: The Assistants API will be deprecated on 30 April

## Key Differences

### Endpoint Changes

| Assistants API                   | Agents API                   | Breaking?                 |
| -------------------------------- | ---------------------------- | ------------------------- |
| `/assistant/v1/chat/completions` | `/agent/v1/chat/completions` | Yes - Format changes      |
| `/assistant/v1/create`           | `/agent/v1/create`           | No - Only parameter names |
| `/assistant/v1/get`              | `/agent/v1/get`              | No - Only parameter names |
| `/assistant/v1/update`           | `/agent/v1/update`           | No - Only parameter names |
| `/assistant/v1/models`           | `/agent/v1/models`           | No - Identical            |

### Parameter Changes (Non-Breaking)

For create, get, and update endpoints, the only change is parameter naming:

* `assistantId` → `agentId`
* Request/response structure remains identical
* All other parameters unchanged

## Breaking Changes in `/chat/completions`

The chat completions endpoint has significant format changes to support Vercel AI SDK compatibility.

### Request Format Changes

#### Old Format (Assistants API)

```javascript theme={null}
{
  assistantId: "asst_123",
  messages: [
    {
      role: "user",
      content: "Hello, how are you?",  // Simple string content
      attachmentIds: ["uuid-1234"]
    }
  ],
  stream: true
}
```

#### New Format (Agents API)

```javascript theme={null}
{
  agentId: "agent_123",  // Parameter name changed
  messages: [
    {
      id: "msg_1",  // New: Message ID required
      role: "user",
      parts: [  // New: Parts array instead of content string
        {
          type: "text",
          text: "Hello, how are you?"
        }
      ],
      metadata: {
        attachments: ["uuid-1234"]  // New: Attachment format
      }
    }
  ],
  stream: true
}
```

### Key Request Differences

1. **Message Structure**:
   * Old: `content` as string
   * New: `parts` as array with typed objects

2. **Message ID**:
   * Old: Optional or auto-generated
   * New: Required `id` field for each message

3. **Attachments**:
   * Old: `attachmentIds` array at message level
   * New: `metadata.attachments` array on the message object

4. **Parameter Name**:
   * Old: `assistantId`
   * New: `agentId`

### Response Format Changes

#### Old Format (Assistants API)

```javascript theme={null}
{
  result: [
    {
      id: "msg_456",
      role: "assistant",
      content: [
        {
          type: "text",
          text: "I'm doing well, thank you!"
        }
      ]
    }
  ]
}
```

#### New Format (Agents API)

```javascript theme={null}
{
  messages: [
    {
      id: "msg_456",
      role: "assistant",
      content: "I'm doing well, thank you!"
    }
  ]
}
```

### Key Response Differences

1. **Top-level Structure**:
   * Old: Wrapped in `result` array
   * New: Wrapped in `messages` array

2. **Content Field**:
   * Old: `content` array
   * New: `content` string

### Streaming Changes

#### Old Format (Assistants API)

```
data: {"type":"message","content":"Hello"}
data: {"type":"message","content":" world"}
data: {"type":"done"}
```

#### New Format (Agents API)

Uses Vercel AI SDK streaming format:

```
0:"text chunk 1"
1:"text chunk 2"
...
```

The Agents API streams in Vercel AI SDK's native format, compatible with the `useChat` hook.

## Migration Steps

### Step 1: Update Endpoint URLs

```javascript theme={null}
// Before
const url = 'https://api.langdock.com/assistant/v1/chat/completions';

// After
const url = 'https://api.langdock.com/agent/v1/chat/completions';
```

### Step 2: Update Parameter Names (Non-Breaking Endpoints)

For create, get, update endpoints:

```javascript theme={null}
// Before
{ assistantId: "asst_123" }

// After
{ agentId: "agent_123" }
```

### Step 3: Update Message Format (Breaking - Chat Completions)

#### Converting Messages

```javascript theme={null}
// Before (Assistants API)
const oldMessage = {
  role: "user",
  content: "Analyze this document",
  attachmentIds: ["uuid-1234"]
};

// After (Agents API)
const newMessage = {
  id: generateId(), // You need to generate message IDs
  role: "user",
  parts: [
    {
      type: "text",
      text: "Analyze this document"
    }
  ],
  metadata: {
    attachments: ["uuid-1234"]
  }
};
```

#### Using with Vercel AI SDK

The Agents API works natively with Vercel AI SDK's `useChat` hook:

```typescript theme={null}
import { useChat } from '@ai-sdk/react';

function ChatComponent() {
  const { messages, input, handleSubmit, handleInputChange } = useChat({
    api: 'https://api.langdock.com/agent/v1/chat/completions',
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    },
    body: {
      agentId: 'agent_123'
    }
  });

  // The hook handles all message formatting automatically!
  return (
    <div>
      {messages.map(m => (
        <div key={m.id}>
          {m.role}: {m.content}
        </div>
      ))}
      <form onSubmit={handleSubmit}>
        <input value={input} onChange={handleInputChange} />
        <button type="submit">Send</button>
      </form>
    </div>
  );
}
```

### Step 4: Update Response Handling

```javascript theme={null}
// Before (Assistants API)
const response = await fetch(assistantUrl, options);
const data = await response.json();
const messages = data.result; // Array of messages

// After (Agents API)
const response = await fetch(agentUrl, options);
const data = await response.json();
const messages = data.messages; // Array of messages
const text = messages[0].content; // Plain string content
```

### Step 5: Update Streaming Code

#### Before (Custom SSE Parsing)

```javascript theme={null}
const response = await fetch(url, options);
const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const chunk = decoder.decode(value);
  const lines = chunk.split('\n');

  for (const line of lines) {
    if (line.startsWith('data: ')) {
      const data = JSON.parse(line.slice(6));
      if (data.type === 'message') {
        console.log(data.content);
      }
    }
  }
}
```

#### After (Vercel AI SDK)

```typescript theme={null}
import { streamText } from 'ai';

const result = await streamText({
  model: langdock({
    apiKey: process.env.LANGDOCK_API_KEY,
    agentId: 'agent_123'
  }),
  messages: conversationHistory
});

// Stream text chunks
for await (const chunk of result.textStream) {
  process.stdout.write(chunk);
}
```

## Code Examples

### Complete Migration Example

#### Before (Assistants API)

```javascript theme={null}
const axios = require("axios");

async function chatWithAssistant() {
  const response = await axios.post(
    "https://api.langdock.com/assistant/v1/chat/completions",
    {
      assistantId: "asst_123",
      messages: [
        {
          role: "user",
          content: "What's the weather today?",
          attachmentIds: []
        }
      ],
      stream: false
    },
    {
      headers: {
        Authorization: "Bearer YOUR_API_KEY"
      }
    }
  );

  // Response wrapped in result array
  const assistantMessage = response.data.result[0];
  console.log(assistantMessage.content[0].text);
}
```

#### After (Agents API)

```javascript theme={null}
const axios = require("axios");

async function chatWithAgent() {
  const response = await axios.post(
    "https://api.langdock.com/agent/v1/chat/completions",
    {
      agentId: "agent_123",  // Changed parameter name
      messages: [
        {
          id: "msg_1",  // Added message ID
          role: "user",
          parts: [  // Changed to parts array
            {
              type: "text",
              text: "What's the weather today?"
            }
          ]
        }
      ],
      stream: false
    },
    {
      headers: {
        Authorization: "Bearer YOUR_API_KEY"
      }
    }
  );

  // Response is messages array with content string
  const agentMessage = response.data.messages[0];
  console.log(agentMessage.content);
}
```

### Using with Next.js and Vercel AI SDK

```typescript theme={null}
// app/api/chat/route.ts
export async function POST(req: Request) {
  const { messages, agentId } = await req.json();

  const response = await fetch(
    'https://api.langdock.com/agent/v1/chat/completions',
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.LANGDOCK_API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        agentId,
        messages,
        stream: true
      })
    }
  );

  // Forward the streaming response
  return new Response(response.body, {
    headers: { 'Content-Type': 'text/event-stream' }
  });
}
```

## Testing Your Migration

### Checklist

* [ ] Update all endpoint URLs from `/assistant/v1/*` to `/agent/v1/*`
* [ ] Replace `assistantId` with `agentId` in all requests
* [ ] Convert message `content` strings to `parts` arrays (for chat completions)
* [ ] Add `id` field to all messages (for chat completions)
* [ ] Update attachment references to use `metadata.attachments` format
* [ ] Update response handling to work with new format
* [ ] Test streaming with new format (or use Vercel AI SDK)
* [ ] Update error handling for new response structure

### Gradual Migration Strategy

You can migrate endpoints gradually:

1. **Start with non-breaking endpoints**: Migrate create, get, update, models first (only parameter names change)
2. **Test thoroughly**: Ensure these work correctly
3. **Migrate chat completions last**: This requires the most code changes
4. **Use feature flags**: Toggle between old and new APIs during transition

## Common Migration Issues

### Issue 1: Missing Message IDs

**Problem**: Agents API requires message IDs

```javascript theme={null}
// Error: Missing id field
{
  role: "user",
  parts: [...]
}
```

**Solution**: Generate unique IDs for each message

```javascript theme={null}
import { nanoid } from 'nanoid';

{
  id: nanoid(),
  role: "user",
  parts: [...]
}
```

### Issue 2: Attachment Format

**Problem**: Old attachment format not recognized

```javascript theme={null}
// Wrong
{
  role: "user",
  attachmentIds: ["uuid-1234"],
  parts: [...]
}
```

**Solution**: Use `metadata.attachments`

```javascript theme={null}
// Correct
{
  id: "msg_1",
  role: "user",
  parts: [
    { type: "text", text: "..." }
  ],
  metadata: {
    attachments: ["uuid-1234"]
  }
}
```

### Issue 3: Response Parsing

**Problem**: Looking for `result` array

```javascript theme={null}
// Wrong - result doesn't exist in Agents API
const messages = response.data.result;
```

**Solution**: Use `messages` array with `content` string

```javascript theme={null}
// Correct
const messages = response.data.messages;
const text = messages[0].content;
```

## Support

If you encounter issues during migration:

1. Check the [Agents API documentation](/en/developer/agents-api/agent) for detailed examples
2. Review the [Vercel AI SDK documentation](https://sdk.vercel.ai/docs) for SDK-specific help
3. Contact support at [support@langdock.com](mailto:support@langdock.com)

## Timeline

* **Current**: Both APIs are available
* **Future**: Assistants API will be deprecated (date TBD)
* **Recommendation**: Migrate new projects to Agents API now

<Info>
  For questions or assistance with migration, contact our support team at [support@langdock.com](mailto:support@langdock.com).
</Info>