Skip to main content
This tutorial follows the companion PDF demo application: a minimal chat UI that runs parse_pdf locally while the workflow executes over a streaming connection (no webhooks in the demo path). See Getting started for the minimal API flow first. Replace package install lines with asapi to match this documentation.

​
Prerequisites

  • Python 3.10+
  • An execution API API key
  • The asapi package (install from PyPI, or editable from your monorepo)
  • Redis-backed SSE on the execution API side (required for interactive runs)

​
1. Clone and install

git clone <your-demo-repo-url>
cd <demo-repo>
python -m venv .venv
source .venv/bin/activate
pip install -e .
pip install asapi

​
2. Environment

Copy .env.example to .env and set at least your API key and base URL. Names vary by demo; common variables are listed in Environment.

​
3. One-time agent upload

The demo ships an orchestration JSON (for example example_agent.json). Upload it once so every developer shares the same graph: 
sudoiq-demo-upload example_agent.json
Equivalent: python -m scripts.upload_orchestration example_agent.json. The command writes an agent id file (for example .agent_id) consumed by the app.

​
4. Run the server

uvicorn app.main:app --reload --host 0.0.0.0 --port 8080
Open http://localhost:8080, send a message, and attach a PDF when the workflow should call parse_pdf.

​
5. Request path (conceptual)

  1. The browser posts chat input (and optional upload) to your FastAPI app.
  2. The app builds local tool handlers (for example build_local_tool_handlers mapping parse_pdf to an async function).
  3. It calls client.set_tools(...) then run_agent (or execute_agent and awaits the handle).
  4. SSE delivers pauses for tools; the handler runs parse_pdf on the server using the uploaded file and returns JSON text.
  5. The final AgentGraphRunStatusResponse is reduced to assistant text for the UI.
Inspect the demo source for exact module names after you align imports with asapi: typically app/interactive_run.py, tools/parse_pdf.py, and app/main.py.

​
6. Dump tool and validator JSON (optional)

If your tenant is missing parse_pdf or an invoice validator referenced by the graph, some demos ship a CLI to print registration payloads: 
sudoiq-demo-dump
# or: python -m app.dump_schemas
Flags often include --tools, --validators, and -o combined.json. Register the printed JSON in your product UI or automation.