SDK

Le SDK opencode JS/TS fournit un client de type sécurisé pour interagir avec le serveur. Utilisez-le pour créer des intégrations et contrôler opencode par programme.

En savoir plus sur le fonctionnement du serveur. Pour des exemples, consultez les projects construits par la communauté.

Installez le SDK à partir de npm :

Terminal

npm install @opencode-ai/sdk

Créez une instance de opencode :

JavaScript

import { createOpencode } from "@opencode-ai/sdk"

const { client } = await createOpencode()

Cela démarre à la fois un serveur et un client

Options

Options	Tapez	Descriptif	Par défaut
`hostname`	`string`	Nom d’hôte du serveur	`127.0.0.1`
`port`	`number`	Port du serveur	`4096`
`signal`	`AbortSignal`	Signal d’abandon pour annulation	`undefined`
`timeout`	`number`	Délai d’attente en ms pour le démarrage du serveur	`5000`
`config`	`Config`	Objet de configuration	`{}`

Vous pouvez transmettre un objet de configuration pour personnaliser le comportement. L’instance récupère toujours votre opencode.json, mais vous pouvez remplacer ou ajouter une configuration en ligne :

JavaScript

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()

Si vous disposez déjà d’une instance en cours d’exécution de opencode, vous pouvez créer une instance client pour vous y connecter :

JavaScript

import { createOpencodeClient } from "@opencode-ai/sdk"

const client = createOpencodeClient({
  baseUrl: "http://localhost:4096",
})

Options

Options	Tapez	Descriptif	Par défaut
`baseUrl`	`string`	URL du serveur	`http://localhost:4096`
`fetch`	`function`	Implémentation de récupération personnalisée	`globalThis.fetch`
`parseAs`	`string`	Méthode d’analyse des réponses	`auto`
`responseStyle`	`string`	Style de retour : `data` ou `fields`	`fields`
`throwOnError`	`boolean`	Lancez des erreurs au lieu de return	`false`

Le SDK inclut des définitions TypeScript pour tous les types API. Importez-les directement :

TypeScript

import type { Session, Message, Part } from "@opencode-ai/sdk"

Tous les types sont générés à partir de la spécification OpenAPI du serveur et disponibles dans le fichier de types.

Le SDK peut générer des erreurs que vous pouvez détecter et gérer :

TypeScript

try {
  await client.session.get({ path: { id: "invalid-id" } })
} catch (error) {
  console.error("Failed to get session:", (error as Error).message)
}

Vous pouvez demander une sortie JSON structurée au modèle en spécifiant un format avec un schéma JSON. Le modèle utilisera un outil StructuredOutput pour renvoyer un JSON validé correspondant à votre schéma.

TypeScript

const result = await client.session.prompt({
  path: { id: sessionId },
  body: {
    parts: [{ type: "text", text: "Research Anthropic and provide company info" }],
    format: {
      type: "json_schema",
      schema: {
        type: "object",
        properties: {
          company: { type: "string", description: "Company name" },
          founded: { type: "number", description: "Year founded" },
          products: {
            type: "array",
            items: { type: "string" },
            description: "Main products",
          },
        },
        required: ["company", "founded"],
      },
    },
  },
})

// Access the structured output
console.log(result.data.info.structured_output)
// { company: "Anthropic", founded: 2021, products: ["Claude", "Claude API"] }

Type	Description
`text`	Par défaut. Réponse textuelle standard (pas de sortie structurée)
`json_schema`	Renvoie un JSON validé correspondant au schéma fourni

Lors de l’utilisation de type: 'json_schema', fournissez :

Champ	Type	Description
`type`	`'json_schema'`	Requis. Spécifie le mode de schéma JSON
`schema`	`object`	Requis. Objet JSON Schema définissant la structure de sortie
`retryCount`	`number`	Facultatif. Nombre de tentatives de validation (par défaut : 2)

Si le modèle ne parvient pas à produire une sortie structurée valide après toutes les tentatives, la réponse inclura une StructuredOutputError :

TypeScript

if (result.data.info.error?.name === "StructuredOutputError") {
  console.error("Failed to produce structured output:", result.data.info.error.message)
  console.error("Attempts:", result.data.info.error.retries)
}

Fournissez des descriptions claires dans les propriétés de votre schéma pour aider le modèle à comprendre quelles données extraire
Utilisez required pour spécifier quels champs doivent être présents
Gardez les schémas ciblés - les schémas imbriqués complexes peuvent être plus difficiles à remplir correctement pour le modèle
Définissez un retryCount approprié - augmentez-le pour les schémas complexes, diminuez-le pour les simples

Le SDK expose toutes les API du serveur via un client de type sécurisé.

Méthode	Descriptif	Réponse
`global.health()`	Vérifier l’état et la version du serveur	`{ healthy: true, version: string }`

Exemples

JavaScript

const health = await client.global.health()
console.log(health.data.version)

Méthode	Descriptif	Réponse
`app.log()`	Écrire une entrée de journal	`boolean`
`app.agents()`	Liste tous les agents disponibles	`Agent[]`

Exemples

JavaScript

// 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()

Méthode	Descriptif	Réponse
`project.list()`	Lister tous les projets	`Project[]`

Exemples

JavaScript

// List all projects
const projects = await client.project.list()

Méthode	Descriptif	Réponse
`path.get()`	Obtenir le chemin actuel	`Path`

Exemples

JavaScript

// Get current path information
const pathInfo = await client.path.get()

Méthode	Descriptif	Réponse
`config.get()`	Obtenir des informations de configuration	`Config`
`config.providers()`	Liste des fournisseurs et modèles par défaut	`{ providers:` `Provider[], default: { [key: string]: string } }`

Exemples

JavaScript

const config = await client.config.get()

const { providers, default: defaults } = await client.config.providers()

Méthode	Descriptif	Remarques
`session.list()`	Liste des séances	Renvoie `Session[]`
`session.get({ path })`	Obtenir une session	Renvoie `Session`
`session.children({ path })`	Liste des sessions enfants	Renvoie `Session[]`
`session.create({ body })`	Créer une séance	Renvoie `Session`
`session.delete({ path })`	Supprimer la séance	Renvoie `boolean`
`session.update({ path, body })`	Mettre à jour les propriétés de la session	Renvoie `Session`
`session.init({ path, body })`	Analysez l’application et créez `AGENTS.md`	Renvoie `boolean`
`session.abort({ path })`	Abandonner une session en cours	Renvoie `boolean`
`session.share({ path })`	Séance de partage	Renvoie `Session`
`session.unshare({ path })`	Annuler le partage de la session	Renvoie `Session`
`session.summarize({ path, body })`	Résumer la séance	Renvoie `boolean`
`session.messages({ path })`	Liste des messages dans une session	Renvoie `{ info:` `Message, parts:` `Part[]}[]`
`session.message({ path })`	Obtenir les détails du message	Renvoie `{ info:` `Message, parts:` `Part[]}`
`session.prompt({ path, body })`	Envoyer un message d’invite	`body.noReply: true` renvoie UserMessage (contexte uniquement). La valeur par défaut renvoie `AssistantMessage` avec réponse IA. Prend en charge `body.outputFormat` pour sortie structurée
`session.command({ path, body })`	Envoyer la commande à la session	Renvoie `{ info:` `AssistantMessage, parts:` `Part[]}`
`session.shell({ path, body })`	Exécuter une commande shell	Renvoie `AssistantMessage`
`session.revert({ path, body })`	Rétablir un message	Renvoie `Session`
`session.unrevert({ path })`	Restaurer les messages annulés	Renvoie `Session`
`postSessionByIdPermissionsByPermissionId({ path, body })`	Répondre à une demande d’autorisation	Renvoie `boolean`

Exemples

JavaScript

// 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." }],
  },
})

Méthode	Descriptif	Réponse
`find.text({ query })`	Rechercher du texte dans des fichiers	Tableau d’objets correspondant avec `path`, `lines`, `line_number`, `absolute_offset`, `submatches`
`find.files({ query })`	Rechercher des fichiers et des répertoires par nom	`string[]` (chemins)
`find.symbols({ query })`	Rechercher des symboles d’espace de travail	`Symbol[]`
`file.read({ query })`	Lire un fichier	`{ type: "raw" \| "patch", content: string }`
`file.status({ query? })`	Obtenir le statut des fichiers suivis	`File[]`

find.files prend en charge quelques champs de requête facultatifs :

type : "file" ou "directory"
directory : remplace la racine du projet pour la recherche
limit : résultats maximum (1 à 200)

Exemples

JavaScript

// 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" },
})

Méthode	Descriptif	Réponse
`tui.appendPrompt({ body })`	Ajouter du texte à l’invite	`boolean`
`tui.openHelp()`	Ouvrir la boîte de dialogue d’aide	`boolean`
`tui.openSessions()`	Ouvrez le sélecteur de session	`boolean`
`tui.openThemes()`	Ouvrez le sélecteur de thème	`boolean`
`tui.openModels()`	Ouvrez le sélecteur de modèle	`boolean`
`tui.submitPrompt()`	Soumettre l’invite actuelle	`boolean`
`tui.clearPrompt()`	Effacez l’invite	`boolean`
`tui.executeCommand({ body })`	Exécuter une commande	`boolean`
`tui.showToast({ body })`	Afficher la notification toast	`boolean`

Exemples

JavaScript

// Control TUI interface
await client.tui.appendPrompt({
  body: { text: "Add this to prompt" },
})

await client.tui.showToast({
  body: { message: "Task completed", variant: "success" },
})

Méthode	Descriptif	Réponse
`auth.set({ ... })`	Définir les informations d’authentification	`boolean`

Exemples

JavaScript

await client.auth.set({
  path: { id: "anthropic" },
  body: { type: "api", key: "your-api-key" },
})

Méthode	Descriptif	Réponse
`event.subscribe()`	Flux d’événements envoyés par le serveur	Flux d’événements envoyés par le serveur

Exemples

JavaScript

// 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)
}

SDK

Installer

Créer un client

Options

Configuration

Client uniquement

Options

Types

Erreurs

Sortie structurée

Utilisation de base

Types de format de sortie

Format de schéma JSON

Gestion des erreurs

Bonnes pratiques

APIs

Mondial

Exemples

Application

Exemples

Projet

Exemples

Chemin

Exemples

Configuration

Exemples

Séances

Exemples

Fichiers

Exemples

TUI

Exemples

Authentification

Exemples

Événements

Exemples