Agent Create API

Yeni bir agent'ı programatik olarak oluşturun

Workspace'inizde programatik olarak yeni bir agent oluşturur. Oluşturulan agent, chat completions endpoint'i üzerinden kullanılabilir veya ajan UI'dan erişilebilir.

Başlamadan önce

API key scope: Agent API kapsamına sahip bir API anahtarı gerekir. Oluşturulan agent'lar, chat completions'ta kullanılmak üzere API anahtarıyla otomatik paylaşılır.
Legacy Assistants API: Bu, yerel Vercel AI SDK uyumluluğuna sahip yeni Agents API'dir. Eski Assistants API kullanıyorsanız migration guide sayfasına bakın.

Base URL

https://api.ajan.io/agent/v1/create

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

Parameters

Parameter	Type	Required	Description
`name`	string	Yes	Agent adı (1-80 karakter)
`description`	string	No	Agent'ın ne yaptığına dair açıklama (maks. 800 karakter)
`emoji`	string	No	Agent için emoji ikonu (maks. 16 karakter, ör. "🤖")
`instruction`	string	No	Agent için system prompt/talimatlar (maks. 50000 karakter)
`inputType`	string	No	Giriş türü: "PROMPT", "STRUCTURED", "INTEGRATION", "SCHEDULED" veya "WEBHOOK" (varsayılan: "PROMPT")
`model`	string	No	Kullanılacak model tanımlayıcısı (Models API deployment adı). Sağlanmazsa workspace varsayılanı kullanılır
`creativity`	number	No	0-1 arası temperature (varsayılan: 0.3)
`conversationStarters`	string\[]	No	Kullanıcıların başlamasına yardımcı önerilen prompt dizisi (maks. 20, her biri 1-255 karakter)
`actions`	array	No	Özel entegrasyonlar için action nesneleri dizisi
`inputFields`	array	No	Form alanı tanımları dizisi (STRUCTURED input type için)
`attachments`	string\[]	No	Agent ile dahil edilecek en fazla 50 attachment UUID dizisi
`knowledgeFolderIds`	string\[]	No	Agent ile dahil edilecek Folder UUID dizisi
`webSearch`	boolean	No	Web arama yeteneğini etkinleştir (varsayılan: false)
`imageGeneration`	boolean	No	Görüntü üretme yeteneğini etkinleştir (varsayılan: false)
`dataAnalyst`	boolean	No	Uyumluluk için kabul edilir. Aşağıdaki uyarıya bakın
`extendedThinking`	boolean	No	Extended thinking modunu etkinleştir (varsayılan: false)

dataAnalyst parametresi kullanımdan kaldırılmıştır ve etkisi yoktur. İçeren istekler geriye dönük uyumluluk için yine başarılı olur; ancak ajan değeri yok sayar ve dosya veya kod yürütmeyi etkinleştirmez. Yeni entegrasyonlarda bu parametreyi atlayın.

Actions Configuration

actions dizisindeki her action şunları içermelidir:

actionId (required) — Etkin bir entegrasyondan action UUID'si
requiresConfirmation (optional) — Çalıştırmadan önce kullanıcı onayı gerekip gerekmediği (varsayılan: true)

Yalnızca workspace'inizde etkinleştirilmiş entegrasyonlardaki action'lar kullanılabilir.

Input Fields Configuration

inputType: "STRUCTURED" kullanırken inputFields dizisinde form alanları tanımlayabilirsiniz:

Field	Type	Required	Description
`slug`	string	Yes	Alan için benzersiz tanımlayıcı
`type`	string	Yes	Alan türü (aşağıdaki desteklenen türler)
`label`	string	Yes	Alan için görünen etiket
`description`	string	No	Alan için yardım metni
`required`	boolean	No	Alanın zorunlu olup olmadığı (varsayılan: false)
`order`	number	Yes	Görüntüleme sırası (0-indexed)
`options`	string\[]	No	SELECT ve MULTI_SELECT türü alanlar için seçenekler
`fileTypes`	string	No	FILE türü alanlar için izin verilen dosya türleri (nullable)
`emailDomain`	string	No	EMAIL türü alanlar için izin verilen e-posta alanı

Supported Field Types:

TEXT — Tek satırlı metin girişi
MULTI_LINE_TEXT — Çok satırlı metin alanı
NUMBER — Sayısal giriş
CHECKBOX — Boolean onay kutusu
FILE — Dosya yükleme
SELECT — Açılır liste seçimi
MULTI_SELECT — Çoklu seçim
DATE — Tarih seçici
EMAIL — E-posta adresi

Obtaining Attachment IDs

Agent'ınıza attachment eklemek için önce Upload Attachment API ile dosya yükleyin. Bu, attachments dizisine ekleyebileceğiniz attachment UUID'lerini döndürür.

Examples

Creating a Basic Agent

javascript

const axios = require("axios");

async function createBasicAgent() {
  const response = await axios.post(
    "https://api.ajan.io/agent/v1/create",
    {
      name: "Document Analyzer",
      description: "Analyzes and summarizes documents",
      emoji: "📄",
      instruction: "You are a helpful agent that analyzes documents and provides clear summaries of key information.",
      creativity: 0.5,
      conversationStarters: [
        "Summarize this document",
        "What are the key points?",
        "Extract action items"
      ],
      webSearch: false
    },
    {
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
      }
    }
  );

  console.log("Agent created:", response.data.agent.id);
}

Validation Rules

API birkaç doğrulama kuralı uygular:

Model — Workspace'inizin aktif modeller listesinde olmalıdır
Actions — Workspace'inizde etkin entegrasyonlara ait olmalıdır
Attachments — Workspace'inizde var olmalı ve silinmiş olmamalıdır
Folders — Workspace'inizde var olmalı ve silinmiş olmamalıdır
Permissions — API anahtarınızın createAgents izni olmalıdır
Name — 1-80 karakter arasında olmalıdır
Description — Maksimum 800 karakter
Instruction — Maksimum 50000 karakter
Creativity — 0 ile 1 arasında olmalıdır

Important Notes

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

Oluşturulan agent'lar chat completions'ta kullanılmak üzere API anahtarınızla otomatik paylaşılır
API anahtarı oluşturan kişi sahip olur ve agent'ı UI'da yönetebilir
Attachment'lar agent ile çift yönlü bağlanır
createdBy ve workspaceId API anahtarınızdan otomatik ayarlanır

Response Format

Success Response (201 Created)

typescript

{
  status: "success";
  message: "Agent created successfully";
  agent: {
    id: string;
    name: string;
    description: string | null;
    instruction: string | null;
    emojiIcon: string | null;
    model: string | null;
    temperature: number;
    conversationStarters: string[];
    inputType: "PROMPT" | "STRUCTURED" | "INTEGRATION" | "SCHEDULED" | "WEBHOOK";
    webSearchEnabled: boolean;
    imageGenerationEnabled: boolean;
    canvasEnabled: boolean;
    extendedThinking: boolean;
    actions: Array<{
      actionId: string;
      requiresConfirmation: boolean;
    }>;
    inputFields: Array<{
      type: "TEXT" | "MULTI_LINE_TEXT" | "NUMBER" | "CHECKBOX" | "FILE" | "SELECT" | "MULTI_SELECT" | "DATE" | "EMAIL";
      label: string;
      description: string | null;
      required: boolean;
      order: number;
    }>;
    attachments: string[];
    knowledgeFolderIds: string[];
    owner: {
      id: string;
      name: string | null;
      email: string;
    } | null;
    createdAt: string;
    updatedAt: string;
  };
}

Error Handling

typescript

try {
  const response = await axios.post('https://api.ajan.io/agent/v1/create', ...);
} catch (error) {
  if (error.response) {
    switch (error.response.status) {
      case 400:
        console.error('Invalid parameters or resource not found:', error.response.data.message);
        break;
      case 401:
        console.error('Invalid or missing API key');
        break;
      case 403:
        console.error('Insufficient permissions - requires Agent API scope');
        break;
      case 429:
        console.error('Rate limit exceeded');
        break;
      case 500:
        console.error('Server error');
        break;
    }
  }
}

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.

OpenAPI

openapi: 3.0.0
info:
  title: ajan API
  version: 3.0.0
servers:
  - url: https://api.ajan.io
    description: Production
security:
  - bearerAuth: []
paths:
  /agent/v1/create:
    post:
      tags:
        - Agent Build
      summary: Creates a new agent
      description: Creates a new agent in your workspace programmatically.
      operationId: createAgentV2
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssistantCreateRequest'
      responses:
        '201':
          description: Agent created successfully
          content:
            application/json:
              schema:
                type: object
                required:
                  - status
                  - message
                  - agent
                properties:
                  status:
                    type: string
                    enum:
                      - success
                  message:
                    type: string
                  agent:
                    $ref: '#/components/schemas/AssistantDetails'
components:
  schemas:
    AssistantCreateRequest:
      allOf:
        - $ref: '#/components/schemas/AssistantWriteRequest'
        - type: object
          required:
            - name
          properties:
            inputType:
              default: PROMPT
            creativity:
              default: 0.3
            conversationStarters:
              default: []
            actions:
              default: []
            inputFields:
              default: []
            webSearch:
              default: false
            imageGeneration:
              default: false
            dataAnalyst:
              default: false
            extendedThinking:
              default: false
            attachments:
              default: []
            knowledgeFolderIds:
              default: []
    AssistantDetails:
      type: object
      required:
        - id
        - name
        - description
        - instruction
        - emojiIcon
        - model
        - temperature
        - conversationStarters
        - inputType
        - webSearchEnabled
        - imageGenerationEnabled
        - canvasEnabled
        - extendedThinking
        - actions
        - inputFields
        - attachments
        - knowledgeFolderIds
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the agent
        name:
          type: string
          description: Name of the agent
        description:
          type: string
          nullable: true
          description: Description of what the agent does
        instruction:
          type: string
          nullable: true
          description: System prompt/instructions for the agent
        emojiIcon:
          type: string
          nullable: true
          description: Emoji icon for the agent
        model:
          type: string
          nullable: true
          description: Model ID to use (see Models for Agent API)
        temperature:
          type: number
          minimum: 0
          maximum: 1
          description: Temperature/creativity setting for response generation
        conversationStarters:
          type: array
          items:
            type: string
          description: Array of suggested prompts to help users get started
        inputType:
          type: string
          enum:
            - PROMPT
            - STRUCTURED
            - INTEGRATION
            - SCHEDULED
            - WEBHOOK
          description: Input type for the agent
        webSearchEnabled:
          type: boolean
          description: Whether web search capability is enabled
        imageGenerationEnabled:
          type: boolean
          description: Whether image generation capability is enabled
        canvasEnabled:
          type: boolean
          description: Whether canvas capability is enabled
        extendedThinking:
          type: boolean
          description: >-
            Whether extended thinking is enabled. Only supported on models that
            expose this capability; enabling it on an unsupported model returns
            a 400 error.
        actions:
          type: array
          items:
            type: object
            required:
              - actionId
              - requiresConfirmation
            properties:
              actionId:
                type: string
                format: uuid
                description: UUID of the action from an enabled integration
              requiresConfirmation:
                type: boolean
                description: Whether user confirmation is required before executing
          description: Array of action objects for custom integrations
        inputFields:
          type: array
          items:
            type: object
            required:
              - type
              - label
              - description
              - required
              - order
            properties:
              type:
                type: string
                enum:
                  - TEXT
                  - MULTI_LINE_TEXT
                  - NUMBER
                  - CHECKBOX
                  - FILE
                  - SELECT
                  - MULTI_SELECT
                  - DATE
                  - EMAIL
                description: Field type
              label:
                type: string
                description: Display label for the field
              description:
                type: string
                nullable: true
                description: Help text for the field
              required:
                type: boolean
                description: Whether the field is required
              order:
                type: integer
                minimum: 0
                description: Display order (0-indexed)
          description: Array of form field definitions (for STRUCTURED input type)
        attachments:
          type: array
          items:
            type: string
            format: uuid
          description: Array of attachment UUIDs associated with the agent
        knowledgeFolderIds:
          type: array
          items:
            type: string
            format: uuid
          description: Array of Folder UUIDs associated with the agent
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the agent was created
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when the agent was last updated
    AssistantWriteRequest:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 80
          description: Name of the agent or assistant
        description:
          type: string
          maxLength: 800
          description: >-
            Description of what the agent or assistant does. Send an empty
            string to clear it during an update.
        instruction:
          type: string
          maxLength: 50000
          description: >-
            System prompt or instructions. Send an empty string to clear it
            during an update.
        inputType:
          type: string
          enum:
            - PROMPT
            - STRUCTURED
            - INTEGRATION
            - SCHEDULED
            - WEBHOOK
          description: Input type
        emoji:
          type: string
          nullable: true
          maxLength: 16
          description: Emoji icon
        model:
          type: string
          description: Model deployment name
        creativity:
          type: number
          minimum: 0
          maximum: 1
          description: Temperature for response generation
        conversationStarters:
          type: array
          maxItems: 20
          items:
            type: string
            minLength: 1
            maxLength: 255
          description: Suggested prompts
        actions:
          type: array
          items:
            $ref: '#/components/schemas/AssistantActionRequest'
          description: Actions that the agent or assistant can use
        inputFields:
          type: array
          items:
            $ref: '#/components/schemas/AssistantInputFieldRequest'
          description: Form fields for STRUCTURED input
        webSearch:
          type: boolean
          description: Enable web search
        imageGeneration:
          type: boolean
          description: Enable image generation
        dataAnalyst:
          type: boolean
          deprecated: true
          description: Deprecated. Accepted for compatibility and ignored.
        extendedThinking:
          type: boolean
          description: Enable extended thinking
        attachments:
          type: array
          maxItems: 50
          items:
            type: string
            format: uuid
          description: Attachment UUIDs
        knowledgeFolderIds:
          type: array
          items:
            type: string
            format: uuid
          description: Folder UUIDs
    AssistantActionRequest:
      type: object
      required:
        - actionId
      properties:
        actionId:
          type: string
          format: uuid
          description: UUID of the action from an enabled integration
        requiresConfirmation:
          type: boolean
          default: true
          description: Whether to require user confirmation before executing
    AssistantInputFieldRequest:
      type: object
      required:
        - slug
        - type
        - label
        - order
      properties:
        slug:
          type: string
          minLength: 1
          maxLength: 64
          description: Unique identifier for the field
        type:
          type: string
          enum:
            - TEXT
            - MULTI_LINE_TEXT
            - NUMBER
            - CHECKBOX
            - FILE
            - SELECT
            - MULTI_SELECT
            - DATE
            - EMAIL
          description: Field type
        label:
          type: string
          minLength: 1
          maxLength: 255
          description: Display label for the field
        description:
          type: string
          maxLength: 512
          description: Help text for the field
        required:
          type: boolean
          default: false
          description: Whether the field is required
        order:
          type: integer
          minimum: 0
          description: Display order
        options:
          type: array
          default: []
          items:
            type: string
            minLength: 1
            maxLength: 255
          description: Options for SELECT and MULTI_SELECT fields
        fileTypes:
          type: string
          nullable: true
          maxLength: 255
          description: Allowed file types for FILE fields
        emailDomain:
          type: string
          nullable: true
          description: Allowed email domain for EMAIL fields
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: API key as Bearer token. Format "Bearer YOUR_API_KEY"