Three core developer journeys
Run curl, Python and TypeScript journeys with final evidence, saved receipts and safe recovery.
Building an application against a provisioned Q environment? Start with Build with Q; no repository or release tooling is needed. This page is the source-checkout tutorial for contributors and developers qualifying the synthetic examples.
This guide uses retrieval, a grounded answer with final citations, and an explicitly durable agent request with a saved receipt. Run the exact examples locally first. The synthetic sandbox tests HTTP integration only; switch to a provisioned environment for model generation and Temporal execution.
For a first HTTP request without SDK preparation, start with the curl-only guide. This page adds installed SDKs, durable agent receipts and recovery.
Prerequisites
- Python 3.11+, curl with
--fail-with-body, and Node 22 for TypeScript/React. - This checkout for the sandbox and examples.
- Prepared SDK 1.1.0 archives for Python/TypeScript/React. Publication is not assumed.
From a contributor environment built using TESTING.md, prepare archives and example dependencies:
.venv/bin/python -m scripts.release.sdk_packages --install
.venv/bin/python -m scripts.release.sdk_packages
.venv/bin/python -m scripts.developer.check --install
.venv/bin/python -m scripts.developer.check --prepare--prepare installs qualified local SDK archives and pinned dependencies into the example environments. It creates examples/python-quickstart/.venv, compiles the TypeScript example and builds the React browser assets. It does not modify a Q deployment. Python dependencies come from the pinned wheel cache; Node build dependencies use checked-in locks. For full release qualification run the contract check before building archives.
Start the local sandbox
In one terminal:
python3 examples/sandbox/server.pyIn a second terminal, from the repository root:
export Q_API_BASE_URL=http://127.0.0.1:8787/v1
export Q_API_KEY=q_local_sandboxThe server accepts only that fixed fixture token and binds 127.0.0.1. It ignores provider credentials and does not load .env. Every returned answer/run is synthetic. Its in-memory ledger disappears when the sandbox exits; keep the server running while testing journal reuse. Sandbox details.
Run the three journeys
Each command runs the same sequence and writes a separate local journal:
sh examples/curl-quickstart/run.sh
examples/python-quickstart/.venv/bin/python examples/python-quickstart/main.py
node examples/typescript-quickstart/dist/index.jsThe curl entry uses a Python standard-library orchestrator to construct JSON safely and retain receipts; requests themselves are made by curl. It requires no Python SDK. Service credentials are passed to curl over stdin, not command-line arguments.
Successful output is JSON containing search_results, answer, sources, citations, quality, agent_receipt, agent_status and temporal_workflow_id. The sandbox returns the synthetic answer Q fixtures test API integration [1]. and a synthetic-only-… workflow ID. That identifier deliberately does not claim real Temporal execution.
The request sequence is:
| Step | Request | Read |
|---|---|---|
| Retrieve | POST /v1/search with query, mode: web, max_results | results and their evidence URLs |
| Answer | POST /v1/answer with stream: false | Final answer, sources, citations, quality |
| Create agent | Keyed POST /v1/agents | Agent id |
| Start durable work | Keyed POST /v1/agents/{id}/runs, response_mode: receipt, durable_temporal: true | run_id, agent_id, stream_key |
| Poll | GET /v1/agents/{id}/runs/{run_id} | Status and workflow identity |
Agent runs enable explicit tool approval. These examples never approve an action automatically. If a real run waits for approval, inspect it using the approval contract; a polling timeout leaves the receipt available.
The examples use the non-streaming answer result to make final evidence explicit. For streaming, use version-1 answer events, which replace provisional text and evidence on completion. The React example exercises that path.
Durable agents and recovery
The default journal names are .q-curl-quickstart.json, .q-python-quickstart.json and .q-typescript-quickstart.json. Override with Q_QUICKSTART_STATE. They contain credential fingerprints, operation keys and receipts, never the credential itself. Treat run IDs and receipts as sensitive. Local lock directories prevent concurrent mutation starts; after a crashed example, confirm that its process has stopped before removing its .lock directory.
A rerun with the same journal reuses the agent and polls the original run without submitting another run. Search and answer calls still execute again and may incur cost on a real deployment. Polling is bounded to 30 seconds by default; set Q_QUICKSTART_POLL_SECONDS up to 120. Pending, failed, cancelled and uncertain results are explicit failures, not completed output.
A mutation records create_uncertain or start_uncertain before dispatch and clears it only after its receipt is saved. A crash or uncertain start retains the marker and stops subsequent automatic starts. Reconcile the saved keys and any returned receipt with the server/operator. Do not delete the journal or use a new key to work around uncertainty. Reusing a journal with a different credential/API root is rejected. Removing a completed journal deliberately creates a new agent/run on the next invocation.
Explicit Temporal dispatch now fails with durable_dispatch_unknown and a receipt if acceptance cannot be confirmed; it does not run inline. A workflow ID records requested dispatch, not proof of worker completion. The example also waits for a completed run. Q3.1 adds checkpoint recovery across API/worker restarts, persisted waits, cancellation and deadlines; see the durable run contract and rollout requirements.
Run the React starter
With the sandbox running and the same server-side environment variables:
cd examples/react-embed
npm startOpen http://127.0.0.1:8788. The browser uses a short-lived local application session; the Q credential remains in the Node process. The answer widget displays the final synthetic answer and citation after a revision. See proxy guarantees and production integration requirements.
Connect to a real environment
Use an operator-issued credential and that deployment's API root. Check /capabilities and /openapi.public.json, the ai:answer scope and agent_api availability. Explicit durable agents require a working Temporal service and worker. Model/provider credentials, billing, corpus permissions and outbound access are configured on Q, not in these clients.
Use a new journal path for a different environment; preserve existing journals for reconciliation. Actual retrieval and citations depend on the available corpus/providers. A q_test_ prefix alone does not guarantee isolated tenant data or free model calls. Browser deployments require real application authentication and per-user/tenant resource mapping.
Verify and troubleshoot
.venv/bin/python -m scripts.developer.checkThis creates fresh temporary Python/Node environments, installs the prepared archives, runs all three examples twice, validates their HTTP payloads against public OpenAPI, tests browser/proxy boundaries and records source hashes. The second run must not create another agent/run. No live providers are used.
The required CI job installs the pinned Chromium revision. If using make bootstrap-unit locally, install it with PLAYWRIGHT_BROWSERS_PATH="$PWD/.cache/q-test/browsers" .venv/bin/python -m playwright install chromium before this check. Linux may also need Playwright system libraries.
401: check the credential and selected environment. 403: inspect scope, entitlement and resource access. A missing module/archive means the preparation step has not completed. A retained uncertainty marker, pending agent, missing workflow identity or interrupted stream requires reconciliation, not a fresh mutation. The SDK support guide and release checks describe remaining deployment gates.