#SDKs and APIs

A3S Code provides Rust, Node.js, Python, and Go SDKs. Install the a3s CLI when you want the terminal application. Treat each registry and GitHub Releases as the source of truth for package versions and release status.

#Install

# Rust
cargo add a3s-code-core

# Node.js
npm install @a3s-lab/code

# Python
python -m pip install a3s-code

# Go
go get github.com/A3S-Lab/Code/sdk/go/v8

#Python wheel platforms (v8.2.0)

a3s-code on PyPI is a small pure-Python bootstrap. On first import it downloads the matching native wheel from the v8.2.0 GitHub Release and checks its SHA-256 manifest. Native wheels use the CPython 3.10 stable ABI (cp310-abi3), so the same asset supports CPython 3.10 through 3.14:

Each wheel contains a3s_code/moli/<moli executable> and a provenance record. The bootstrap extracts both the native extension and sidecar into the shared per-user cache. A process lock and atomic replacement make first import safe when several applications start together; subsequent applications reuse the same verified Moli installation. Linux musl is intentionally not listed: the upstream Moli release has no musl asset, so use a system Moli executable or an explicit Chrome/Lightpanda backend there.

For an Intel Mac on macOS 12 or later, install with the interpreter that will run your application:

python3.14 -m ensurepip --upgrade  # only if this interpreter has no pip
python3.14 -m pip install --upgrade pip
python3.14 -m pip install a3s-code

If python3.14 -m pip reports No module named pip, the error is in the Python environment, before A3S Code is imported. Initialize or reinstall pip for that interpreter and retry. The Intel wheel is x86_64 and targets macOS 12; it does not include the optional local ONNX embedding adapter. Keep workspace retrieval model-free or configure an explicitly authorized remote embedding provider on Intel.

#Go module and bridge

The Go 1.23+ API is pure Go and does not require CGO. One long-lived a3s-code-go-bridge process owns the native runtime and carries multiplexed requests and EventEnvelopeV1 values over a versioned JSONL protocol.

A Go-enabled repository release publishes a path-prefixed module tag sdk/go/vX.Y.Z, matching release vX.Y.Z, together with a3s-code-go-bridge-SHA256SUMS, standalone bridge executables, and bundles that contain the matching Moli sidecar:

Download the bridge from GitHub Releases, verify it against the published SHA-256 file, and keep its version equal to the Go module version. Put it on PATH, set A3S_CODE_GO_BRIDGE, or pass code.WithBridgePath:

export A3S_CODE_GO_BRIDGE=/opt/a3s/bin/a3s-code-go-bridge

$env:A3S_CODE_GO_BRIDGE = 'C:\a3s\a3s-code-go-bridge.exe'

For an architecture without a release asset, build it from a source checkout:

bash .github/setup-workspace.sh
cargo build --release --package a3s-code-go-bridge --bin a3s-code-go-bridge

code.Create performs a fail-closed handshake for the transport protocol, event protocol, and complete operation inventory. Go failures use stable *code.Error codes while context cancellation and deadlines remain available through errors.Is. The bridge covers the complete serializable Agent/Session surface plus Go-backed hooks, budget guards, slash commands, and pipeline callbacks. Arbitrary Rust trait-object implementations remain a Rust-native extension mechanism; the other SDKs use their equivalent value configuration, callback, direct-tool, or MCP boundary.

#What the SDKs share

All four SDKs use the same session lifecycle, event format, and snapshots. A UI can subscribe to the same AgentEvent / EventEnvelopeV1 stream and resume saved work by session ID.

#Priority scheduler surface

v6.9 adds the same Agent-wide scheduler controls to every SDK. Select a session's urgent, interactive, foreground, background, or maintenance priority at creation time, then read the shared occupancy snapshot from the Agent or any sibling session:

The snapshot includes global capacity, active and pending totals, per-priority counts, and shutdown state. See Task scheduler for ordering, aging, cancellation, configuration, and complete examples.

#Safe-point run-control surface

Every SDK can steer or interrupt the currently active Run without opening a second transcript operation:

Requests use immutable Run IDs, optional optimistic turn guards, deadlines, and idempotency keys. Receipts distinguish accepted, applied, settled, and rejected; the shared run_control_applied event records safe-point application. See Sessions for complete examples and lifecycle semantics.

#Tool-result projection surface

All four SDKs pin the same versioned deterministic projection policy to a session:

Rust and Python expose a context_efficient() preset; Node.js and Go accept the same explicit fields. The policy persists in snapshots and every Tool result carries a3s.code.tool-result-evidence.v1 metadata. See Tools for field values, ordering, bounds, loss modes, and SDK examples.

The shared guides place Go beside Node.js and Python for the complete common SDK capability surface. Start with quick start, then continue to streaming, direct tools, sessions, verification, MCP, and persistence.

All four SDKs can configure persistence, memory, local/S3 workspaces, remote Git, permissions and confirmation, hooks, MCP, queues, deterministic replay, and orchestration. Rust additionally accepts arbitrary in-process trait implementations such as a custom LlmClient or ContextProvider; other languages integrate custom services through callbacks, direct tools, or MCP. For UI integration, start with sessions and event streams.

#Product capability discovery

The release has one product-level capability contract. sdkCapabilities() (or its language equivalent) returns the same ordered 27-record inventory in every official SDK. Each record has a stable identifier, category, canonical operation names, a description, and a hostOwned flag. hostOwned identifies who supplies policy, credentials, or an external lifecycle; it does not remove the operation from an SDK.

The inventory covers agent/runtime lifecycle, governed tools, code intelligence, workspace retrieval and tools, memory and cognitive packages, A3S Use tasks, model adapters, structured output, MCP and Skills, planning and priority scheduling, programmable workflows, persistence, state graphs, release/protocol contracts, web search, Moli, S3, agent serving, OpenTelemetry, conversation, run observability, and governance. Use the inventory for feature negotiation instead of guessing from package files or versions.

use a3s_code_core::{sdk_capabilities, sdk_capabilities_schema};

let capabilities = sdk_capabilities();
assert_eq!(sdk_capabilities_schema(), "a3s-code/sdk-capabilities/v1");
assert!(capabilities.iter().any(|item| item.id == "web_search"));

import { sdkCapabilities, sdkCapabilitiesSchema } from '@a3s-lab/code';

const capabilities = sdkCapabilities();
console.log(sdkCapabilitiesSchema(), capabilities.length);

from a3s_code import sdk_capabilities, sdk_capabilities_schema

capabilities = sdk_capabilities()
assert sdk_capabilities_schema() == "a3s-code/sdk-capabilities/v1"

capabilities, err := code.SDKCapabilities(ctx)
if err != nil {
	return err
}
fmt.Println(code.SDKCapabilitiesSchema(), len(capabilities))

#Moli runtime and web search

web_search is backed by a3s-search v3.1.0 and uses Moli by default for JavaScript-rendered engines. Runtime resolution is deterministic: an explicit browserPath/A3S_CODE_MOLI_EXECUTABLE, a packaged sidecar, the verified shared cache, a discoverable system Moli, and finally an HTTPS download of the pinned release. The cache is per user and version/target scoped; an exclusive install lock and atomic receipt prevent duplicate installations when several a3s-code processes start together. Set autoDownloadMoli: false (or the equivalent field) for strict offline operation.

The diagnostics call is read-only. The ensure call may download only after the caller has opted into the default automatic provisioning and the release manifest/hash checks pass. Linux musl has no upstream Moli asset in v8.2.0; use a system/explicit Moli executable or select the Chrome/Lightpanda backend there.

use a3s_code_core::{ensure_moli, moli_runtime_info, HeadlessConfig};
use std::time::Duration;

let config = HeadlessConfig::default();
let status = moli_runtime_info(Some(&config));
let executable = ensure_moli(&config, Duration::from_secs(120)).await?;
println!("{} {:?} {}", status.version, status.executable, executable.display());

import { BrowserBackend, ensureMoli, moliRuntimeInfo } from '@a3s-lab/code';

const status = moliRuntimeInfo({
  backend: BrowserBackend.Moli,
  autoDownloadMoli: true,
});
const executable = await ensureMoli({ backend: BrowserBackend.Moli });
console.log(status.version, executable);

from a3s_code import ensure_moli_async, moli_runtime_info

status = moli_runtime_info()
executable = await ensure_moli_async()
print(status["version"], executable)

status, err := code.MoliRuntimeInfo(ctx, code.NewMoliHeadlessConfig())
if err != nil {
	return err
}
executable, err := code.EnsureMoli(ctx, code.NewMoliHeadlessConfig())
if err != nil {
	return err
}
fmt.Println(status.Version, executable)