docker-agent/sdk/typescript

@docker/docker-agent-ts-sdk

TypeScript types for the docker-agent API (docker agent serve api): request and response bodies, sessions, agent configs and every event streamed by a session. They are generated from the Go types the server encodes, so they match the JSON it actually sends.

import type { AgentStreamingEvent } from '@docker/docker-agent-ts-sdk';

function render(event: AgentStreamingEvent) {
  switch (event.type) {
    case 'agent_choice':
      return event.content;
    case 'tool_call':
      return event.tool_call.function.name;
  }
}

Install

The package is published to GitHub Packages with every docker-agent release, at the same version: docker-agent v1.154.0 ships @docker/docker-agent-ts-sdk@1.154.0. Pin the version of the docker-agent you talk to.

GitHub Packages needs a token to install, even for public packages: a classic personal access token with the read:packages scope, or GITHUB_TOKEN in GitHub Actions. Map the @docker scope in your .npmrc:

@docker:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

npm install @docker/docker-agent-ts-sdk zod

TypeScript 5.4 or later is required.

Tools

The package also describes the builtin tools:

• <Tool>ArgsSchema: a strict Zod 4 schema of the tool's arguments, and <Tool>Args, its type. toolArgsSchemas maps tool names to them. Zod is a peer dependency.
• One as const list of tool names per toolset (filesystem, shell, …) and ToolName, their union.

import { toolArgsSchemas } from '@docker/docker-agent-ts-sdk';

const args = toolArgsSchemas.read_file.parse(JSON.parse(call.function.arguments));

The same types are also available as JSON Schemas (2020-12), one $defs entry per type: schemas/docker-agent.schema.json for the API and schemas/tool-args.schema.json for tool arguments.

Reading the types

• An optional property (name?: T) is omitted from the JSON when empty.
• T | null means the server may send null, usually for an unset list or object.
• Timestamps are RFC 3339 strings.
• AgentStreamingEvent is a union discriminated by type, and so is Toolset: each variant only has the fields its toolset type accepts.

Development

Everything under src/generated/ and schemas/ is generated by gen and committed. Don't edit it by hand; from the repository root:

task generate-ts # regenerate after changing Go API types or builtin tools
task check-ts    # what CI runs: fails when the output is stale, doesn't type-check or its tests fail

npm run build compiles src/ to dist/, which is what gets published alongside schemas/. CI builds and packs the package on every run to check its contents.

gen/config.go lists the Go types to expose and how to build each builtin toolset to read its tools. Types with a custom MarshalJSON need a schema in gen/overrides.go: the generator refuses to guess their shape, and fails on tool argument schemas it cannot translate to Zod.