Migrating from Assistants API to Agents API

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

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

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)

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

New Format (Agents API)

{
  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)

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

New Format (Agents API)

{
  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

// Before
const url = 'https://api.odeus.ai/assistant/v1/chat/completions';

// After
const url = 'https://api.odeus.ai/agent/v1/chat/completions';

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

For create, get, update endpoints:

// Before
{ assistantId: "asst_123" }

// After
{ agentId: "agent_123" }

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

Converting Messages

// 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:

import { useChat } from '@ai-sdk/react';

function ChatComponent() {
  const { messages, input, handleSubmit, handleInputChange } = useChat({
    api: 'https://api.odeus.ai/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 => (
        &lt;div key={m.id}&gt;
          {m.role}: {m.content}
        </div>
      ))}
      &lt;form onSubmit={handleSubmit}&gt;
        &lt;input value={input} onChange={handleInputChange} /&gt;
        &lt;button type="submit"&gt;Send&lt;/button&gt;
      &lt;/form&gt;
    </div>
  );
}

Step 4: Update Response Handling

// 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)

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)

import { streamText } from 'ai';

const result = await streamText({
  model: odeus({
    apiKey: process.env.ODEUS_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)

const axios = require("axios");

async function chatWithAssistant() {
  const response = await axios.post(
    "https://api.odeus.ai/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)

const axios = require("axios");

async function chatWithAgent() {
  const response = await axios.post(
    "https://api.odeus.ai/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

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

  const response = await fetch(
    'https://api.odeus.ai/agent/v1/chat/completions',
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.ODEUS_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

// Error: Missing id field
{
  role: "user",
  parts: [...]
}

Solution: Generate unique IDs for each message

import { nanoid } from 'nanoid';

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

Issue 2: Attachment Format

Problem: Old attachment format not recognized

// Wrong
{
  role: "user",
  attachmentIds: ["uuid-1234"],
  parts: [...]
}

Solution: Use metadata.attachments

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

Issue 3: Response Parsing

Problem: Looking for result array

// Wrong - result doesn't exist in Agents API
const messages = response.data.result;

Solution: Use messages array with content string

// Correct
const messages = response.data.messages;
const text = messages[0].content;

Support

If you encounter issues during migration:

1. Check the Agents API documentation for detailed examples
2. Review the Vercel AI SDK documentation for SDK-specific help
3. Contact support at [email protected]

Timeline

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

For questions or assistance with migration, contact our support team at [email protected].