İçeriğe geç
ajan.io

Belgeler menüsü

Bu sayfada

Action oluştur

Agent'ların yürütebileceği bir action'ı entegrasyona ekleyin

Bir entegrasyon için yeni bir action oluşturur. Action'lar, agent'ların yürütebileceği yeteneklerdir; örneğin mesaj gönderme, veri getirme veya harici sistemlerde kayıt oluşturma.

Base URL

https://api.ajan.io/integrations/v1/{integrationId}/actions/create

Dedicated deployments Tüm isteklerde api.ajan.com'u /api/public ile değiştirin.

Required Scopes

Bu endpoint INTEGRATION_API kapsamı gerektirir.

Parameters

Path Parameters

ParameterTypeRequiredDescription
integrationIdstringYesEntegrasyonun UUID'si

Request Body

ParameterTypeRequiredDescription
namestringYesAction adı (maks. 100 karakter)
descriptionstringNoAction açıklaması (maks. 1.000 karakter)
codestringNoÇalıştırılacak JavaScript kodu (maks. 150.000 karakter)
inputFieldsarrayNoAction için giriş alanları
requiresConfirmationbooleanNoÇalıştırmadan önce kullanıcı onayı gerekip gerekmediği (varsayılan: true)

Input Field Schema

Her giriş alanının şu özellikleri vardır:

PropertyTypeRequiredDescription
labelstringYesAlan etiketi (maks. 100 karakter)
typestringNoAlan türü (varsayılan: "TEXT")
descriptionstringNoAlan açıklaması (maks. 500 karakter)
placeholderstringNoPlaceholder metni (maks. 200 karakter)
requiredbooleanNoAlanın zorunlu olup olmadığı (varsayılan: false)
optionsarrayNoSELECT türü alanlar için seçenekler
allowMultiSelectbooleanNoSELECT alanlarında çoklu seçime izin ver
contextActionIdstringNoDinamik seçenekler için kullanılacak action UUID'si
jsonSchemastringNoBeklenen değeri tanımlayan JSON Schema (stringified JSON). Genellikle agent'ların üretmesi gereken şekli kısıtlamak için OBJECT alanlarıyla kullanılır.

Field Types

TypeDescription
TEXTTek satırlı metin girişi
MULTI_LINE_TEXTÇok satırlı metin girişi
NUMBERSayısal giriş
BOOLEANTrue/false anahtarı
SELECTAçılır liste seçimi
PASSWORDParola girişi (maskeli)
VECTORVektör girişi
OBJECTNesne girişi
FILEDosya girişi
IDTanımlayıcı girişi

Example

javascript
const axios = require("axios");

async function createAction(integrationId) {
  const response = await axios.post(
    `https://api.ajan.io/integrations/v1/${integrationId}/actions/create`,
    {
      name: "Get User Data",
      description: "Retrieves user information from the internal API by user ID",
      code: `
        const response = await ld.request({
          method: "GET",
          url: "https://api.example.com/users/" + data.input.userId,
          headers: {
            Authorization: "Bearer " + data.auth.apiToken
          }
        });

        if (response.status < 200 || response.status >= 300) {
          throw new Error("User not found");
        }

        return response.json;
      `,
      inputFields: [
        {
          label: "User ID",
          type: "TEXT",
          description: "The unique identifier of the user",
          placeholder: "e.g., user_123",
          required: true
        },
        {
          label: "Include Details",
          type: "BOOLEAN",
          description: "Include extended user details",
          required: false
        },
        {
          label: "Filters",
          type: "OBJECT",
          description: "Structured filters applied to the user lookup",
          required: false,
          jsonSchema: JSON.stringify({
            type: "object",
            properties: {
              status: { type: "string", enum: ["active", "inactive"] },
              limit: { type: "integer", minimum: 1, maximum: 100 }
            },
            required: ["status"]
          })
        }
      ]
    },
    {
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
      }
    }
  );

  console.log("Created action:", response.data.action);
}

createAction("550e8400-e29b-41d4-a716-446655440000");

Response Format

Success Response (201 Created)

typescript
{
  action: {
    id: string;           // UUID of the created action
    name: string;         // Action name
    slug: string;         // URL-friendly identifier (auto-generated)
    description: string;  // Action description
    code: string | null;  // JavaScript code
    order: number;        // Display order
    requiresConfirmation: boolean; // Whether the action requires user confirmation before running
    inputFields: Array<{
      slug: string;       // Field identifier
      label: string;      // Display label
      type: string;       // Field type
      description: string;
      placeholder: string | null;
      required: boolean;
      order: number;
      options: Array<{label: string, value: string}> | null;
      allowMultiSelect: boolean | null;
      contextActionId: string | null;
      jsonSchema: string | null;
    }>;
  };
}

Error Handling

Status CodeDescription
400Geçersiz istek gövdesi veya geçersiz entegrasyon ID
401Geçersiz veya eksik API anahtarı
403Bu entegrasyona erişim yok
404Entegrasyon bulunamadı
409Bu ada sahip bir action entegrasyonda zaten var
429Rate limit aşıldı
500İç sunucu hatası

Code Execution Environment

Action kodu, şunlara erişimi olan sandboxed JavaScript ortamında çalışır:

  • data.input — Giriş alanlarının değerlerini içeren nesne
  • data.auth — Entegrasyon için yapılandırılmış bağlantı kimlik bilgilerini içeren nesne
  • ld.request — Harici API'lere HTTP istekleri
  • ld.log — Çalıştırma logları
  • Standart JavaScript built-in'leri

Action kodu hataları zarifçe işlemelidir. Yakalanmayan hatalar action'ın başarısız olmasına ve agent'a bir hata mesajı dönmesine yol açar.

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.