opencode-agent-sdk

High-level agent runtime for @opencode-ai/sdk/v2.

This package wraps OpenCode's lower-level session and SSE APIs with a more agent-oriented model:

• declare agents once
• create reusable sessions
• call query() / receiveResponse() or runAgent()
• observe an existing session without sending a new prompt
• list sessions with their OpenCode status
• check OpenCode server health
• consume normalized text, tool-call, status, error, and final-result events

It is inspired by the usability level of Claude's agent SDK, but it does not try to be API-compatible 1:1.

Config behavior

This SDK follows OpenCode's normal config resolution and adds programmatic overrides on top.

• OpenCode still loads its normal config chain such as global config, project config, .opencode/, and managed config
• if OPENCODE_CONFIG_CONTENT is already present in the parent process, this SDK inherits and merges it by default
• options passed to createAgentRuntime() are applied as inline runtime overrides on top of the inherited config

In practice, the resolved precedence for config passed through this SDK is:

1. existing OPENCODE_CONFIG_CONTENT from the parent environment
2. options.config
3. SDK-managed overrides such as agents, mcp, permission, and model

Pass rawConfigContent if you want to override the inherited inline config content explicitly.

Why

@opencode-ai/sdk is a solid transport/client layer, but most applications still need to rebuild the same higher-level pieces:

• session lifecycle helpers
• per-turn completion handling
• stream filtering by session
• message delta vs snapshot reconciliation
• tool call lifecycle normalization
• final assistant message lookup

@liontree/opencode-agent-sdk packages those concerns into a reusable runtime.

Installation

npm install @liontree/opencode-agent-sdk

This package declares @opencode-ai/sdk and opencode-ai as dependencies, so you do not need to install them separately.

Requirements

• a working OpenCode provider/auth setup available through normal OpenCode config resolution or inline config passed to this SDK

Quick Start

npm install @liontree/opencode-agent-sdk

See examples/subagents.ts for a complete subagent lineage and resumeAgent() example, examples/attach.ts for attaching to an existing OpenCode server, and examples/observe.ts for monitoring an existing session.

import { createAgentRuntime } from "@liontree/opencode-agent-sdk"

const runtime = await createAgentRuntime({
  directory: "/app",
  model: "openai/gpt-5.4",
  mcp: {
    terminal: {
      type: "remote",
      url: "http://127.0.0.1:8000/mcp",
      oauth: false,
      timeout: 3600000,
    },
  },
  agents: {
    fuzzer: {
      description: "Expert in AFL++ fuzzing workflows.",
      prompt: "You are the fuzzing agent...",
    },
  },
})

const session = await runtime.createSession({ agent: "fuzzer" })

await session.query("Start fuzzing target libpng")

for await (const event of session.receiveResponse()) {
  switch (event.type) {
    case "status":
      console.log("status:", event.status)
      break
    case "text":
      process.stdout.write(event.text)
      break
    case "tool_call":
      console.log("tool:", event.toolName, event.status)
      break
    case "error":
      console.error("error:", event.error)
      break
    case "result":
      console.log("final text:\n", event.result.text)
      break
  }
}

await runtime.dispose()

This example assumes your OpenCode provider/auth configuration is already available through OpenCode's normal config resolution, for example:

• ~/.config/opencode/opencode.json
• opencode.json in the project
• environment variables consumed by your provider config
• existing OPENCODE_CONFIG_CONTENT

If you want to provide inline config explicitly, pass rawConfigContent or config.

const runtime = await createAgentRuntime({
  directory: "/app",
  rawConfigContent: JSON.stringify({
    provider: {
      openai: {
        options: {
          apiKey: "{env:OPENAI_API_KEY}",
        },
      },
    },
  }),
  agents: {
    researcher: {
      prompt: "You are a focused research agent.",
    },
  },
})

If you already have an OpenCode server running, attach to it with serverUrl:

const runtime = await createAgentRuntime({
  directory: "/app",
  serverUrl: "http://127.0.0.1:40937",
  model: "openai/gpt-5.4",
})

In attach mode, model still works as a local default and is sent with each prompt. Per-turn variant overrides are also sent with the prompt. Other runtime config such as config, mcp, permission, and rawConfigContent is not pushed into the existing server.

If you only need the final answer instead of a streamed event loop, use runAgent():

const result = await session.runAgent("Summarize the current repository")

console.log(result.text)

To switch model variants for a single turn, pass variant in the per-call options:

const result = await runtime.runAgent({
  agent: "general",
  model: "openai/gpt-5.4",
  variant: "high",
  prompt: "Analyze the repository's test strategy",
})

To stream descendant subagent activity in the same turn, pass includeSubagents: true and read event.source.chainText:

await session.query("Investigate the auth flow", { includeSubagents: true })

for await (const event of session.receiveResponse()) {
  if (event.type === "tool_call") {
    console.log(`[${event.source.chainText}]`, event.toolName, event.status)
  }
}

You can also reopen an existing session and optionally continue it with another turn:

const reopened = await runtime.resumeAgent({
  sessionID: "sess_123",
  prompt: "Continue from the last auth findings.",
})

for await (const event of reopened.receiveResponse()) {
  if (event.type === "text") {
    process.stdout.write(event.text)
  }
}

If you want to monitor an existing session without sending a new prompt, use observeSession():

const observer = await runtime.observeSession({
  sessionID: "sess_123",
  includeSubagents: true,
  resolveFinalResult: true,
  untilIdle: true,
})

for await (const event of observer.receiveResponse()) {
  if (event.type === "tool_call") {
    console.log(`[${event.source.chainText}]`, event.toolName, event.status)
  }
}

const result = await observer.result()
console.log(result?.text ?? "no final assistant message observed")

If you want a subagent to be able to launch another subagent via the task tool, you must allow it in that agent's permissions. OpenCode controls task separately from normal read/edit/bash permissions.

const runtime = await createAgentRuntime({
  directory: "/app",
  model: "openai/gpt-5.4",
  config: {
    agent: {
      general: {
        permission: {
          task: {
            "*": "allow",
          },
        },
      },
    },
  },
})

Use config.agent.<name>.permission.task when you want to override a built-in agent such as general. For custom agents declared in options.agents, you can also set permission directly on the agent definition.

Main API

createAgentRuntime(options)

Creates an OpenCode runtime in one of two modes:

• managed mode: starts and manages an OpenCode server, then injects agent prompts, optional default model, optional MCP config, optional permission config, and optional extra config merged with inherited inline config
• attach mode: connects to an existing OpenCode server with serverUrl

Attach mode does not push config, mcp, permission, or rawConfigContent into the existing server. model still works as a local default, and per-turn variant overrides are sent with each prompt. serverUrl cannot be combined with hostname, port, or timeoutMs.

runtime.createSession({ agent, model })

Creates a reusable OpenCode session and returns an OpencodeAgentSession.

runtime.openSession(sessionID, { agent, model })

Opens an existing OpenCode session and returns an OpencodeAgentSession handle.

runtime.listAgents()

Lists the agents currently available from the OpenCode runtime, including built-in subagents such as general and explore.

runtime.runAgent({ agent, prompt, model, variant })

Creates a fresh session, runs one turn, and resolves the final result.

runtime.resumeAgent({ sessionID, prompt?, agent?, model?, variant?, includeSubagents? })

Reopens an existing session and optionally starts another turn on it.

runtime.observeSession({ sessionID, agent?, includeSubagents?, untilIdle?, resolveFinalResult? })

Starts observing an existing session without sending a prompt.

• by default it only streams future events and stays attached until you call observer.stop()
• pass untilIdle: true to stop automatically when the observed session tree becomes idle
• pass resolveFinalResult: true only together with untilIdle: true when you want observer.result() to resolve the final assistant message for the observed turn

runtime.waitForSessionIdle({ sessionID, agent?, includeSubagents? })

Convenience helper that observes an existing session and resolves once it becomes idle.

runtime.health()

Checks whether the OpenCode server is reachable. Returns the server health payload on success and throws if the server is unhealthy or unreachable.

runtime.listSessions(limit?)

Returns a SessionListEntry[] for every session under the runtime's directory by default. Pass limit to cap how many entries are returned. Each entry includes:

• sessionID — OpenCode session identifier
• status — current status type ("busy", "idle", "retry", "unknown", etc.)
• agentType — detected agent type when available (null otherwise)
• title, createTime, directory, parentID

session.query(prompt, options)

Starts one turn on the session.

• pass includeSubagents: true to receive descendant subagent-session events in the same stream
• pass variant to choose a model variant for that turn, such as "low" or "high"
• to let a subagent launch more subagents, configure that agent's permission.task

session.receiveResponse()

Consumes the active turn as an async stream of normalized events:

• status
• text
• tool_call
• error
• result

receiveResponse() is single-consumer per turn.

session.runAgent(prompt, options)

Convenience helper that internally calls query() and consumes the response stream until a final result is available. It accepts the same per-turn options as query(), including variant.

observer.receiveResponse()

Consumes an observer as an async stream of normalized events.

receiveResponse() is single-consumer per observation.

observer.result()

Waits for the observer to finish and returns the resolved final assistant message when resolveFinalResult was enabled.

observer.waitForIdle()

Resolves when the observed session tree becomes idle.

observer.stop()

Stops local observation without interrupting the remote OpenCode session.

session.abort() / session.interrupt()

Both currently map to OpenCode's session abort behavior.

Event Model

status

Emitted on deduplicated session status transitions such as busy and idle.

text

Emitted for assistant text updates.

• format: "delta" means incremental text
• format: "snapshot" means the full part text was emitted to recover from a missing delta or stream correction

tool_call

Emitted when a tool part changes lifecycle state.

error

Emitted for prompt failures, session errors, SSE errors, or shutdown problems.

result

Emitted exactly once when the final assistant message can be resolved.

Source Metadata

Every normalized event now includes a source object describing where it came from.

• source.agentType: raw agent name such as build, general, or explore
• source.agentLabel: display label with sibling ordinal when needed, such as general#2
• source.chainText: readable lineage such as build -> general#2 -> explore#1
• source.sessionID: the session that produced the event
• source.parentSessionID: parent session ID when the event came from a descendant session
• source.rootSessionID: root session for the current lineage
• source.taskID: session ID when the event came from a subagent task, otherwise null
• source.sourceToolCallID: originating task tool call when known

event.agent and result.agent are preserved for compatibility and match source.agentType.

Notes

• This SDK is higher-level than raw OpenCode, not a workflow engine.
• It exposes OpenCode subagent lineage metadata, but it does not implement orchestration policy for you.
• It does not aim for complete Claude SDK compatibility.
• variant is a per-turn override only. Supported variant names depend on the selected model/provider and OpenCode configuration.
• Model resolution order is: per-call override -> session default -> agent default -> runtime default -> OpenCode config.
• observeSession() does not replay historical events. It streams future changes after the observer attaches, while priming enough current session state to keep text/tool updates and lineage tracking coherent.