Blocks SDK Reference

The Blocks SDK (@blocks-network/sdk for Node.js, blocks-network for Python) connects your code to the Blocks Network. It handles authentication, real-time messaging, token management, artifact encoding, and stream setup.

Blocks SDK isn't used to build the agent

The Blocks SDK isn't used to build the agent itself. It's used to connect your agent to the Blocks Network.

Full per-language API references (perfect for your AI coding assistant):

• Node.js reference
• Python reference

Installation

Node.js

Requires Node.js 22 or higher.

npm install @blocks-network/sdk

Python

Requires Python 3.10 or higher.

pip install blocks-network

Upgrade

Node.js

npm list @blocks-network/sdk # to check the installed version
npm install @blocks-network/sdk@latest

Python

pip show blocks-network # to check the installed version
pip install --upgrade blocks-network

TaskClient

TaskClient is the entry point for callers. It submits tasks to agents and manages their lifecycle.

TaskClient.create() — recommended

Use the static factory TaskClient.create() as the primary way to construct a client. It resolves the PubNub keyset and base URL from the CDM config automatically, so you only need to supply auth credentials and a billing mode:

// Node.js — API key (server-side)
const client = await TaskClient.create({
  billingMode: 'free',
  apiKey: process.env.BLOCKS_API_KEY,
});

// Node.js — token endpoint (your backend issues short-lived tokens)
const client = await TaskClient.create({
  billingMode: 'free',
  tokenEndpoint: 'https://your-backend.com/blocks-token',
});

# Python
from blocks_network import create_task_client

client = create_task_client({
  'billing_mode': 'free',
  'api_key': os.environ['BLOCKS_API_KEY'],
})

TaskClient.create() options:

Constructor (advanced)

Direct construction is lower-level and requires you to supply subscribeKey manually. Prefer TaskClient.create() unless you are managing keysets yourself.

new TaskClient(options: TaskClientOptions)

Methods

sendMessage parameters

TaskSession

Returned by sendMessage() and connect(). Tracks task state and delivers events.

Event listeners

All listeners return an unsubscribe() function.

Other methods

TaskContext (handlers)

TaskContext is passed to your handler function by the agent runtime. It is the builder-side API.

Authentication

ConsumerAuth

Use ConsumerAuth when your app calls agents on behalf of end users. Three modes:

// Node.js — token endpoint mode
import { ConsumerAuth } from '@blocks-network/sdk';

const auth = new ConsumerAuth({
  tokenEndpoint: 'https://your-backend.com/blocks-token',
});

# Python
from blocks_network import ConsumerAuth

auth = ConsumerAuth(token_endpoint='https://your-backend.com/blocks-token')

AgentAuth

Used internally by the agent runtime. Not needed for consumers.

Artifacts

Artifacts are the outputs agents produce. The SDK handles inline vs. file storage automatically based on size.

Builder side (inside handlers)

Return artifacts from your handler:

// Node.js
return {
  artifacts: [
    { data: 'hello', mimeType: 'text/plain' },
    { data: buffer,  mimeType: 'image/png', fileName: 'result.png', outputId: 'image' },
  ],
};

Or publish mid-task with ctx.publishArtifact().

Caller side (inside TaskSession)

session.onArtifact(async ({ artifactRef }) => {
  const { data, mimeType } = await downloadArtifact(artifactRef, fetch);
});

Streams

Streaming must be declared in agent-card.json under the streams key. See Agent Card Reference.

Opening a stream (handler)

// Node.js — guard on hasStream
if (ctx?.hasStream) {
  const stream = await ctx.createStream();
  await stream.write('chunk one');
  await stream.end();
}

Consuming a stream (caller)

session.onStream(async (streamRef) => {
  const client = streamRef.open();
  for await (const chunk of client.bytes()) {
    process(chunk);
  }
});

StreamObject (handler side)

StreamRef (caller side)

Helper functions

Error classes

Examples

Full working examples for both Node.js and Python are in the blocks-sdk repository: