Agent Migration Guide

Bu kılavuz, Agents API ile agent'ları bir ajan workspace'inden diğerine nasıl taşıyacağınızı açıklar. Agent yapılandırmalarını farklı workspace'lerde çoğaltmak, organizasyonel yeniden yapılanmada agent'ları taşımak veya agent'larınızın yedek kopyalarını oluşturmak için faydalıdır.

Başlamadan önce

• Agents API: Bu, yerel Vercel AI SDK uyumluluğuna sahip Agents API'dir.

Overview

Taşıma süreci iki ana adımdan oluşur:

1. Export: Kaynak workspace'ten agent yapılandırmasını Agent Get API ile alın
2. Import: Hedef workspace'te Agent Create API ile yeni bir agent oluşturun

Prerequisites

Başlamadan önce şunlara sahip olduğunuzdan emin olun:

1. Agent API kapsamına sahip iki API anahtarı:
   • Kaynak workspace için bir API anahtarı (agent'ın şu anda bulunduğu)
   • Hedef workspace için bir API anahtarı (agent'ı taşımak istediğiniz yer)
2. Agent'a erişim: Kaynak workspace API anahtarınızın taşımak istediğiniz agent'a erişimi olmalıdır
3. Hedef workspace'te eşleşen kaynaklar (varsa):
   • Hedef workspace aynı modele erişemiyorsa, taşımadan önce script'te model'i kullanılabilir bir deployment adına ayarlayın
   • Agent özel action'lar kullanıyorsa bu entegrasyonlar hedef workspace'te etkin olmalıdır
   • Attachment'ların ayrı ayrı yeniden yüklenmesi gerekir (otomatik aktarılmaz)

Step 1: Export the Agent from Source Workspace

Agent ayarlarını almak için Agent Get API kullanın:

const axios = require("axios");

async function getAgentFromSource(agentId, sourceApiKey) {
  const response = await axios.get(
    "https://api.ajan.io/agent/v1/get",
    {
      params: {
        agentId: agentId
      },
      headers: {
        Authorization: `Bearer ${sourceApiKey}`
      }
    }
  );

  return response.data.agent;
}

Understanding the Response

Get API şu agent ayarlarını döndürür:

• name, description, instruction — Agent'ın kimliği ve system prompt'u
• emojiIcon — Agent için görüntülenen emoji ikonu
• model — Kullanılan modelin tanımlayıcısı (ör. gpt-5-mini-eu)
• temperature — Yaratıcılık ayarı (0-1)
• conversationStarters — Kullanıcılar için önerilen prompt'lar
• inputType — Yapılandırılmış giriş türü
• inputFields — Form alanları için görüntüleme özellikleri. Yanıt, bunları yeniden oluşturmak için gereken slug, options, fileTypes veya emailDomain değerlerini içermez
• webSearchEnabled, imageGenerationEnabled, canvasEnabled — Yetenek bayrakları
• extendedThinking — Extended thinking'in etkin olup olmadığı
• actions — Özel entegrasyon action'ları
• attachments — Ekli dosyaların UUID'leri
• knowledgeFolderIds — Bağlı Folder UUID'leri
• owner — mevcut sahip ({ id, name, email }), atanmamışsa null

canvasEnabled bu endpoint'lerde salt okunurdur ve bu taşıma ile aktarılmaz. owner da aktarılmaz. Hedef workspace'te API anahtarı oluşturan kişi sahip olur.

Step 2: Transform the Configuration

Get API yanıtı, Create API'nin beklediğinden biraz farklı alan adları kullanır. Alanları eşlemeniz gerekir:

function transformForCreate(sourceAgent) {
  return {
    // Basic information
    name: sourceAgent.name,
    description: sourceAgent.description || undefined,
    emoji: sourceAgent.emojiIcon || undefined,
    instruction: sourceAgent.instruction || undefined,

    // Settings
    model: sourceAgent.model,
    creativity: sourceAgent.temperature,
    inputType: sourceAgent.inputType,
    conversationStarters: sourceAgent.conversationStarters || [],

    // Capabilities
    webSearch: sourceAgent.webSearchEnabled,
    imageGeneration: sourceAgent.imageGenerationEnabled,
    extendedThinking: sourceAgent.extendedThinking,
    knowledgeFolderIds: sourceAgent.knowledgeFolderIds || [],

    // Note: input fields, actions, and attachments require special handling (see below)
  };
}

Field Mapping Reference

Step 3: Create the Agent in Target Workspace

Hedef workspace'te agent oluşturmak için Agent Create API kullanın:

async function createAgentInTarget(agentConfig, targetApiKey) {
  const response = await axios.post(
    "https://api.ajan.io/agent/v1/create",
    agentConfig,
    {
      headers: {
        Authorization: `Bearer ${targetApiKey}`,
        "Content-Type": "application/json"
      }
    }
  );

  return response.data.agent;
}

Complete Migration Script

Tüm adımları birleştiren tam bir script:

const axios = require("axios");

// Configuration
const SOURCE_API_KEY = "your-source-workspace-api-key";
const TARGET_API_KEY = "your-target-workspace-api-key";
const AGENT_ID_TO_MIGRATE = "550e8400-e29b-41d4-a716-446655440000";

async function migrateAgent() {
  try {
    // Step 1: Get agent from source workspace
    console.log("Fetching agent from source workspace...");
    const getResponse = await axios.get(
      "https://api.ajan.io/agent/v1/get",
      {
        params: { agentId: AGENT_ID_TO_MIGRATE },
        headers: { Authorization: `Bearer ${SOURCE_API_KEY}` }
      }
    );
    
    const sourceAgent = getResponse.data.agent;
    console.log(`Found agent: "${sourceAgent.name}"`);

    // Step 2: Transform configuration for Create API
    const createConfig = {
      name: sourceAgent.name,
      description: sourceAgent.description || undefined,
      emoji: sourceAgent.emojiIcon || undefined,
      instruction: sourceAgent.instruction || undefined,
      model: sourceAgent.model,
      creativity: sourceAgent.temperature,
      inputType: sourceAgent.inputType,
      conversationStarters: sourceAgent.conversationStarters || [],
      webSearch: sourceAgent.webSearchEnabled,
      imageGeneration: sourceAgent.imageGenerationEnabled,
      extendedThinking: sourceAgent.extendedThinking,
      knowledgeFolderIds: sourceAgent.knowledgeFolderIds || [],
      // Note: input fields, actions, and attachments excluded - see "Handling Special Cases"
    };

    // Remove undefined values
    Object.keys(createConfig).forEach(key => {
      if (createConfig[key] === undefined) {
        delete createConfig[key];
      }
    });

    // Step 3: Create agent in target workspace
    console.log("Creating agent in target workspace...");
    const createResponse = await axios.post(
      "https://api.ajan.io/agent/v1/create",
      createConfig,
      {
        headers: {
          Authorization: `Bearer ${TARGET_API_KEY}`,
          "Content-Type": "application/json"
        }
      }
    );

    const newAgent = createResponse.data.agent;
    console.log(`Migration successful!`);
    console.log(`New agent ID: ${newAgent.id}`);
    console.log(`Agent name: ${newAgent.name}`);
    
    return newAgent;

  } catch (error) {
    if (error.response) {
      console.error(`Error ${error.response.status}: ${JSON.stringify(error.response.data)}`);
    } else {
      console.error("Error:", error.message);
    }
    throw error;
  }
}

migrateAgent();

Handling Special Cases

Form Fields

Get API yanıtı, Create API'nin gerektirdiği slug, options, fileTypes veya emailDomain değerlerini içermez. Form alanlarını hedef workspace'te elle yeniden oluşturun.

Actions (Custom Integrations)

Action'lar, hedef workspace'te etkinleştirilmiş olması gereken entegrasyonlara referans verir. Action UUID'leri her workspace'in entegrasyon kurulumuna özgüdür.

Action'ları ilk taşımadan hariç tutun ve agent oluşturulduktan sonra hedef workspace'te elle yapılandırın.

Attachments

Attachment UUID'leri kaynak workspace'te saklanan dosyalara referans verir. Bu dosyalar otomatik aktarılmaz.

Attachment'ları taşımak için:

1. Dosyaları kaynak workspace'ten indirin
2. Upload Attachment API ile hedef workspace'e yeniden yükleyin
3. Agent'ı yeni attachment UUID'leriyle güncelleyin

OAuth Connections

Önceden seçilmiş OAuth bağlantıları API üzerinden desteklenmez. Kullanıcılar taşımadan sonra ajan UI üzerinden OAuth bağlantılarını yapılandırmalıdır.

Migrating Multiple Agents

Birden fazla agent taşımak için agent ID listesi üzerinde döngü kurun:

const AGENT_IDS = [
  "agent-uuid-1",
  "agent-uuid-2",
  "agent-uuid-3"
];

async function migrateMultipleAgents() {
  const results = [];
  
  for (const agentId of AGENT_IDS) {
    try {
      console.log(`\nMigrating agent: ${agentId}`);
      const newAgent = await migrateAgent(agentId);
      results.push({ 
        sourceId: agentId, 
        targetId: newAgent.id, 
        status: "success" 
      });
    } catch (error) {
      results.push({ 
        sourceId: agentId, 
        status: "failed", 
        error: error.message 
      });
    }
  }
  
  console.log("\n=== Migration Summary ===");
  console.table(results);
}

Post-Migration Checklist

Bir agent taşıdıktan sonra hedef workspace'te şunları doğrulayın:

• Agent, doğru ad ve emoji ile Agents listesinde görünüyor
• Açıklama ve talimatlar doğru aktarılmış
• Model hedef workspace'te kullanılabilir
• Conversation starter'lar mevcut
• Yetenekler (web search, image generation vb.) doğru etkin
• Giriş alanları doğru yapılandırılmış (STRUCTURED input type için)
• Gerekli OAuth bağlantılarını UI üzerinden elle yapılandırın
• Gerekli dosyaları yeniden yükleyip ekleyin
• Gerekirse özel action/entegrasyonları yapılandırın
• Agent'a bir mesaj göndererek test edin

Limitations

Taşımanızı planlarken şu sınırlamaları aklınızda bulundurun:

1. Attachment'lar aktarılmaz — Dosyalar hedef workspace'e yeniden yüklenmelidir
2. Action'lar yeniden yapılandırma gerektirebilir — Entegrasyon action UUID'leri workspace'e özgüdür
3. OAuth bağlantıları elle kurulum gerektirir — API üzerinden yapılandırılamaz
4. Model erişimi eşleşmelidir — Create API, hedef workspace'te olmayan bir modeli reddeder. Taşımadan önce kullanılabilir bir deployment adı ayarlayın
5. Konuşma geçmişi taşınmaz — Yalnızca agent yapılandırması aktarılır

ajan, API anahtarınızı korumak ve uygulamalarınızın güvenliğini sağlamak için tarayıcı kaynaklı istekleri bilinçli olarak engeller. Daha fazla bilgi için API Key Best Practices kılavuzuna bakın.