Blueprint for agents

Robot-team agent access.

Search capture-backed site worlds in agent language, quote hosted-session rentals, create dry-run orders and entitlement proof, open eligible hosted sessions, manipulate scenarios and start states, run headless rollouts, render explorer frames, and export dataset artifacts without a human click.

Public demo pathProtected robot-team flowDry-run commerceOpenAPI, CLI, MCP

Open contract Inspect public demo

Quickstart

Start with the public demo, then add scoped auth.

JSON is the default contract for the CLI and MCP tools. Human-readable output is opt-in so automation can parse every response predictably.

export BLUEPRINT_API_BASE_URL=https://tryblueprint.io
# Protected flows: set a Firebase robot-team or admin bearer token.
export BLUEPRINT_AGENT_AUTH_TOKEN=<firebase-id-token>
npx tsx scripts/agent-access/blueprint-agent-cli.ts discover
npx tsx scripts/agent-access/blueprint-agent-cli.ts catalog list --limit 3
npx tsx scripts/agent-access/blueprint-agent-cli.ts catalog search --q "whole foods" --limit 5
npx tsx scripts/agent-access/blueprint-agent-cli.ts commerce quote --site-world-id siteworld-f5fd54898cfb --product hosted-session-rental --session-hours 1
npx tsx scripts/agent-access/blueprint-agent-cli.ts commerce checkout --site-world-id siteworld-f5fd54898cfb --product hosted-session-rental --mode dry_run
npx tsx scripts/agent-access/blueprint-agent-cli.ts commerce entitlement <dry-entitlement-id>
npx tsx scripts/agent-access/blueprint-agent-cli.ts session create --site-world-id siteworld-f5fd54898cfb --entitlement-id <dry-entitlement-id> --order-id <dry-order-id> --commerce-mode dry_run --robot-profile-id other_sample --task-id sw-chi-01-task-1 --scenario-id sw-chi-01-scenario-1 --start-state-id sw-chi-01-start-1

Public demo commands omit the token when the demo site world is enabled. Dry-run checkout creates no live Stripe session or charge. Protected worlds keep Firebase, session ownership, and provisioned-entitlement checks in place.

Discover

Read /llms.txt, /api/site-content, search for store or warehouse language, and inspect the OpenAPI contract before loading a specific site-world id.

Quote

Ask for a site-world package or hosted-session rental quote. The quote is a planning artifact, not a live Stripe checkout.

Dry-run order

Create a dry-run order, receipt, and provisioned entitlement so an agent can prove the commerce link without charging a card.

Run

Create an entitlement-gated hosted session, reset to a known start state, step, batch, send controls, render explorer frames, and export artifacts.

Auth model

Public demo is narrow. Protected access stays gated.

Blueprint does not expose private supply or package access because an agent can send HTTP. Public demo sessions are sample/demo only. Protected robot-team flows require bearer auth that resolves through Firebase Admin and then require either session ownership, admin access, or a matching provisioned hosted-session entitlement.

Public demo

No privileged token, only demo-eligible site worlds.

Protected flow

Firebase robot-team or admin bearer token.

No bypass

Buyer type, entitlement proof, and launch readiness remain authoritative.

Rate limits

Inherits server API rate limiting and runtime blockers.

curl "$BLUEPRINT_API_BASE_URL/api/site-worlds?limit=3"
curl "$BLUEPRINT_API_BASE_URL/api/site-worlds/search?q=whole%20foods&limit=5"
curl "$BLUEPRINT_API_BASE_URL/api/site-worlds/search?q=warehouse%20tote&limit=5"

curl "$BLUEPRINT_API_BASE_URL/api/agent-access/commerce/quote?siteWorldId=siteworld-f5fd54898cfb&product=hosted_session_rental&sessionHours=1"

curl -X POST "$BLUEPRINT_API_BASE_URL/api/agent-access/commerce/dry-run-checkout" \
  -H "Content-Type: application/json" \
  --data '{"mode":"dry_run","siteWorldId":"siteworld-f5fd54898cfb","product":"hosted_session_rental","sessionHours":1}'

curl "$BLUEPRINT_API_BASE_URL/api/agent-access/commerce/entitlement-readiness?siteWorldId=siteworld-f5fd54898cfb&entitlementId=<dry-entitlement-id>"

curl -H "Authorization: Bearer $BLUEPRINT_AGENT_AUTH_TOKEN" \
  "$BLUEPRINT_API_BASE_URL/api/site-worlds/sessions/launch-readiness?siteWorldId=siteworld-f5fd54898cfb"

curl -X POST "$BLUEPRINT_API_BASE_URL/api/site-worlds/sessions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BLUEPRINT_AGENT_AUTH_TOKEN" \
  --data '{"siteWorldId":"siteworld-f5fd54898cfb","entitlementId":"<dry-entitlement-id>","orderId":"<dry-order-id>","commerceMode":"dry_run","sessionMode":"runtime_only","robotProfileId":"other_sample","taskId":"sw-chi-01-task-1","scenarioId":"sw-chi-01-scenario-1","startStateId":"sw-chi-01-start-1"}'

Truth labels

Agents should preserve evidence type in every downstream artifact.

A hosted rollout can be useful before it is operational proof. The label says what kind of evidence an agent is looking at.

capture_groundedRaw capture, timestamps, route context, device metadata, provenance, and approved package references.

provider_derivedWorld-model/runtime outputs produced from a provider or adapter path and tied back to the package.

generatedRollout frames, summaries, and artifacts created during the hosted session.

sample_demoPublic sample shape for integration work, not customer proof or deployment evidence.

request_gatedProtected package, rights, export, or hosted access still needs account/request review.

dry_run_orderA repo-safe test order, receipt, and entitlement proof that does not touch live Stripe or grant live package access.

protected_robot_teamProtected hosted-session operations require robot-team/admin auth plus session ownership or a matching provisioned entitlement.

MCP

Mirror the CLI as tools.

The MCP server is stdio-first for Codex and other local agent clients. Read-only tools can use public endpoints; session tools require public-demo eligibility or scoped bearer auth.

blueprint.catalog.searchblueprint.siteWorld.getblueprint.siteWorld.launchReadinessblueprint.commerce.quoteblueprint.commerce.checkoutDryRunblueprint.commerce.order.getblueprint.commerce.entitlement.getblueprint.session.createblueprint.session.controlblueprint.session.runBatch

{
  "mcpServers": {
    "blueprint": {
      "command": "npx",
      "args": ["tsx", "scripts/agent-access/blueprint-mcp-server.ts"],
      "env": {
        "BLUEPRINT_API_BASE_URL": "https://tryblueprint.io",
        "BLUEPRINT_AGENT_AUTH_TOKEN": "<firebase-id-token>"
      }
    }
  }
}

Request scope

Dry-run commerce proves the shape of quote, order, receipt, entitlement, and hosted-session rental access. Live Stripe payment, webhook fulfillment, package delivery, rights clearance, provider execution, and guaranteed hosted fulfillment remain request-scoped until the owning system supplies current proof.

Error semantics

Machines get blockers, not vague failure text.

400 bad_requestMissing ids, invalid JSON, unsupported option shape, or malformed command input.

401 unauthorizedProtected flow is missing a Firebase robot-team or admin bearer token.

403 forbiddenAuthenticated account is not a robot-team/admin profile, lacks a provisioned hosted-session entitlement, or does not own the session.

404 not_foundSite world, session, artifact, or explorer asset was not found.

409 blockedLaunch readiness, session mode, runtime handle, provider, or active operation blocks the request.

CLI

scripts/agent-access/blueprint-agent-cli.ts

OpenAPI

agent-access.openapi.json

Smoke

scripts/agent-access/headless-hosted-session-smoke.ts