SDK
opencode JS/TS SDK, sunucu ile etkileşmek için type-safe bir istemci sağlar. opencode’u programatik olarak kontrol etmek ve entegrasyonlar oluşturmak için kullanabilirsiniz.
Sunucu sayfasında nasıl çalıştığını görebilir, örnekler için topluluğun oluşturduğu projeler bölümüne bakabilirsiniz.
SDK’yı npm’den yükleyin:
npm install @opencode-ai/sdkBir opencode örneği oluşturun:
import { createOpencode } from "@opencode-ai/sdk"
const { client } = await createOpencode()Bu, hem bir sunucu hem de bir istemci başlatır
Seçenekler
| Seçenek | Tip | Açıklama | Varsayılan |
|---|---|---|---|
hostname | string | Sunucu ana bilgisayar adı | 127.0.0.1 |
port | number | Sunucu bağlantı noktası | 4096 |
signal | AbortSignal | İptal için durdurma sinyali | undefined |
timeout | number | Sunucu başlatma için ms cinsinden zaman aşımı | 5000 |
config | Config | Yapılandırma nesnesi | {} |
Davranışı özelleştirmek için bir yapılandırma nesnesi iletebilirsiniz. Örnek yine de opencode.json dosyanızı alır, ancak yapılandırmayı satır içi olarak geçersiz kılabilir veya ekleyebilirsiniz:
import { createOpencode } from "@opencode-ai/sdk"
const opencode = await createOpencode({
hostname: "127.0.0.1",
port: 4096,
config: {
model: "anthropic/claude-sonnet-5-5",
},
})
console.log(`Server running at ${opencode.server.url}`)
opencode.server.close()Halihazırda çalışan bir opencode örneğiniz varsa, ona bağlanmak için bir istemci örneği oluşturabilirsiniz:
import { createOpencodeClient } from "@opencode-ai/sdk"
const client = createOpencodeClient({
baseUrl: "http://localhost:4096",
})Seçenekler
| Seçenek | Tip | Açıklama | Varsayılan |
|---|---|---|---|
baseUrl | string | Sunucunun URL’si | http://localhost:4096 |
fetch | function | Özel fetch uygulaması | globalThis.fetch |
parseAs | string | Yanıt ayrıştırma yöntemi | auto |
responseStyle | string | Dönüş stili: data veya fields | fields |
throwOnError | boolean | Dönüş yerine hata fırlat | false |
SDK, tüm API türleri için TypeScript tanımlarını içerir. Bunları doğrudan içe aktarın:
import type { Session, Message, Part } from "@opencode-ai/sdk"Tüm tipler, sunucunun OpenAPI spesifikasyonundan oluşturulur ve tipler dosyasında mevcuttur.
SDK, yakalayabileceğiniz ve işleyebileceğiniz hatalar fırlatabilir:
try {
await client.session.get({ path: { id: "invalid-id" } })
} catch (error) {
console.error("Failed to get session:", (error as Error).message)
}Bir JSON şeması ile format belirterek modelden yapılandırılmış JSON çıktısı isteyebilirsiniz. Model, şemanızla eşleşen doğrulanmış JSON’u döndürmek için bir StructuredOutput aracı kullanacaktır.
const result = await client.session.prompt({
path: { id: sessionId },
body: {
parts: [{ type: "text", text: "Anthropic'i araştırın ve şirket bilgileri sağlayın" }],
format: {
type: "json_schema",
schema: {
type: "object",
properties: {
company: { type: "string", description: "Şirket adı" },
founded: { type: "number", description: "Kuruluş yılı" },
products: {
type: "array",
items: { type: "string" },
description: "Ana ürünler",
},
},
required: ["company", "founded"],
},
},
},
})
// Yapılandırılmış çıktıya erişin
console.log(result.data.info.structured_output)
// { company: "Anthropic", founded: 2021, products: ["Claude", "Claude API"] }| Tür | Açıklama |
|---|---|
text | Varsayılan. Standart metin yanıtı (yapılandırılmış çıktı yok) |
json_schema | Sağlanan şema ile eşleşen doğrulanmış JSON döndürür |
type: 'json_schema' kullanırken şunları sağlayın:
| Alan | Tür | Açıklama |
|---|---|---|
type | 'json_schema' | Gerekli. JSON şema modunu belirtir |
schema | object | Gerekli. Çıktı yapısını tanımlayan JSON Şema nesnesi |
retryCount | number | İsteğe bağlı. Doğrulama yeniden deneme sayısı (varsayılan: 2) |
Model, tüm yeniden denemelerden sonra geçerli bir yapılandırılmış çıktı üretemezse, yanıt bir StructuredOutputError içerecektir:
if (result.data.info.error?.name === "StructuredOutputError") {
console.error("Yapılandırılmış çıktı üretilemedi:", result.data.info.error.message)
console.error("Denemeler:", result.data.info.error.retries)
}- Açık açıklamalar sağlayın: Modelin hangi verileri çıkaracağını anlamasına yardımcı olmak için şema özelliklerinde
requiredkullanın: Hangi alanların mevcut olması gerektiğini belirtmek için- Şemaları odaklı tutun: Karmaşık iç içe geçmiş şemaların model tarafından doğru doldurulması daha zor olabilir
- Uygun
retryCountayarlayın: Karmaşık şemalar için artırın, basit olanlar için azaltın
SDK, tüm sunucu API’lerini type-safe bir istemci aracılığıyla sunar.
| Yöntem | Açıklama | Yanıt |
|---|---|---|
global.health() | Sunucu sağlığını ve sürümünü kontrol et | { healthy: true, version: string } |
Örnekler
const health = await client.global.health()
console.log(health.data.version)| Yöntem | Açıklama | Yanıt |
|---|---|---|
app.log() | Bir günlük girdisi yaz | boolean |
app.agents() | Tüm mevcut agent’ları listele | Agent[] |
Örnekler
// Write a log entry
await client.app.log({
body: {
service: "my-app",
level: "info",
message: "Operation completed",
},
})
// List available agents
const agents = await client.app.agents()| Yöntem | Açıklama | Yanıt |
|---|---|---|
project.list() | Tüm projeleri listele | Project[] |
Örnekler
// List all projects
const projects = await client.project.list()
| Yöntem | Açıklama | Yanıt |
|---|---|---|
path.get() | Mevcut yolu al | Path |
Örnekler
// Get current path information
const pathInfo = await client.path.get()| Yöntem | Açıklama | Yanıt |
|---|---|---|
config.get() | Yapılandırma bilgisini al | Config |
config.providers() | Sağlayıcıları ve varsayılan modelleri listele | { providers: Provider[], default: { [key: string]: string } } |
Örnekler
const config = await client.config.get()
const { providers, default: defaults } = await client.config.providers()| Yöntem | Açıklama | Notlar |
|---|---|---|
session.list() | Oturumları listele | Session[] döndürür |
session.get({ path }) | Oturum al | Session döndürür |
session.children({ path }) | Alt oturumları listele | Session[] döndürür |
session.create({ body }) | Oturum oluştur | Session döndürür |
session.delete({ path }) | Oturum sil | boolean döndürür |
session.update({ path, body }) | Oturum özelliklerini güncelle | Session döndürür |
session.init({ path, body }) | Uygulamayı analiz et ve AGENTS.md oluştur | boolean döndürür |
session.abort({ path }) | Çalışan bir oturumu iptal et | boolean döndürür |
session.share({ path }) | Oturum paylaş | Session döndürür |
session.unshare({ path }) | Oturum paylaşımını kaldır | Session döndürür |
session.summarize({ path, body }) | Oturumu özetle | boolean döndürür |
session.messages({ path }) | Oturumdaki mesajları listele | { info: Message, parts: Part[]}[] döndürür |
session.message({ path }) | Mesaj ayrıntılarını al | { info: Message, parts: Part[]} döndürür |
session.prompt({ path, body }) | İstem mesajı gönder | body.noReply: true UserMessage (yalnızca bağlam) döndürür. Varsayılan olarak AI yanıtıyla AssistantMessage döndürür. yapılandırılmış çıktı için body.outputFormat destekler |
session.command({ path, body }) | Oturuma komut gönder | { info: AssistantMessage, parts: Part[]} döndürür |
session.shell({ path, body }) | Bir kabuk komutu çalıştır | AssistantMessage döndürür |
session.revert({ path, body }) | Bir mesajı geri al | Session döndürür |
session.unrevert({ path }) | Geri alınan mesajları geri yükle | Session döndürür |
postSessionByIdPermissionsByPermissionId({ path, body }) | Bir izin isteğine yanıt ver | boolean döndürür |
Örnekler
// Create and manage sessions
const session = await client.session.create({
body: { title: "My session" },
})
const sessions = await client.session.list()
// Send a prompt message
const result = await client.session.prompt({
path: { id: session.id },
body: {
model: { providerID: "anthropic", modelID: "claude-sonnet-5-5" },
parts: [{ type: "text", text: "Hello!" }],
},
})
// Inject context without triggering AI response (useful for plugins)
await client.session.prompt({
path: { id: session.id },
body: {
noReply: true,
parts: [{ type: "text", text: "You are a helpful assistant." }],
},
})| Yöntem | Açıklama | Yanıt |
|---|---|---|
find.text({ query }) | Dosyalarda metin ara | path, lines, line_number, absolute_offset, submatches içeren eşleşme nesneleri dizisi |
find.files({ query }) | Dosya ve dizinleri isme göre bul | string[] (yollar) |
find.symbols({ query }) | Çalışma alanı sembollerini bul | Symbol[] |
file.read({ query }) | Bir dosyayı oku | { type: "raw" | "patch", content: string } |
file.status({ query? }) | İzlenen dosyalar için durumu al | File[] |
find.files birkaç isteğe bağlı sorgu alanını destekler:
type:"file"veya"directory"directory: arama için proje kökünü geçersiz kılmalimit: maksimum sonuç (1-200)
Örnekler
// Search and read files
const textResults = await client.find.text({
query: { pattern: "function.*opencode" },
})
const files = await client.find.files({
query: { query: "*.ts", type: "file" },
})
const directories = await client.find.files({
query: { query: "packages", type: "directory", limit: 20 },
})
const content = await client.file.read({
query: { path: "src/index.ts" },
})| Yöntem | Açıklama | Yanıt |
|---|---|---|
tui.appendPrompt({ body }) | İsteme metin ekle | boolean |
tui.openHelp() | Yardım iletişim kutusunu aç | boolean |
tui.openSessions() | Oturum seçiciyi aç | boolean |
tui.openThemes() | Tema seçiciyi aç | boolean |
tui.openModels() | Model seçiciyi aç | boolean |
tui.submitPrompt() | Mevcut istemi gönder | boolean |
tui.clearPrompt() | İstemi temizle | boolean |
tui.executeCommand({ body }) | Bir komut çalıştır | boolean |
tui.showToast({ body }) | Toast bildirimi göster | boolean |
Örnekler
// Control TUI interface
await client.tui.appendPrompt({
body: { text: "Add this to prompt" },
})
await client.tui.showToast({
body: { message: "Task completed", variant: "success" },
})| Yöntem | Açıklama | Yanıt |
|---|---|---|
auth.set({ ... }) | Kimlik bilgilerini ayarla | boolean |
Örnekler
await client.auth.set({
path: { id: "anthropic" },
body: { type: "api", key: "your-api-key" },
})| Yöntem | Açıklama | Yanıt |
|---|---|---|
event.subscribe() | Sunucu tarafından gönderilen olay akışı | Sunucu tarafından gönderilen olay akışı |
Örnekler
// Listen to real-time events
const events = await client.event.subscribe()
for await (const event of events.stream) {
console.log("Event:", event.type, event.properties)
}