Docs/Plataforma e integrações/SDK JS/TS

O agente como
biblioteca.

O SDK JS/TS é um cliente type-safe gerado da spec OpenAPI do servidor. Suba uma instância, mande prompts, receba saída estruturada — tudo tipado, do request ao evento.

Disponível agoraReferência /sdk1 min de leitura

01Instalando

terminal

npm install @maxvision/sdk

02Servidor + cliente em uma chamada

app.tsts

import { createOpencode } from "@maxvision/sdk"

const mvcode = await createOpencode({
  port: 4096,
  config: { model: "anthropic/claude-sonnet-4-5" }
})

console.log(`Servidor em ${mvcode.server.url}`)
// … trabalhe com mvcode.client …
mvcode.server.close()

A instância lê a sua config normal; o objeto config sobrepõe inline. Opções: hostname, port, signal, timeout.

03Só o cliente

Para um servidor já em execução:

client.tsts

import { createOpencodeClient } from "@maxvision/sdk"

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

04O fluxo essencial

fluxo.tsts

// cria a sessão
const session = await client.session.create({ body: { title: "Auditoria" } })

// manda o prompt e espera a resposta
const result = await client.session.prompt({
  path: { id: session.data.id },
  body: { parts: [{ type: "text", text: "Liste os riscos deste projeto" }] }
})

A superfície espelha a API: session.* (create, prompt, command, shell, abort, fork, revert, share…), project.*, config.*, global.health(), eventos e arquivos. Tipos importáveis direto: Session, Message, Part…

05Saída estruturada

Peça JSON validado por schema — o modelo responde por uma ferramenta de saída estruturada, com retries de validação:

structured.tsts

const result = await client.session.prompt({
  path: { id: sessionId },
  body: {
    parts: [{ type: "text", text: "Pesquise a empresa e resuma" }],
    format: {
      type: "json_schema",
      retryCount: 2,
      schema: {
        type: "object",
        properties: {
          company: { type: "string" },
          founded: { type: "number" }
        },
        required: ["company", "founded"]
      }
    }
  }
})
result.data.info.structured_output  // JSON validado

Falhou após os retries? A resposta traz StructuredOutputError com a contagem de tentativas — trate como qualquer erro tipado. Descrições claras nas propriedades e schemas focados aumentam a taxa de acerto.

06Regenerando após mudanças

O SDK é gerado da spec do servidor. Se você estende a API (plugins com endpoints, forks internos), regenere o cliente para manter os tipos em dia — o contrato é a spec, não o código escrito à mão.

Compatibilidade · nomes herdados no SDK

As factories preservam os nomes herdados do núcleo — createOpencode / createOpencodeClient — para que integrações existentes compilem sem mudança. Um SDK Go de comunidade (o ecossistema opencode-go) também fala com o servidor; para código novo, o caminho oficial é o SDK JS @maxvision/sdk.