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:
npm install @opencode-ai/sdkCriar 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ção | Tipo | Descrição | Padrão |
|---|---|---|---|
hostname | string | Nome do host do servidor | 127.0.0.1 |
port | number | Porta do servidor | 4096 |
signal | AbortSignal | Sinal de abortar para cancelamento | undefined |
timeout | number | Tempo limite em ms para iniciar o servidor | 5000 |
config | Config | Objeto 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ção | Tipo | Descrição | Padrão |
|---|---|---|---|
baseUrl | string | URL do servidor | http://localhost:4096 |
fetch | function | Implementação de fetch personalizada | globalThis.fetch |
parseAs | string | Método de análise da resposta | auto |
responseStyle | string | Estilo de retorno: data ou fields | fields |
throwOnError | boolean | Lançar erros em vez de retornar | false |
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étodo | Descrição | Resposta |
|---|---|---|
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étodo | Descrição | Resposta |
|---|---|---|
app.log() | Escrever uma entrada de log | boolean |
app.agents() | Listar todos os agentes disponíveis | Agent[] |
Exemplos
// Write a log entryawait client.app.log({ body: { service: "my-app", level: "info", message: "Operation completed", },})
// List available agentsconst agents = await client.app.agents()Projeto
| Método | Descrição | Resposta |
|---|---|---|
project.list() | Listar todos os projetos | Project[] |
project.current() | Obter projeto atual | Project |
Exemplos
// List all projectsconst projects = await client.project.list()
// Get current projectconst currentProject = await client.project.current()Caminho
| Método | Descrição | Resposta |
|---|---|---|
path.get() | Obter caminho atual | Path |
Exemplos
// Get current path informationconst pathInfo = await client.path.get()Configuração
| Método | Descrição | Resposta |
|---|---|---|
config.get() | Obter informações de configuração | Config |
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étodo | Descrição | Notas |
|---|---|---|
session.list() | Listar sessões | Retorna Session[] |
session.get({ path }) | Obter sessão | Retorna Session |
session.children({ path }) | Listar sessões filhas | Retorna Session[] |
session.create({ body }) | Criar sessão | Retorna Session |
session.delete({ path }) | Deletar sessão | Retorna boolean |
session.update({ path, body }) | Atualizar propriedades da sessão | Retorna Session |
session.init({ path, body }) | Analisar app e criar AGENTS.md | Retorna boolean |
session.abort({ path }) | Abortar uma sessão em execução | Retorna boolean |
session.share({ path }) | Compartilhar sessão | Retorna Session |
session.unshare({ path }) | Descompartilhar sessão | Retorna Session |
session.summarize({ path, body }) | Resumir sessão | Retorna boolean |
session.messages({ path }) | Listar mensagens em uma sessão | Retorna { info: Message, parts: Part[]}[] |
session.message({ path }) | Obter detalhes da mensagem | Retorna { info: Message, parts: Part[]} |
session.prompt({ path, body }) | Enviar mensagem de prompt | body.noReply: true retorna UserMessage (apenas contexto). O padrão retorna AssistantMessage com resposta da AI |
session.command({ path, body }) | Enviar comando para a sessão | Retorna { info: AssistantMessage, parts: Part[]} |
session.shell({ path, body }) | Executar um comando shell | Retorna AssistantMessage |
session.revert({ path, body }) | Reverter uma mensagem | Retorna Session |
session.unrevert({ path }) | Restaurar mensagens revertidas | Retorna Session |
postSessionByIdPermissionsByPermissionId({ path, body }) | Responder a um pedido de permissão | Retorna boolean |
Exemplos
// Create and manage sessionsconst session = await client.session.create({ body: { title: "My session" },})
const sessions = await client.session.list()
// Send a prompt messageconst 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étodo | Descrição | Resposta |
|---|---|---|
find.text({ query }) | Pesquisar texto em arquivos | Array de objetos de correspondência com path, lines, line_number, absolute_offset, submatches |
find.files({ query }) | Encontrar arquivos e diretórios por nome | string[] (caminhos) |
find.symbols({ query }) | Encontrar símbolos no workspace | Symbol[] |
file.read({ query }) | Ler um arquivo | { type: "raw" | "patch", content: string } |
file.status({ query? }) | Obter status para arquivos rastreados | File[] |
find.files suporta alguns campos de consulta opcionais:
type:"file"ou"directory"directory: substituir a raiz do projeto para a pesquisalimit: resultados máximos (1–200)
Exemplos
// Search and read filesconst 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étodo | Descrição | Resposta |
|---|---|---|
tui.appendPrompt({ body }) | Adicionar texto ao prompt | boolean |
tui.openHelp() | Abrir o diálogo de ajuda | boolean |
tui.openSessions() | Abrir o seletor de sessões | boolean |
tui.openThemes() | Abrir o seletor de temas | boolean |
tui.openModels() | Abrir o seletor de modelos | boolean |
tui.submitPrompt() | Enviar o prompt atual | boolean |
tui.clearPrompt() | Limpar o prompt | boolean |
tui.executeCommand({ body }) | Executar um comando | boolean |
tui.showToast({ body }) | Mostrar notificação toast | boolean |
Exemplos
// Control TUI interfaceawait client.tui.appendPrompt({ body: { text: "Add this to prompt" },})
await client.tui.showToast({ body: { message: "Task completed", variant: "success" },})Autenticação
| Método | Descrição | Resposta |
|---|---|---|
auth.set({ ... }) | Definir credenciais de autenticação | boolean |
Exemplos
await client.auth.set({ path: { id: "anthropic" }, body: { type: "api", key: "your-api-key" },})Eventos
| Método | Descrição | Resposta |
|---|---|---|
event.subscribe() | Fluxo de eventos enviados pelo servidor | Fluxo de eventos enviados pelo servidor |
Exemplos
// Listen to real-time eventsconst events = await client.event.subscribe()for await (const event of events.stream) { console.log("Event:", event.type, event.properties)}