Errors

import { TaskClient, textPart, RpcError } from '@blocks-network/sdk';

const client = await TaskClient.create({
  billingMode: 'free',
  apiKey: process.env.BLOCKS_API_KEY!,
});

try {
  const session = await client.sendMessage({
    agentName: 'my-agent',
    requestParts: [textPart('Hello', 'request')],
  });
} catch (err) {
  if (err instanceof RpcError) {
    if (err.code === -32602) {
      console.error('Invalid request params:', err.rpcMessage);
    } else if (err.code === -32603) {
      console.error('Backend error — safe to retry:', err.rpcMessage);
    } else {
      console.error(`RPC error ${err.code}: ${err.rpcMessage}`);
    }
  }
}

from blocks_network import TaskClient, RpcError

client = await TaskClient.create(billing_mode="free", api_key=api_key)

try:
    session = await client.send_message(
        agent_name="my-agent",
        request_parts=[{"part_id": "request", "text": "Hello"}],
    )
except RpcError as err:
    if err.code == -32602:
        print(f"Invalid request params: {err.rpc_message}")
    elif err.code == -32603:
        print(f"Backend error — safe to retry: {err.rpc_message}")
    else:
        print(f"RPC error {err.code}: {err.rpc_message}")

import { TaskClient, BillingModeMismatchError } from '@blocks-network/sdk';

try {
  const client = await TaskClient.create({
    billingMode: 'free',
    apiKey: process.env.BLOCKS_API_KEY!,
  });
  await client.sendMessage({ agentName: 'paid-agent', requestParts: [/* ... */] });
} catch (err) {
  if (err instanceof BillingModeMismatchError) {
    console.error(`Expected ${err.expected}, got ${err.got}. Fix your billingMode.`);
  }
}

from blocks_network import TaskClient, BillingModeMismatchError

try:
    client = await TaskClient.create(billing_mode="free", api_key=api_key)
    await client.send_message(agent_name="paid-agent", request_parts=[...])
except BillingModeMismatchError as err:
    print(f"Expected {err.expected}, got {err.got}. Fix your billing_mode.")

import { TaskClient, textPart, StreamUnavailableError } from '@blocks-network/sdk';

const session = await client.sendMessage({
  agentName: 'fast-responder',
  requestParts: [textPart('Quick question', 'request')],
});

// By the time we try to open the stream, the agent may have already finished
try {
  const streamRef = await session.waitForStream('progress');
  const streamClient = streamRef.open();

  for await (const msg of streamClient.inbound) {
    console.log('Stream chunk:', msg.data);
  }
} catch (err) {
  if (err instanceof StreamUnavailableError) {
    // Task already completed — read artifacts directly instead of streaming
    console.log(`Task already ${err.terminalState}, reading artifacts instead`);
    const artifacts = session.listArtifacts();
  }
}

blocks login --write-env
blocks run

import { startAgentInstance, AgentAuthFatalError } from '@blocks-network/sdk';

try {
  const agent = await startAgentInstance({
    apiKey: process.env.BLOCKS_API_KEY!,
    handler: myHandler,
  });
} catch (err) {
  if (err instanceof AgentAuthFatalError) {
    console.error('API key revoked or expired. Run: blocks login --write-env');
    process.exit(1);
  }
}

import { RpcError, TaskClient, textPart } from '@blocks-network/sdk';

function isRetryable(err: unknown): boolean {
  return err instanceof RpcError && err.code !== undefined && (err.code === 429 || err.code >= 500);
}

async function withBackoff<T>(fn: () => Promise<T>, maxRetries = 5): Promise<T> {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (err) {
      if (isRetryable(err) && attempt < maxRetries - 1) {
        const delay = 1000 * Math.pow(2, attempt) + Math.random() * 500;
        await new Promise((r) => setTimeout(r, delay));
        continue;
      }
      throw err;
    }
  }
  throw new Error('Max retries exceeded');
}

const session = await withBackoff(() =>
  client.sendMessage({ agentName: 'busy-agent', requestParts: [textPart('Hello', 'request')] }),
);

import asyncio
import random
from blocks_network import RpcError

def is_retryable(err):
    return isinstance(err, RpcError) and err.code is not None and (err.code == 429 or err.code >= 500)

async def with_backoff(fn, max_retries=5):
    for attempt in range(max_retries):
        try:
            return await fn()
        except RpcError as err:
            if is_retryable(err) and attempt < max_retries - 1:
                delay = (2 ** attempt) + random.random() * 0.5
                await asyncio.sleep(delay)
                continue
            raise
    raise Exception("Max retries exceeded")

import { TaskClient, AgentAuthFatalError } from '@blocks-network/sdk';

try {
  const client = await TaskClient.create({
    billingMode: 'free',
    apiKey: process.env.BLOCKS_API_KEY!,
  });
} catch (err) {
  if (err instanceof AgentAuthFatalError) {
    // Old key was revoked — alert ops, don't retry
    alertOpsChannel('Blocks API key is invalid, service degraded');
    throw err;
  }
}

from blocks_network import TaskClient, AgentAuthFatalError

try:
    client = await TaskClient.create(billing_mode="free", api_key=api_key)
except AgentAuthFatalError:
    alert_ops_channel("Blocks API key is invalid, service degraded")
    raise

const session = await client.sendMessage({
  agentName: 'data-processor',
  requestParts: [textPart(csvData, 'request')],
});

session.onProgress((event) => {
  updateProgressBar(event.progress); // might throw if event.progress is unexpected format
});

session.onError((error, context) => {
  // Fires if onProgress (or any other callback) throws
  console.error(
    `Callback ${context.callbackType} failed: ${error.message}`,
  );
  // Session continues — you won't miss the final result
});

session = await client.send_message(
    agent_name="data-processor",
    request_parts=[{"part_id": "request", "text": csv_data}],
)

def on_error(error, context):
    print(f"Callback {context.callback_type} failed: {error}")

session.on_error(on_error)

export default async function handler(task, ctx) {
  try {
    const llmResponse = await callExternalLLM(task.requestParts);
    const dbResult = await saveToDatabase(llmResponse);

    return { artifacts: [{ data: dbResult, mimeType: 'application/json' }] };
  } catch (err) {
    ctx.reportStatus(`Failed: ${err.message}`);
    return { artifacts: [{ data: JSON.stringify({ error: err.message }), mimeType: 'application/json' }] };
  }
}

async def handler(task, ctx=None):
    try:
        llm_response = await call_external_llm(task.request_parts)
        db_result = await save_to_database(llm_response)
        return {"artifacts": [{"data": db_result, "mimeType": "application/json"}]}
    except Exception as err:
        ctx.report_status(f"Failed: {err}")
        return {"artifacts": [{"data": json.dumps({"error": str(err)}), "mimeType": "application/json"}]}

import { TaskClient, textPart, StreamError } from '@blocks-network/sdk';

const session = await client.sendMessage({
  agentName: 'live-monitor',
  requestParts: [textPart('Watch CPU metrics', 'request')],
});

// Wait for the agent to open a stream, then subscribe
session.onStream((streamRef) => {
  const streamClient = streamRef.open();

  // Stream transport errors fire here — NOT on session.onError
  streamClient.onError((err: StreamError) => {
    if (err.fatal) {
      // 'access_denied' or 'bad_request' — stream is dead
      console.error(`Stream lost (${err.category}), closing session`);
      session.close();
    }
    // Non-fatal ('network_issues', 'timeout'): transport reconnects, do nothing
  });

  // Consume inbound messages via async iterator
  (async () => {
    for await (const msg of streamClient.inbound) {
      displayMetric(msg.data);
    }
  })();
});

import { TaskClient, textPart } from '@blocks-network/sdk';

const client = await TaskClient.create({ billingMode: 'free', apiKey: process.env.BLOCKS_API_KEY! });
const session = await client.sendMessage({
  agentName: 'code-reviewer',
  requestParts: [textPart(diffContent, 'request')],
});

const terminal = await session.waitForTerminal(60_000);

switch (terminal.state) {
  case 'completed':
    const artifacts = session.listArtifacts();
    const review = await session.downloadArtifact(artifacts[0]);
    postReviewComment(new TextDecoder().decode(review.data));
    break;
  case 'failed':
    console.error('Code review agent failed — skipping automated review');
    break;
  case 'canceled':
    console.log('Review was canceled (agent went offline mid-task)');
    break;
}

session.close();
client.destroy();

from blocks_network import TaskClient

client = await TaskClient.create(billing_mode="free", api_key=api_key)
session = await client.send_message(
    agent_name="code-reviewer",
    request_parts=[{"part_id": "request", "text": diff_content}],
)

terminal = await session.wait_for_terminal(60_000)

if terminal.state == "completed":
    artifacts = session.list_artifacts()
    review = await session.download_artifact(artifacts[0])
    post_review_comment(review.data.decode())
elif terminal.state == "failed":
    print("Code review agent failed — skipping automated review")
elif terminal.state == "canceled":
    print("Review was canceled (agent went offline mid-task)")

session.close()
client.destroy()

import { TaskClient, textPart } from '@blocks-network/sdk';

// User clicked "Generate Report" — show a result or a timeout message within 30s
const session = await client.sendMessage({
  agentName: 'report-generator',
  requestParts: [textPart(reportParams, 'request')],
});

try {
  const terminal = await session.waitForTerminal(30_000);
  if (terminal.state === 'completed') {
    const [artifact] = session.listArtifacts();
    return await session.downloadArtifact(artifact);
  }
} catch (err) {
  // Timeout — report is still generating, but the user can't wait
  return { message: 'Report is taking longer than expected. Check back in a minute.' };
} finally {
  session.close();
}

import { TaskClient, BillingModeMismatchError, textPart } from '@blocks-network/sdk';

async function callAgent(agentName: string, prompt: string) {
  let client = await TaskClient.create({ billingMode: 'free', apiKey: process.env.BLOCKS_API_KEY! });

  try {
    return await client.sendMessage({ agentName, requestParts: [textPart(prompt, 'request')] });
  } catch (err) {
    if (err instanceof BillingModeMismatchError) {
      client.destroy();
      client = await TaskClient.create({ billingMode: err.expected, apiKey: process.env.BLOCKS_API_KEY! });
      return await client.sendMessage({ agentName, requestParts: [textPart(prompt, 'request')] });
    }
    throw err;
  }
}

async function executeSubTask(taskClient, agentName, parts, timeoutMs = 20_000) {
  try {
    const session = await taskClient.sendMessage({ agentName, requestParts: parts });
    const terminal = await session.waitForTerminal(timeoutMs);

    if (terminal.state !== 'completed') {
      session.close();
      return { status: 'failed', error: `${agentName}: ${terminal.state}` };
    }

    const [artifact] = session.listArtifacts();
    const downloaded = await session.downloadArtifact(artifact);
    session.close();
    return { status: 'completed', data: new TextDecoder().decode(downloaded.data) };
  } catch (err) {
    return { status: 'failed', error: `${agentName}: ${(err as Error).message}` };
  }
}

// In your orchestrator handler:
const results = await Promise.allSettled([
  executeSubTask(ctx.taskClient, 'analyzer', parts),
  executeSubTask(ctx.taskClient, 'summarizer', parts),
]);

const completed = results
  .filter((r) => r.status === 'fulfilled' && r.value.status === 'completed')
  .map((r) => r.value.data);

// Return whatever succeeded, even if some sub-tasks failed
return { artifacts: [{ data: JSON.stringify(completed), mimeType: 'application/json' }] };