Skip to content

Start here

Create your first agent

Read fields from a short order, then inspect the input, result and tokens in the dashboard.

1. Create an agent

Open the dashboard, choose your Space and create an agent. Name it Order reader, choose an available model and use these instructions:

Instructions
Read order details from the supplied text.
Use only stated facts. Do not invent missing values.

Copy the agent ID. The examples below use order-reader; replace it with the ID shown in your dashboard.

2. Connect from your backend

Open Connect on the agent. As an Owner, choose Create a key and copy it immediately; the full key stays visible only until you leave the agent page. Editors should ask an Owner for a key. Put it in your backend environment as NULLPROTOCOL_KEY.

Terminal · macOS / Linux
python -m pip install nullprotocol==0.5.0
export NULLPROTOCOL_KEY='your-space-sdk-key'

3. Run a request

Use Python 3.10 or newer. Save this as agent.py:

agent.py
from nullprotocol import NullProtocol

with NullProtocol() as client:
    agent = client.load("order-reader")
    result = agent.extract(
        "Order 42: two blue mugs.",
        {"orderId": "number", "quantity": "number", "item": "string"},
    )
    if not result.success:
        raise RuntimeError(result.error)
    print(result.data)
    print(result.usage)
    if result.history_error:
        print("History was not saved:", result.history_error)
Terminal
python agent.py

With a successful extraction, result.data contains the order ID, quantity and item. result.usage contains input and output tokens when the provider reports them. The same Space key authorizes the saved agent and its model; you do not need a separate provider key.

Keep the client available for your calls

Use it in an async application

async_agent.py
import asyncio
from nullprotocol import AsyncNullProtocol

async def main():
    async with AsyncNullProtocol() as client:
        agent = await client.load("order-reader")
        result = await agent.extract(
            "Order 42: two blue mugs.", {"orderId": "number"},
        )
        print(result.data if result.success else result.error)

asyncio.run(main())

Await methods that perform network I/O. register_action and with_scope are local and do not need await. Async handlers and guards are supported. Keep blocking work outside the async event loop.

4. Inspect it and change a rule

Open the agent’s History and refresh the list. Open the operation to see its input, output, model, instructions, included context and reported usage.

Edit the agent’s instructions or add a short rule under Context. Run the file again. The next operation uses the saved changes without changing your application code.