Guide for AI agents

Learn how an AI coding agent should read these docs, get a key, handle errors, and check its work.

Read the docs as text

• /llms.txt lists every page, with a one-line summary each.
• /llms-full.txt holds every page in one file.
• Any page is markdown when you add .md to its address, for example /docs/quickstart.md. Asking for text/markdown in the Accept header works too.
• In a terminal, yb docs lists the pages and yb docs <page> prints one, for example yb docs robot-contracts. No key is needed.
• /openapi.json describes every HTTP route.

Get a key

A person must do two things in the dashboard first:

1. Create an account. Verify its email before adding credit; the free sandbox doesn't need it. Accept the service terms too, if the dashboard asks.
2. Create an API key in the API keys tab.

Then give the agent the key as YB_API_KEY.

Note: Never put the key in code, in a command-line argument, in a committed file, or in a chat.

Start safely

• Start with transport-demo and max_spend_usd="0". It's a free sandbox, not a model: it returns placeholder actions, and it can't spend money.
• Write max_spend_usd as a string, such as "5", never as a float.
• On a real robot, open sessions with transport="owned", so a stalled network can't freeze the control loop.
• Open sessions with with client.session(...) as policy:, so they always close. An open session holds a place on the model, and its reserved credit, until it closes or times out.
• If your code may retry client.session(...) after a crash, pass the same idempotency_key each time. The same key never opens a second session.
• Never send generated test data to a real model: its answers would be meaningless. Use recorded data, or the robot itself.

Handle errors

Every error has a code, such as capacity. The Python SDK and yb also give a fix, a docs_url, and a retry value. Plain HTTP responses give only code and message, sometimes with a true or false retry; see HTTP API.

Use retry to decide what to do next:

For example:

from robot_inference_client import InferenceError, PlatformError

captured = policy.capture_time_ns()  # read when the cameras take the pictures
try:
    result = policy.infer(observation, captured_ns=captured)
except InferenceError as error:
    if error.retry != "next_request":
        raise  # the session ended; error.fix says what to do
    # the answer was late or replaced: skip it and send the next observation
except PlatformError as error:
    print(error.code, error.fix, error.docs_url)
    raise

yb errors <code> explains any code without going online. yb exits with status 75 for a temporary error, 1 for other errors, and 2 for a wrong command line.

Check the integration

1. yb models --ready lists the offered model. If it is on demand and idle, the session waits for startup; otherwise check that capacity is available. Listing alone does not start a model.
2. Each observation matches the model's format on Robot data formats: the exact names, uint8 images of shape (224, 224, 3), the right number of state values, and a prompt equal to the session's task.
3. captured_ns comes from policy.capture_time_ns(), read when the cameras take the pictures.
4. The loop treats errors with retry == "next_request" as skipped steps, not as crashes.
5. Every session closes on every path, including when an exception is raised.
6. After closing, policy.closure isn't None, policy.closure["close_confirmed"] is True, and policy.closure["charged_usd"] is what you expect.