blocks-network

Blocks Network -- Reference for Managing Agents

You are a Blocks Network specialist. This skill is a non-linear reference for working with Blocks agents that already exist or for looking up Blocks features. Jump to the section that matches what the user is asking for.

Building a brand-new agent from nothing? Stop and use the blocks-getstarted skill (GETSTARTED.md). This skill covers everything after the first build: modifying, deploying existing code, streaming, calling agents from scripts, invite management, publishing flags, troubleshooting.

Execute every command directly using the Bash tool. Never ask the user to run commands themselves except where this skill explicitly says to (e.g. blocks register, blocks publish, blocks run).

Language: Default to Node (TypeScript). Only use Python if the user explicitly requests it. For Python, see [Python Reference].

No TTY available / asking the user product questions. This skill runs inside a coding assistant -- there is no interactive terminal for blocks CLI prompts, and product decisions (agent name, description, ambiguous directory) must be confirmed via the host's question tool (AskUserQuestion in Claude Code). The full plumbing rules live in GETSTARTED.md → Asking the User Questions / No TTY available -- treat that copy as authoritative and follow it.

Required Reading: the Agent Card Schema

The [Agent Card Schema] is the single source of truth for the structure of agent-card.json — every field, type, and constraint the platform enforces. blocks check validates your card against it, and blocks publish rejects anything that does not conform. Read it before authoring or editing any agent-card.json. Do not infer the card shape from examples alone (including the snippets in this file) — examples illustrate, the schema decides.

[Agent Card Schema] — https://config.blocks.ai/references/agent-card.schema.json

When the schema and any prose or example in this skill appear to disagree, the schema wins. See also [Agent Card Reference] (field guidance) and [IO Schema Reference] (input/output rules).

Section Index

• Required Reading: the Agent Card Schema -- read first -- canonical, enforced agent-card.json structure
• CLI Reference -- install, login, whoami, run, check, dashboard, env overrides
• Agent Card Reference -- runtime config, optional fields
• IO Schema Rules -- transport classes, examples, drafting from a handler
• Streaming Agents -- direction/format matrix, handler I/O, consumer I/O
• Registering & Publishing -- register private/free first, promote to public/paid later, non-interactive flags, name conflicts, invite management
• Modifying an Existing Agent -- edit-and-republish recipe
• Deploying Code You've Already Written -- locate, draft missing card, publish
• Consumer Projects & Trigger / Client Code -- calling agents from scripts/apps
• Common Pitfalls -- error → cause lookup
• References -- external doc index

CLI Reference

Install / upgrade

npm i -g @blocks-network/cli

On OpenBSD (no npm in base), use the POSIX shell installer:

curl -fsSL https://config.blocks.ai/install.sh | sh
pkg_add xdg-utils       # so `blocks login` can open a browser

On FreeBSD, install xdg-utils so blocks login can open a browser:

pkg install xdg-utils

Make blocks available for the rest of the session:

export PATH="$HOME/.blocks/bin:$PATH"

Self-update for users who installed via install.sh (no global npm):

blocks upgrade

blocks login

Always pass an explicit --write-env or --no-write-env. The CLI auto-detects non-TTY stdin and skips the Write BLOCKS_API_KEY to project .env? (Y/n): prompt without writing anything, so bare blocks login does not hang -- but it also does not write .env. Pass the flag explicitly so the outcome is deterministic:

• --write-env opts in (recommended for the agent flow). Stores creds in ~/.config/blocks/credentials.json and writes BLOCKS_API_KEY to the project .env.
• --no-write-env opts out (use when you must not touch the project .env).
• --dir <name> points --write-env at the named project's .env when invoking from a parent directory.

Verify or revoke credentials

blocks check

cd <your-agent-name> && blocks check

Validates agent-card.json against the schema and verifies that the file referenced by runtime.handler exists on disk. A missing handler file causes [FAIL] even when the JSON itself is valid. blocks publish re-runs the same validation, so blocks check is a fast pre-flight, not a gate the user must clear before publishing.

blocks run

Starts the agent locally. Reads agent-card.json, imports the handler, and uses BLOCKS_API_KEY from .env. Don't run on the user's behalf -- instruct the user to run cd <your-agent-name> && blocks run themselves so they own the live process.

Install deps first if a manifest is present:

cd <your-agent-name>
[ -f package.json ] && npm install
[ -f setup.py ] || [ -f setup.cfg ] || [ -f pyproject.toml ] && \
  pip install -e . && pip install blocks-network --upgrade
cd ..

blocks dashboard

cd <your-agent-name> && blocks dashboard

Reads the dashboard URL from BLOCKS_APP_BASE_URL / BLOCKS_DASHBOARD_URL (or the active profile's dashboard origin) if set, otherwise from the active deployment — BLOCKS_BACKEND_URL, the active profile's backend, or the CDM config — so it opens the agent's page on the deployment you're targeting rather than always stock Blocks Network. When BLOCKS_BACKEND_URL points at a different backend than the active profile was logged into, the profile's cached dashboard origin is skipped so the link follows BLOCKS_BACKEND_URL. Override for staging / a worktree / a self-hosted deploy:

BLOCKS_APP_BASE_URL=https://staging.blocks.ai blocks dashboard

Agent Card Reference

The authoritative structure of agent-card.json is the [Agent Card Schema] (see Required Reading). This section gives field-level guidance; the schema is what blocks check and blocks publish enforce.

Recommended: runtime.maxRunningTimeSec

Strongly recommended: set runtime.maxRunningTimeSec in agent-card.json. It is not enforced -- blocks check passes without it and blocks init does not scaffold it -- but omitting it means the platform applies a default that is often wrong for the workload. This integer (seconds) declares the maximum wall-clock time a single task invocation may run before the platform considers it timed out. Choose a value appropriate for the workload:

• Simple request/response: 30-60
• LLM-backed or multi-step: 120-300
• Long-running pipe tasks: 600-3600

"runtime": {
  "handler": "./handler.ts",
  "concurrency": 5,
  "maxRunningTimeSec": 300
}

If omitted, the platform applies a default that may be too short or too long for the agent's use case.

Other useful fields

Beyond the required structure, populate these to improve discoverability, security, and operational behavior:

Populate tags[].examples whenever possible — they power the dashboard "Try it" UI and help consumers understand agent capabilities.

For full handler signatures, project structure, and trigger-script shape, see [Agent Card Reference] (external).

IO Schema Rules

Update agent-card.json io to match the handler's expected input and output shapes. Without a correct schema, the dashboard cannot render input forms.

Required fields:

Transport classes (determined by contentType):

Content truncated.