hurozo 0.4.0

Hurozo Agentic Platform CLI

Hurozo CLI

Hurozo is a visual agent builder and execution platform. You compose agents as graphs of nodes, connect inputs and outputs, and save them to run via API calls, webhooks, or the UI. The Hurozo CLI helps you:

• Scaffold runnable Python projects for your saved agents
• List available agents in your account
• Run agents programmatically using Python

The CLI is designed for quick prototyping and integration into scripts or services.

Features

• Scaffold a minimal Python project with main.py for selected agents
• Instantiate agents by name or by UUID directly
• Prefill input keys in the scaffolded script (when the agent defines required inputs)
• Lightweight Agent class for invoking agents via the Hurozo API

Installation

Install from PyPI:

pip install hurozo

This will provide the hurozo console command and the hurozo Python package.

Authentication

The CLI and the Agent class use a bearer token to access your Hurozo account.

• HUROZO_API_TOKEN: required. A user or org API token.

Example:

export HUROZO_API_TOKEN=...your token...

Commands

• hurozo init [dirname]

  • Interactively select one or more agents from your account
  • Scaffolds a minimal project in dirname (creates requirements.txt and main.py)
  • main.py instantiates each selected agent by display name and pre-fills .input({...}) if inputs are defined
  • When run, main.py will execute all selected agents and print their results

• hurozo list

  • Lists accessible agents with their display names and UUIDs

• hurozo help [command]

  • Shows help for a specific command

Python API

The packaged Python module also exposes a small API for running agents directly:

from hurozo import Agent

# Name-based: resolves display name → UUID at runtime
bruno = Agent("Bruno")
bruno.input({"naam": "De Hengst"})
print(bruno.run())

# UUID-based: skip resolution and use UUID directly
bruno = Agent("2375125b-1455-40fa-8458-d319cdef9b32d", True)
print(by_id.run())

Both styles call the Hurozo backend execute endpoint under the hood. Name-based resolution fetches your agent list and prefers exact (case-sensitive) name matches, falling back to case-insensitive.

Scaffolded Project Layout

When you run hurozo init my-agent, the CLI generates:

• requirements.txt – dependencies: hurozo, python-dotenv, requests
• main.py – a runnable script that:
  • imports Agent from hurozo
  • defines one variable per selected agent using its display name
  • fills in .input({...}) from the agent’s defined input keys (if available)
  • calls .run() for each agent and prints the results
• .env (optional) – if not present, a template is created with a HUROZO_API_TOKEN placeholder

Run it with:

cd my-agent
pip install -r requirements.txt
export HUROZO_API_TOKEN=...your token... (or set it in .env)
python main.py

Environment Variables

• HUROZO_API_TOKEN – required for both listing agents and executing them
• HUROZO_TOKEN – optional alias read by the RemoteAgent helper (falls back to HUROZO_API_TOKEN)
• HUROZO_API_URL / HUROZO_SERVER_URI – override the default backend host (https://hurozo.com)
• HUROZO_DEBUG – set to 1 to emit verbose RemoteAgent logs (registration attempts, Firebase token minting, Firestore events, etc.)
• NO_COLOR – if set, disables colored output in the CLI

Remote Agents

The packaged RemoteAgent helper now mirrors the Hurozo UI: it listens to Firestore for pending requests and writes results/events back in real time, no polling loop required.

from hurozo import RemoteAgent

def hello(name):
    return {"greeting": f"Hello {name}"}

RemoteAgent(hello, {
    "inputs": ["name"],
    "outputs": ["greeting"]
})

Requirements:

• Set HUROZO_API_TOKEN (or HUROZO_TOKEN) with a read/write API token.
• Optionally set HUROZO_API_URL if you are targeting a self-hosted deployment.

The helper:

1. Registers the remote agent metadata with /api/remote_agents/register (keeps it fresh).
2. Calls /api/firebase_token with your API token and exchanges the custom token for Firebase credentials.
3. Opens a Firestore gRPC watch on users/<uid>/remote_requests scoped to your agent.
4. Invokes your handler, patches the Firestore document with status/outputs (or error details), and emits execution events for the UI.

When HUROZO_DEBUG=1 is present, the helper prints each handshake step (registration, Firebase token mint, Firestore listen, request updates) so you can trace the realtime flow end‑to‑end.

Designing agents

• Go to https://hurozo.com/ to design your agents visually. Save your agent, create an API token, and scaffold a project with hurozo init.

Troubleshooting

• Missing token: ensure HUROZO_API_TOKEN is set in your shell or .env
• Name resolution fails: the CLI falls back to using the provided string; switch to UUID-based invocation by passing True as the second Agent argument
• Inputs missing at runtime: open the agent in the Hurozo UI and ensure inputs are defined; re-run hurozo init to regenerate a script with updated keys