1. Install

This tutorial uses the full zeroth-platform source tree. It installs the runtime and runs one model call; the lightweight remote SDK is a different package.

Install from source

uv sync --extra regulus

Run this from a checkout matching the documentation you are reading, with Python 3.12+ and uv installed. The current platform release is not yet on PyPI. Only the experimental remote client, zeroth-sdk==0.1.0a1, is available there; installing it does not install the graph runtime used by this tutorial.

Optional backends (Postgres, pgvector, Chroma, Elasticsearch, Redis, Regulus economics), the web console, and the LangGraph integrations are available through extras; see pyproject.toml for the full list. The regulus extra includes the bundled economic backend for the later service tutorial. You do not need the console to run the examples.

Set an API key

The hello example below makes one real LLM call through litellm using OpenAI (openai/gpt-4o-mini). Set your key:

export OPENAI_API_KEY=sk-...

Any litellm-supported provider works — edit the model= argument in the hello script to switch (e.g. anthropic/claude-sonnet-5 with ANTHROPIC_API_KEY).

Run the hello example

The canonical smoke test lives at examples/00_hello.py in the repository — the examples/ directory is not shipped inside the wheel, so run it from the source checkout used above. To seed a runnable demo service instead, see Local development.

It builds a one-node graph, wires a real AgentRunner through LiteLLMProviderAdapter, and runs it through the orchestrator. If this runs end-to-end your install is healthy.

examples/00_hello.py

"""00 — Hello, Zeroth: a single agent node, run through the real runtime.

What this shows
---------------
The smallest possible end-to-end invocation. One :class:`AgentNode`, one
real :class:`AgentRunner` backed by the real :class:`LiteLLMProviderAdapter`,
run through the real :class:`RuntimeOrchestrator`. No stubs, no hacks, no
``litellm.completion`` calls in user code — this file is what the library
wants you to write.

Requirements
------------
* ``OPENAI_API_KEY`` in the environment (uses ``openai/gpt-4o-mini``).
  Set ``ZEROTH_EXAMPLE_MODEL`` to override the model name.

Run
---
    uv run python examples/00_hello.py
"""

from __future__ import annotations

# Allow python examples/NN_name.py to find the sibling examples/_common.py helper.
import sys as _sys
from pathlib import Path as _Path

_sys.path.insert(0, str(_Path(__file__).resolve().parents[1]))

import asyncio
import os
import sys

from examples._common import (
    DEMO_GRAPH_ID,
    print_run_summary,
    require_env,
    running_service,
)
from examples._contracts import Answer, Question
from zeroth.contracts.graph import (
    AgentNode,
    AgentNodeData,
    DisplayMetadata,
    ExecutionSettings,
    Graph,
)
from zeroth.runtime.agents import (
    AgentConfig,
    AgentRunner,
    LiteLLMProviderAdapter,
)


def build_graph(model_name: str) -> Graph:
    """A one-node graph whose only step is a Q&A :class:`AgentNode`."""
    graph_version_ref = f"{DEMO_GRAPH_ID}@1"
    return Graph(
        graph_id=DEMO_GRAPH_ID,
        name="Hello, Zeroth",
        version=1,
        entry_step="qa",
        execution_settings=ExecutionSettings(max_total_steps=5),
        nodes=[
            AgentNode(
                node_id="qa",
                graph_version_ref=graph_version_ref,
                display=DisplayMetadata(title="Q&A"),
                input_contract_ref="contract://question",
                output_contract_ref="contract://answer",
                agent=AgentNodeData(
                    instruction=(
                        "You are a helpful assistant. Answer the user's question in one "
                        "short sentence. Return JSON matching the output schema."
                    ),
                    model_provider=model_name,
                    model_params={"temperature": 0.2, "max_tokens": 120},
                ),
            ),
        ],
        edges=[],
    )


async def main() -> int:
    if not require_env("OPENAI_API_KEY"):
        return 0

    model_name = os.environ.get("ZEROTH_EXAMPLE_MODEL", "openai/gpt-4o-mini")

    # Build one real AgentRunner for the one node in the graph. The
    # LiteLLMProviderAdapter reads OPENAI_API_KEY from the environment.
    runner = AgentRunner(
        AgentConfig(
            name="qa",
            description="Answers a user question in one sentence.",
            instruction="Answer the user in one short sentence.",
            model_name=model_name,
            input_model=Question,
            output_model=Answer,
        ),
        LiteLLMProviderAdapter(),
    )

    async with running_service(
        build_graph(model_name),
        contracts={
            "contract://question": Question,
            "contract://answer": Answer,
        },
        agent_runners={"qa": runner},
    ) as demo:
        run = await demo.service.orchestrator.run_graph(
            demo.service.graph,
            {"question": "What is Zeroth in one sentence?"},
            deployment_ref=demo.deployment_ref,
        )
        print_run_summary(run, label="hello")
    return 0


if __name__ == "__main__":
    sys.exit(asyncio.run(main()))

Run it:

uv run python examples/00_hello.py

Expected output: a single short greeting sentence from the LLM.

If OPENAI_API_KEY is unset the script prints a SKIP notice to stderr and exits 0 — that same behaviour keeps CI green on forked pull requests that do not have secrets configured.

Next

→ Section 2: First graph with an agent, a tool, and an LLM call