Pular para o conteúdo

SDK

Cliente JS seguro em tipos para o servidor opencode.

O SDK JS/TS do opencode fornece um cliente seguro em tipos para interagir com o servidor. Use-o para construir integrações e controlar o opencode programaticamente.

Saiba mais sobre como o servidor funciona. Para exemplos, confira os projetos construídos pela comunidade.


Instalar

Instale o SDK a partir do npm:

Terminal window
npm install @opencode-ai/sdk

Criar cliente

Crie uma instância do opencode:

import { createOpencode } from "@opencode-ai/sdk"
const { client } = await createOpencode()

Isso inicia tanto um servidor quanto um cliente.

Opções

OpçãoTipoDescriçãoPadrão
hostnamestringNome do host do servidor127.0.0.1
portnumberPorta do servidor4096
signalAbortSignalSinal de abortar para cancelamentoundefined
timeoutnumberTempo limite em ms para iniciar o servidor5000
configConfigObjeto de configuração{}

Configuração

Você pode passar um objeto de configuração para personalizar o comportamento. A instância ainda pega seu opencode.json, mas você pode substituir ou adicionar configuração inline:

import { createOpencode } from "@opencode-ai/sdk"
const opencode = await createOpencode({
hostname: "127.0.0.1",
port: 4096,
config: {
model: "anthropic/claude-3-5-sonnet-20241022",
},
})
console.log(`Server running at ${opencode.server.url}`)
opencode.server.close()

Apenas cliente

Se você já tem uma instância do opencode em execução, pode criar uma instância de cliente para se conectar a ela:

import { createOpencodeClient } from "@opencode-ai/sdk"
const client = createOpencodeClient({
baseUrl: "http://localhost:4096",
})

Opções

OpçãoTipoDescriçãoPadrão
baseUrlstringURL do servidorhttp://localhost:4096
fetchfunctionImplementação de fetch personalizadaglobalThis.fetch
parseAsstringMétodo de análise da respostaauto
responseStylestringEstilo de retorno: data ou fieldsfields
throwOnErrorbooleanLançar erros em vez de retornarfalse

Tipos

O SDK inclui definições TypeScript para todos os tipos da API. Importe-os diretamente:

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

Todos os tipos são gerados a partir da especificação OpenAPI do servidor e estão disponíveis no arquivo de tipos.


Erros

O SDK pode lançar erros que você pode capturar e tratar:

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

APIs

O SDK expõe todas as APIs do servidor através de um cliente seguro em tipos.


Global

MétodoDescriçãoResposta
global.health()Verificar a saúde e versão do servidor{ healthy: true, version: string }

Exemplos

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

App

MétodoDescriçãoResposta
app.log()Escrever uma entrada de logboolean
app.agents()Listar todos os agentes disponíveisAgent[]

Exemplos

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

Projeto

MétodoDescriçãoResposta
project.list()Listar todos os projetosProject[]
project.current()Obter projeto atualProject

Exemplos

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

Caminho

MétodoDescriçãoResposta
path.get()Obter caminho atualPath

Exemplos

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

Configuração

MétodoDescriçãoResposta
config.get()Obter informações de configuraçãoConfig
config.providers()Listar provedores e modelos padrão{ providers: Provider[], default: { [key: string]: string } }

Exemplos

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

Sessões

MétodoDescriçãoNotas
session.list()Listar sessõesRetorna Session[]
session.get({ path })Obter sessãoRetorna Session
session.children({ path })Listar sessões filhasRetorna Session[]
session.create({ body })Criar sessãoRetorna Session
session.delete({ path })Deletar sessãoRetorna boolean
session.update({ path, body })Atualizar propriedades da sessãoRetorna Session
session.init({ path, body })Analisar app e criar AGENTS.mdRetorna boolean
session.abort({ path })Abortar uma sessão em execuçãoRetorna boolean
session.share({ path })Compartilhar sessãoRetorna Session
session.unshare({ path })Descompartilhar sessãoRetorna Session
session.summarize({ path, body })Resumir sessãoRetorna boolean
session.messages({ path })Listar mensagens em uma sessãoRetorna { info: Message, parts: Part[]}[]
session.message({ path })Obter detalhes da mensagemRetorna { info: Message, parts: Part[]}
session.prompt({ path, body })Enviar mensagem de promptbody.noReply: true retorna UserMessage (apenas contexto). O padrão retorna AssistantMessage com resposta da AI
session.command({ path, body })Enviar comando para a sessãoRetorna { info: AssistantMessage, parts: Part[]}
session.shell({ path, body })Executar um comando shellRetorna AssistantMessage
session.revert({ path, body })Reverter uma mensagemRetorna Session
session.unrevert({ path })Restaurar mensagens revertidasRetorna Session
postSessionByIdPermissionsByPermissionId({ path, body })Responder a um pedido de permissãoRetorna boolean

Exemplos

// 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-3-5-sonnet-20241022" },
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." }],
},
})

Arquivos

MétodoDescriçãoResposta
find.text({ query })Pesquisar texto em arquivosArray de objetos de correspondência com path, lines, line_number, absolute_offset, submatches
find.files({ query })Encontrar arquivos e diretórios por nomestring[] (caminhos)
find.symbols({ query })Encontrar símbolos no workspaceSymbol[]
file.read({ query })Ler um arquivo{ type: "raw" | "patch", content: string }
file.status({ query? })Obter status para arquivos rastreadosFile[]

find.files suporta alguns campos de consulta opcionais:

  • type: "file" ou "directory"
  • directory: substituir a raiz do projeto para a pesquisa
  • limit: resultados máximos (1–200)

Exemplos

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

TUI

MétodoDescriçãoResposta
tui.appendPrompt({ body })Adicionar texto ao promptboolean
tui.openHelp()Abrir o diálogo de ajudaboolean
tui.openSessions()Abrir o seletor de sessõesboolean
tui.openThemes()Abrir o seletor de temasboolean
tui.openModels()Abrir o seletor de modelosboolean
tui.submitPrompt()Enviar o prompt atualboolean
tui.clearPrompt()Limpar o promptboolean
tui.executeCommand({ body })Executar um comandoboolean
tui.showToast({ body })Mostrar notificação toastboolean

Exemplos

// Control TUI interface
await client.tui.appendPrompt({
body: { text: "Add this to prompt" },
})
await client.tui.showToast({
body: { message: "Task completed", variant: "success" },
})

Autenticação

MétodoDescriçãoResposta
auth.set({ ... })Definir credenciais de autenticaçãoboolean

Exemplos

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

Eventos

MétodoDescriçãoResposta
event.subscribe()Fluxo de eventos enviados pelo servidorFluxo de eventos enviados pelo servidor

Exemplos

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