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. Install agentserviceapi from PyPI and import agentsapi to match this documentation.

​
Prerequisites

  • Python 3.10+
  • An execution API API key
  • The client library: pip install agentserviceapi, then from agentsapi import ... (or editable from your monorepo)
  • Redis-backed SSE on the execution API side (required for interactive runs)

​
1. Clone and install

​
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:
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

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 agentsapi: 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:
Flags often include --tools, --validators, and -o combined.json. Register the printed JSON in your product UI or automation.