Bu sayfa İngilizce belgenin çevirisidir. Komutlar, tanımlayıcılar ve örnekler aynıdır. Çalışma zamanı 7.24.4 · SDK 2.6.7. İngilizce kaynak

@defai-digital/ax-code-sdk paketi

AX Code kodlama ajanı çalışma zamanını kendi uygulamalarınıza entegre etmek için TypeScript SDK.

Uyumlu imzalı bir AX Code çalışma zamanını tipli başsız veya gRPC sınırları üzerinden gözetlemek, akış olaylarını tüketmek, oturum durumunu izdüşürmek ve uygulama entegrasyonlarını sınamak için kullanın. Özel çalışma zamanı paketini bilinçli sağlayan kaynak konakları süreç içi createAgent() bağdaştırıcısını da kullanabilir.

Kurulum

pnpm add jsr:@defai-digital/ax-code-sdk@2.6.7

deno add jsr:@defai-digital/ax-code-sdk@2.6.7

npx jsr add @defai-digital/ax-code-sdk@2.6.7

Node.js 26+ gerekir (veya Node uyumluluğuyla Deno). Daha eski Node.js sürümleri desteklenmez. Başsız ve gRPC yaşam döngüsü yardımcıları imzalı bir ax-code yürütülebilir dosyasını PATH üzerinde veya binary olarak geçirilen mutlak bir yolu bekler. SDK ve çalışma zamanı sürümleri bağımsızdır. Uygulama özelliklerini açmadan önce çalışma zamanı yetenek protokolünü denetleyin; tek başına bir SDK sürüm denetimi çalışma zamanı uyumluluğu oluşturmaz.

Çalışma alanı paket adı @ax-code/sdk bu monorepoya özeldir. Herkese açık tüketiciler JSR’den her zaman @defai-digital/ax-code-sdk kurar.

Rapor API geçişi

AX Code 7.24.1, DRE çizge raporunun yerini Run Report ile değiştirir. Rapor entegrasyonları ax-code run-report ve /run-report HTTP yollarını kullanmalıdır; eski dre-graph komutu ve /dre-graph yolları kaldırılmıştır. Üretilen SDK işlemleri artık getRunReportSessionSessionId ve getRunReportSessionSessionIdFingerprint değerleridir; karşılık gelen getDreGraph işlemlerinin yerini alırlar.

Rapor entegrasyonunu ve çalışma zamanını birlikte yükseltin. Diğer entegrasyon yüzeyleri yine kendi çalışma zamanı yetenek denetimlerini gerektirir.

Bir entegrasyon yüzeyi seçin

Herkese açık uygulamalar uyumlu imzalı bir AX Code çalışma zamanıyla headless veya grpc kullanmalıdır. HTTP/OpenAPI bu SDK’ların arkasında geri dönüş ve tanı katmanı olarak kalır. Eski @defai-digital/ax-code-sdk/v2 alt yolları çalışma zamanı uyumluluğu için kalır; yeni entegrasyonlar oradan başlamamalıdır.

createAgent() çağrı anında özel ax-code kaynak paketini yükler. Çalışma zamanı JSR’de yayımlanmaz.

Hızlı başlangıç (başsız)

import { createHeadlessClient, startHeadlessBackend } from "@defai-digital/ax-code-sdk/headless"

const directory = process.cwd()
const backend = await startHeadlessBackend({ directory })
try {
  const client = createHeadlessClient({
    baseUrl: backend.url,
    directory,
    headers: backend.headers,
  })
  const session = await client.createSession({ title: "SDK example" })
  await client.sendPrompt(session.id, {
    parts: [{ type: "text", text: "Summarize this project." }],
  })
} finally {
  await backend.close()
}

Masaüstü konaklar doğrulanmış mutlak bir yolu binary olarak geçirebilir. İzdüşüm tabanlı bir uygulama döngüsü için example/headless-app.ts dosyasına bakın.

Başsız arka uç

startHeadlessBackend rastgele bir geri döngü kapısında ax-code serve başlatır, tek kullanımlık bir kimlik bilgisi üretir, /global/health bekler ve bir tutamaç döndürür. close() SIGTERM, ardından SIGKILL gönderir.

import {
  startHeadlessBackend,
  createHeadlessClient,
  createHeadlessProjectionState,
  applyHeadlessProjectionEvent,
} from "@defai-digital/ax-code-sdk/headless"

const backend = await startHeadlessBackend({ directory: "/path/to/workspace" })
try {
  const client = createHeadlessClient({ baseUrl: backend.url, headers: backend.headers })
  const state = createHeadlessProjectionState()
  const session = await client.createSession({ title: "My session" })

  await client.sendPrompt(session.id, { parts: [{ type: "text", text: "Review this project" }] })
  for await (const event of client.subscribe()) {
    applyHeadlessProjectionEvent(state, event)
    if (state.session_status[session.id]?.type === "idle") break
  }
} finally {
  await backend.close()
}

createHeadlessProjectionState ve applyHeadlessProjectionEvent saf TypeScript’tir. Uygulama arayüzleri permission, question, session_diff, todo, session_status ve session_error değerlerini birincil durum olarak ele almalıdır. Otonom yanıtlar isteğe bağlıdır; gözetimli uygulamalar bekleyen izin ve soru isteklerini işlemelidir.

Otonom izdüşüm isolation_escalation, bash_destructive, ops_approve, webmcp, hook ve computer izinlerini bekler durumda tutar; üst verisi requireInteractive: true ayarlayan herhangi bir isteği de. Tüketiciler bu istekler için açık bir insan yanıtı almalıdır.

gRPC / yerel masaüstü

Yerel bir konak taşımayı zaten sahiplendiğinde @defai-digital/ax-code-sdk/grpc kullanın (Electron ön yüklemesi, Tauri, Rust, HTTP/2).

import {
  createAxCodeGrpcClientFromNativeIpc,
  resolveAxCodeGrpcProtoUrl,
  startAxCodeGrpcHeadlessBackend,
} from "@defai-digital/ax-code-sdk/grpc"

const backend = await startAxCodeGrpcHeadlessBackend({ directory: "/path/to/workspace" })
try {
  const client = backend.client
  await client.bootstrap.load({
    include: { sessions: true, providers: true, path: true, vcs: true },
  })
  const session = (await client.createSession({ title: "Desktop session" })) as { id: string }
  await client.sendPrompt(session.id, { parts: [{ type: "text", text: "Review this project" }] })
  const protoUrl = resolveAxCodeGrpcProtoUrl()
} finally {
  await backend.close()
}

• createAxCodeGrpcClientFromNativeIpc() — yapılandırılmış kopya IPC (ön yükleme / Tauri).
• createAxCodeGrpcClientFromNativeBridge() — aynı JavaScript alanı, AbortSignal ve zaman uyumsuz yinelenebilirlerle.
• createAxCodeGrpcClientFromNativeHandlers() — yöntem adlarını tipli işleyicilere bağlar; requireHandlers boşluklarda hızlı başarısız olur.
• startAxCodeGrpcNodeHttp2Server(), @defai-digital/ax-code-sdk/grpc/node içinden — aynı köprüyü yerel bir HTTP/2 gRPC uç noktası olarak açar.
• AX_CODE_GRPC_METHOD_DESCRIPTORS / listAxCodeGrpcMethods() — izin listeleri ve proto adları için kanonik yöntem kataloğu.

createAxCodeGrpcClientFromHttp() yalnızca geri döngüdür. Proto varlığı packages/sdk/proto/ax_code/v1/headless.proto dosyasıdır ve çalışma zamanında resolveAxCodeGrpcProtoUrl() ile çözülür.

Süreç içi ajan (yalnızca kaynak konakları)

Bu yol özel ax-code çalışma zamanı paketini gerektirir. Herkese açık uygulama entegrasyon sınırı değildir.

import { createAgent, tool } from "@defai-digital/ax-code-sdk"
import { z } from "zod"

const deploy = tool({
  name: "deploy_staging",
  description: "Deploy the current branch to staging",
  parameters: z.object({
    service: z.enum(["api", "web", "worker"]),
    skipTests: z.boolean().default(false),
  }),
  execute: async ({ service }) => ({ url: `https://staging.example.com/${service}` }),
})

const agent = await createAgent({ directory: "/repo", tools: [deploy] })

const result = await agent.run("Fix the login bug")
for await (const event of agent.stream("Explain this codebase")) {
  if (event.type === "text") process.stdout.write(event.text)
}
const session = await agent.session()
await session.run("Read src/auth/index.ts")
await agent.dispose()

Kimlik doğrulama ortam değişkenlerinden otomatik algılanır, auth: { provider, apiKey } ile enjekte edilir veya ax-code providers login üzerinden alınır.

import { ProviderError, ToolError, TimeoutError } from "@defai-digital/ax-code-sdk"

try {
  await agent.run("Deploy to prod")
} catch (e) {
  if (e instanceof ProviderError && e.isRetryable) console.log("Rate limited, retry later")
  else if (e instanceof ToolError) console.log(`Tool "${e.tool}" failed: ${e.message}`)
  else if (e instanceof TimeoutError) console.log(`Timed out after ${e.timeout}ms`)
}

Daha fazla örnek: example/programmatic.ts.

Sınama

import { createMockAgent, assertToolSuccess } from "@defai-digital/ax-code-sdk/testing"

test("CI bot scans for CVEs", async () => {
  const agent = createMockAgent({
    replies: ["Found 2 CVEs. Opening PR to bump versions."],
    toolCalls: [{ tool: "grep", input: { pattern: "CVE-" }, output: "CVE-2025-1234" }],
  })
  const result = await agent.run("scan for CVEs")
  expect(result.text).toContain("2 CVEs")
  assertToolSuccess(result, "grep")
})

Sürüm uyumluluğu

import { SDK_VERSION, isSDKVersionCompatible } from "@defai-digital/ax-code-sdk"

console.log(SDK_VERSION)
if (!isSDKVersionCompatible("^2.0.0")) {
  throw new Error("Incompatible SDK version")
}

İstek denetimleri ve yönlendirme

SDK 2.6 başsız isteklere isteğe bağlı denetimler ekler. Mevcut çağrılar davranışını korur; varsayılan bir son tarih dayatılmaz.

import { createHeadlessClient, HeadlessRequestError } from "@defai-digital/ax-code-sdk/headless"

const client = createHeadlessClient({
  baseUrl: backend.url,
  headers: backend.headers,
  directory,
  requestOptions: { timeoutMs: 30_000 },
})
const compatibility = await client.checkCompatibility({ requiredFeatures: ["sessions", "asyncPrompt"] })
if (!compatibility.compatible) throw new Error(compatibility.issues.join("; "))

const controller = new AbortController()
const state = await client.steering(sessionID, { signal: controller.signal, timeoutMs: 5_000 })
if (state.generation) {
  try {
    const receipt = await client.steer(
      sessionID,
      {
        expectedGeneration: state.generation,
        clientID, // Keep this id with the correction so uncertain outcomes can be reconciled.
        text: "Use the existing session contract.",
      },
      { signal: controller.signal },
    )
    console.log(receipt.status)
  } catch (error) {
    if (error instanceof HeadlessRequestError && error.status === 409) {
      console.log("Correction conflicts with a prior request; reconcile the steering state.")
    } else {
      throw error
    }
  }
}

client.taskQueue.steer(taskID) atomik kuyruklu takip uç noktasını açar. generation_not_active sonucu satırı değiştirmeden bırakır. SDK makbuzları ve ret gerekçelerini olduğu gibi döndürür. accepted daha sonraki bir döngü sınırı için kabul edildiği anlamına gelir; applied o sınırda dayanıklı kabul edildiği anlamına gelir, sağlayıcı tamamlaması ayrı kalır. Makbuzlar sürece yerel ve sınırlıdır; yeniden başlatmadan sonra yoklukları bir düzeltmenin hiç uygulanmadığını kanıtlamaz.

requestOptions iş akışı ve görev kuyruğu işlemleri dahil tüm başsız kolaylık istekleri ve komutları için varsayılanlar sağlar. Çekirdek oturum/komut yöntemleri ve yönlendirme çağrı başına geçersiz kılma kabul eder; timeoutMs: 0 varsayılan bir son tarihi kapatır. Abonelikler kendi signal değerini kullanır ve client.client üretilmiş istemcinin denetimlerini korur. Özel bir HeadlessTransport sinyali alır ve iptal olduğunda bekleyen kaynaklarını bırakmalıdır.

HTTP ve IPC iptali yerel beklemeyi durdurur. Gönderilmiş bir değişiklik yine yürütülebilir; daha fazla işlem yapmadan önce oturum/kuyruk durumunu uzlaştırın. İki taşıma da değişiklikleri yeniden denemez. Son tarihler TimeoutError yükseltir; çağıran iptalleri sinyalin gerekçesini korur. Başarısız HTTP ve IPC yanıtları HeadlessRequestError yükseltir; yanında status, body, method ve path vardır. IPC protokol hata çerçeveleri IpcTransportError korur.

Çalışma zamanı uyumluluğu ve SDK 2.5'ten yükseltme

Güncel üretilmiş sözleşme taban çizgisi AX Code kaynağı v7.23.0’dır. SDK 2.6 ilan edilmemiş özellikleri çalışma zamanı sürümünden çıkarmaz. Güncel yetenek kataloğu yönlendirmeyi ayrı ilan etmez; yönlendirme sunmadan önce okuma uç noktasını denetleyin ve desteklenmeyen yol hatalarını işleyin. SDK 2.6 mevcut üretilmiş ve başsız giriş noktalarını korur. Yeni yanıt hatası üst verisi ve istek denetimleri eklemelidir; Error yakalayan kod çalışmaya devam eder.

Daha eski sabitlemeleri yükselten uygulamalar önce imzalı çalışma zamanını doğrulamalı, sonra yetenek pazarlığını, olay izdüşümünü, bekleyen izinleri/soruları, iptali ve arka uç kapanışını sınamalıdır. Tüketici sabitleme değişiklikleri, hedef SDK yayımlandıktan sonra tüketen depoya aittir. Derlenmiş paketi yerel olarak pnpm --dir packages/sdk/js run test:consumer ile doğrulayın; bu, özel çalışma zamanı kaynak paketi olmadan yalıtılmış bir fikstürde herkese açık içe aktarmaları, bildirimleri ve proto varlıklarını denetler.

Diller arası entegrasyonlar

Bu paket birinci taraf TypeScript/JavaScript SDK’sıdır. Python, Go, Java, Rust veya diğer çalışma zamanları için depo gRPC proto’sundan üretin veya o entegrasyonun sahip olduğu CLI/çalışma zamanı sınırını kullanın.

@ax-code/sdk 1.4.0 sürümünden geçiş

./programmatic alt yolu varsayılan girişi hâlâ yeniden dışa aktarır; onu kullanımdan kalkmış olarak ele alın.

Lisans

Apache-2.0