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
useChatfonksiyonuyla 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 API | Agents API | Breaking? |
|---|---|---|
/assistant/v1/chat/completions | /agent/v1/chat/completions | Evet - Biçim değişiklikleri |
/assistant/v1/create | /agent/v1/create | Hayır - Yalnızca parametre adları |
/assistant/v1/get | /agent/v1/get | Hayır - Yalnızca parametre adları |
/assistant/v1/update | /agent/v1/update | Hayır - Yalnızca parametre adları |
/assistant/v1/models | /agent/v1/models | Hayı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'tanagent'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)
{
assistantId: "asst_123",
messages: [
{
role: "user",
content: "Hello, how are you?", // Simple string content
attachmentIds: ["uuid-1234"]
}
],
stream: true
}Yeni biçim (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
}Temel request farkları
- Message Structure:
- Eski: dize olarak
content - Yeni: tipli nesnelerle dizi olarak
parts
- Eski: dize olarak
- Message ID:
- Eski: İsteğe bağlı veya otomatik üretilir
- Yeni: Her mesaj için zorunlu
idalanı
- Attachments:
- Eski: Mesaj düzeyinde
attachmentIdsdizisi - Yeni: Mesaj nesnesinde
metadata.attachmentsdizisi
- Eski: Mesaj düzeyinde
- Parameter Name:
- Eski:
assistantId - Yeni:
agentId
- Eski:
Response Format değişiklikleri
Eski biçim (Assistants API)
{
result: [
{
id: "msg_456",
role: "assistant",
content: [
{
type: "text",
text: "I'm doing well, thank you!"
}
]
}
]
}Yeni biçim (Agents API)
{
messages: [
{
id: "msg_456",
role: "assistant",
content: "I'm doing well, thank you!"
}
]
}Temel response farkları
- Top-level Structure:
- Eski:
resultdizisine sarılı - Yeni:
messagesdizisine sarılı
- Eski:
- Content Field:
- Eski:
contentdizisi - Yeni:
contentdizesi
- Eski:
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
// 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:
// Before
{ assistantId: "asst_123" }
// After
{ agentId: "agent_123" }Adım 3: Mesaj biçimini güncelleyin (Breaking - Chat Completions)
Mesajları dönüştürme
// 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:
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
// 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 contentAdım 5: Streaming kodunu güncelleyin
Önce (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);
}
}
}
}Sonra (Vercel AI SDK)
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)
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)
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
// 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'yiagentIdile değiştirin - Mesaj
contentdizelerinipartsdizilerine dönüştürün (chat completions için) - Tüm mesajlara
idalanı ekleyin (chat completions için) - Attachment referanslarını
metadata.attachmentsbiç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 endpointsişaretli API anahtarlarını kullanan sahipleri bilgilendirin veya sistemleri taşıyın
Kademeli geçiş stratejisi
Endpoint'leri kademeli olarak taşıyabilirsiniz:
- Non-breaking endpoint'lerle başlayın: Önce create, get, update, models'i taşıyın (yalnızca parametre adları değişir)
- Kapsamlı test edin: Bunların doğru çalıştığından emin olun
- Chat completions'ı en son taşıyın: En fazla kod değişikliği gerektirir
- 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
// Error: Missing id field
{
role: "user",
parts: [...]
}Solution: Her mesaj için benzersiz ID üretin
import { nanoid } from 'nanoid';
{
id: nanoid(),
role: "user",
parts: [...]
}Sorun 2: Attachment Format
Problem: Eski attachment biçimi tanınmıyor
// Wrong
{
role: "user",
attachmentIds: ["uuid-1234"],
parts: [...]
}Solution: metadata.attachments kullanın
// Correct
{
id: "msg_1",
role: "user",
parts: [
{ type: "text", text: "..." }
],
metadata: {
attachments: ["uuid-1234"]
}
}Sorun 3: Response Parsing
Problem: result dizisi aranıyor
// Wrong - result doesn't exist in Agents API
const messages = response.data.result;Solution: content dizesiyle messages dizisini kullanın
// Correct
const messages = response.data.messages;
const text = messages[0].content;Destek
Geçiş sırasında sorunlarla karşılaşırsanız:
- Ayrıntılı örnekler için Agents API documentation sayfasına bakın
- SDK'ya özel yardım için Vercel AI SDK documentation sayfasını inceleyin
- 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.