İçeriğe geç
ajan.io

Belgeler menüsü

Bu sayfada

Assistants API'den Agents API'ye geçiş

Eski Assistants API'den yeni Agents API'ye entegrasyon geçiş kılavuzu

Agents API, Vercel AI SDK gibi modern AI SDK'larıyla daha iyi uyumluluk için tasarlanmış yeni nesil API'mizdir.

Genel bakış

Agents API, Assistants API'ye göre önemli bir iyileştirmedir; ana hedef endüstri standardı AI SDK'larıyla yerel uyumluluk sağlamaktır. Temel fark, özel girdi/çıktı dönüşümlerinin kaldırılıp standart biçimlerin tercih edilmesidir.

Neden geçiş yapmalısınız?

  • Vercel AI SDK compatibility: AI SDK 5'in useChat fonksiyonuyla yerel çalışır
  • Standard formats: Özel dönüşümler yerine endüstri standardı mesaj biçimleri kullanır
  • Better streaming: AI SDK streaming kalıpları için yerel destek
  • Future-proof: Assistants API 16 Ağustos'ta kullanımdan kaldırılacak

Temel farklar

Endpoint değişiklikleri

Assistants APIAgents APIBreaking?
/assistant/v1/chat/completions/agent/v1/chat/completionsEvet - Biçim değişiklikleri
/assistant/v1/create/agent/v1/createHayır - Yalnızca parametre adları
/assistant/v1/get/agent/v1/getHayır - Yalnızca parametre adları
/assistant/v1/update/agent/v1/updateHayır - Yalnızca parametre adları
/assistant/v1/models/agent/v1/modelsHayır - Aynı

Parametre değişiklikleri (Non-Breaking)

Create, get ve update endpoint'leri için tek değişiklik parametre adlandırmasıdır:

  • assistantId → agentId
  • İstek alanları aynı kalır
  • Yanıt nesnesi assistant'tan agent'a değişir
  • Diğer tüm parametreler değişmez

/chat/completions içindeki Breaking Changes

Chat completions endpoint'i, Vercel AI SDK uyumluluğunu desteklemek için önemli biçim değişikliklerine sahiptir.

Request Format değişiklikleri

Eski biçim (Assistants API)

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

Yeni biçim (Agents API)

javascript
{
  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
}

Temel request farkları

  1. Message Structure:
    • Eski: dize olarak content
    • Yeni: tipli nesnelerle dizi olarak parts
  2. Message ID:
    • Eski: İsteğe bağlı veya otomatik üretilir
    • Yeni: Her mesaj için zorunlu id alanı
  3. Attachments:
    • Eski: Mesaj düzeyinde attachmentIds dizisi
    • Yeni: Mesaj nesnesinde metadata.attachments dizisi
  4. Parameter Name:
    • Eski: assistantId
    • Yeni: agentId

Response Format değişiklikleri

Eski biçim (Assistants API)

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

Yeni biçim (Agents API)

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

Temel response farkları

  1. Top-level Structure:
    • Eski: result dizisine sarılı
    • Yeni: messages dizisine sarılı
  2. Content Field:
    • Eski: content dizisi
    • Yeni: content dizesi

Streaming değişiklikleri

Eski biçim (Assistants API)

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

Yeni biçim (Agents API)

Vercel AI SDK streaming biçimini kullanır:

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

Agents API, useChat hook'uyla uyumlu Vercel AI SDK yerel biçiminde stream eder.

Geçiş adımları

Adım 1: Endpoint URL'lerini güncelleyin

javascript
// Before
const url = 'https://api.ajan.io/assistant/v1/chat/completions';

// After
const url = 'https://api.ajan.io/agent/v1/chat/completions';

Adım 2: Parametre adlarını güncelleyin (Non-Breaking Endpoint'ler)

Create, get, update endpoint'leri için:

javascript
// Before
{ assistantId: "asst_123" }

// After
{ agentId: "agent_123" }

Adım 3: Mesaj biçimini güncelleyin (Breaking - Chat Completions)

Mesajları dönüştürme

javascript
// 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"]
  }
};

Vercel AI SDK ile kullanım

Agents API, Vercel AI SDK'nın useChat hook'uyla yerel çalışır:

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

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

  // The hook handles all message formatting automatically!
  return (
    
      {messages.map(m => (
        
          {m.role}: {m.content}
        
      ))}
      
        
        Send
      
    
  );
}

Adım 4: Response işlemeyi güncelleyin

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

Adım 5: Streaming kodunu güncelleyin

Önce (Custom SSE Parsing)

javascript
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);
      }
    }
  }
}

Sonra (Vercel AI SDK)

typescript
import { streamText } from 'ai';

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

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

Kod örnekleri

Tam geçiş örneği

Önce (Assistants API)

javascript
const axios = require("axios");

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

Sonra (Agents API)

javascript
const axios = require("axios");

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

Next.js ve Vercel AI SDK ile kullanım

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

  const response = await fetch(
    'https://api.ajan.io/agent/v1/chat/completions',
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.AJAN_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' }
  });
}

Geçişinizi test etme

Checklist

  • Tüm endpoint URL'lerini /assistant/v1/*'den /agent/v1/*'e güncelleyin
  • Tüm isteklerde assistantId'yi agentId ile değiştirin
  • Mesaj content dizelerini parts dizilerine dönüştürün (chat completions için)
  • Tüm mesajlara id alanı ekleyin (chat completions için)
  • Attachment referanslarını metadata.attachments biçimine güncelleyin
  • Response işlemeyi yeni biçimle çalışacak şekilde güncelleyin
  • Yeni biçimle streaming'i test edin (veya Vercel AI SDK kullanın)
  • Yeni yanıt yapısı için hata işlemeyi güncelleyin
  • Workspace API ayarlarında Using deprecated endpoints işaretli API anahtarlarını kullanan sahipleri bilgilendirin veya sistemleri taşıyın

Kademeli geçiş stratejisi

Endpoint'leri kademeli olarak taşıyabilirsiniz:

  1. Non-breaking endpoint'lerle başlayın: Önce create, get, update, models'i taşıyın (yalnızca parametre adları değişir)
  2. Kapsamlı test edin: Bunların doğru çalıştığından emin olun
  3. Chat completions'ı en son taşıyın: En fazla kod değişikliği gerektirir
  4. Feature flag kullanın: Geçiş sırasında eski ve yeni API arasında geçiş yapın

Yaygın geçiş sorunları

Sorun 1: Eksik Message ID'ler

Problem: Agents API mesaj ID'leri gerektirir

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

Solution: Her mesaj için benzersiz ID üretin

javascript
import { nanoid } from 'nanoid';

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

Sorun 2: Attachment Format

Problem: Eski attachment biçimi tanınmıyor

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

Solution: metadata.attachments kullanın

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

Sorun 3: Response Parsing

Problem: result dizisi aranıyor

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

Solution: content dizesiyle messages dizisini kullanın

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

Destek

Geçiş sırasında sorunlarla karşılaşırsanız:

  1. Ayrıntılı örnekler için Agents API documentation sayfasına bakın
  2. SDK'ya özel yardım için Vercel AI SDK documentation sayfasını inceleyin
  3. support@ajan.com adresinden destekle iletişime geçin

Zaman çizelgesi

  • Current: Her iki API de kullanılabilir
  • Future: Assistants API 16 Ağustos'ta kullanımdan kaldırılacak
  • Recommendation: Yeni sistemleri şimdi Agents API'ye taşıyın

Geçişle ilgili sorular veya yardım için destek ekibimizle support@ajan.com adresinden iletişime geçin.