/blocks-network

name: blocks-network
description: Modify, validate, run, register, publish, consume, and troubleshoot agents on Blocks Network. Use when an agent project already exists, when deploying existing code, or when working with agent-card.json, the Blocks CLI, TaskClient, streams, private access, or publishing. For a brand-new agent, use blocks-getstarted. Do not use for generic AI-agent work or for a Blocks Enterprise deployment, which serves its own skill at <deployment>/skill.md.
metadata:
  author: blocks-network
  version: "0.4.1"

Blocks Network

Work on Blocks agents on Blocks Network, the public multi-tenant Blocks deployment. The CLI and SDKs target it by default; `blocks login --network` selects it explicitly.

A Blocks Enterprise deployment is a separate single-tenant instance with its own authentication, discovery, and visibility. It serves its own skill at `<deployment>/skill.md`. Do not configure against one unless the user names it.

Route before acting

Load only the material needed for the request:

• **Create a brand-new agent:** use [blocks-getstarted] and follow its linear

workflow. Do not duplicate that workflow here.

• **Edit or create `agent-card.json`:** read the [Agent Card Schema] first. It

is authoritative for field names, required fields, types, and conditional validation. Then read [Agent Card Reference].

• **Change inputs or outputs:** also read [IO Schema Reference]. Keep the card's

IO declarations aligned with what the handler accepts and returns.

• **TypeScript handlers, TaskClient, A2A, streams, or trigger scripts:** read

[Node Reference]. TypeScript is the default for new code. It opens with a table of contents; read only the sections the task needs.

• **One agent calling another from its handler:** [Node Reference] →

Agent-to-Agent (Orchestrator), then TaskClient & TaskSession for artifact download and decoding.

• **Cancellation:** [Node Reference] → TaskContext (`cancelSignal`,

`isCancelled`) and Pipe Tasks (Provider Handler) for the handler side; Task Lifecycle Methods and `onCancelRequested` under TaskClient & TaskSession for the consumer side.

• **Python:** read [Python Reference] only when the user requests Python or the

existing project is Python. Preserve the language of existing projects.

• **End-to-end development or deployment questions:** read [Agent Development

Guide].

When a schema and prose disagree, the schema wins. Examples illustrate patterns; they are not templates to copy without adapting names, descriptions, IO, task kinds, timeouts, and stream declarations.

Working method

1. Determine whether the user wants to modify an agent, deploy existing code, call an agent, manage access, or troubleshoot. Ask only when the distinction changes the work materially. 2. Locate candidate projects by `agent-card.json`, not by directory name. If more than one candidate fits, ask which one to use. 3. For an existing project, read its card and the file named by `runtime.handler` before editing. Treat `identity.agentName` as the agent's name even when the directory name differs. 4. Make the requested local changes. If handler input, output, task kind, or streaming behavior changes, update the matching card fields in the same change. 5. Run the smallest relevant local checks, including `blocks check` for every card change. `blocks check` needs no account or login; if `blocks` is not on the `PATH`, run `npx -y @blocks-network/cli check` rather than skipping it. Report failures with their actionable cause; do not claim the agent is deployed or running based only on local validation. 6. Hand off any live command the user must run, with the exact project path and agent name substituted.

Do not silently invent registry metadata, visibility, or pricing. The agent name, description, owning organization when ambiguous, private versus public listing, and free versus paid billing are user decisions.

Network invariants

Target Blocks Network

Authenticate against Blocks Network explicitly:

blocks login --network --write-env

In a non-interactive environment, always pass an explicit `--write-env` or `--no-write-env`; without a flag, a non-TTY login succeeds but silently leaves `.env` untouched. Use `--dir <project>` when logging in from a parent directory so the API key is written to the intended project's `.env`.

A `--network` login writes only `BLOCKS_API_KEY` and removes any `BLOCKS_BACKEND_URL` / `BLOCKS_CDM_URL` left by an earlier Enterprise login; the SDK's built-in defaults reach Blocks Network. Plain trigger and consumer processes launched outside `blocks run` need the key in their `.env`:

BLOCKS_API_KEY=<secret>

Never hardcode, print, commit, or send `BLOCKS_API_KEY` to browser code. Browser apps must use a supported user-auth flow from the Node reference rather than a provider API key.

Registration and visibility

• `blocks register` is the recommended first registration. It registers the

agent as free and private.

• A private agent is reachable only by its owner and by users or organizations

holding an active grant. Owning-organization membership confers nothing; the owner restores org-wide access by granting their own organization.

• `blocks publish` makes the agent public and/or paid on Blocks Network. In a

non-interactive shell it does not prompt: pass `--billing-mode {free|paid}` and `--listing {public|private}`; when paid, add `--accept-terms` and `--price` (or `--price-per-task` / `--price-per-minute` for dual-kind agents). Pass `--org-name` on the organization's first publish; when omitted the organization silently keeps its current name.

• Consumer `TaskClient` instances must pass the `billingMode` the agent is

registered with; a mismatch is rejected with `BillingModeMismatchError`. When it is unknown, look it up with `getAgent(name, { baseUrl, apiKey })`. `getAgent` has no default backend URL and throws `bas