Worked examples¶
Server: aetelier-mcp · Form: natural-language ask → tool sequence → results
Each flow is a full engagement: what you ask the client, the tools it drives to satisfy the ask, and the results it reads back between steps. You speak in natural language; the client picks the tools and chains them, reading each result before the next and adapting as it goes. Results are illustrative and abridged — live values vary.
Health first, cleanup last
A robust flow opens with platform_health and, for a deploy, closes with
stop_collector. The flows below assume a reachable platform.
Errors are results, not failures
A backend error comes back as {"ok": false, "error": "..."}, with code and
docs_url when the backend sent them — an ordinary tool result the client reads
and adapts to in the same loop. Flow 2 shows this: a non-converged fit returns a
400 and becomes a looser-tolerance refit.
Flow 1 — Deploy a collector and confirm data is landing¶
Ask — "Stand up a Binance BTC spot collector in a low-latency region and tell me once it's actually producing data."
This is a remote bring-your-own deploy: deploy_collector registers the service and
mints an agent JWT, and you run your own agent against the gateway with that JWT.
The client drives:
platform_health → list_cex_options → query_colocation → deploy_collector → collector_health → stop_collector
Step 1 — confirm the platform answers
Step 2 — resolve the venue and its native symbol format
The client consults the deployable options before it commits to a symbol string, since each venue names symbols differently.
{
"venues": [
{
"exchange": "binance",
"label": "Binance",
"symbol_format": "concatenated uppercase",
"symbol_example": "BTCUSDT",
"market_types": ["spot"],
"orderbook_depths": [5, 10, 20, 50, 100, 500, 1000],
"default_orderbook_depth": 50,
"datatypes": [
{ "name": "orderbook", "available": true },
{ "name": "trades", "available": true }
]
}
]
}
Binance names BTC spot as BTCUSDT, supports spot, and offers depth 50.
Step 3 — pick the region
{
"count": 1,
"exchanges": [
{ "exchange": "binance", "region": "ap-northeast-1", "score": 0.96 }
]
}
Step 4 — register the remote collector
{
"tool": "deploy_collector",
"arguments": {
"exchange": "binance",
"symbols": ["BTCUSDT"],
"market_type": "spot",
"region": "ap-northeast-1"
}
}
{
"service_id": "63060972-4c1e-4b8a-9f2d-7a5e0c3b1d84",
"binding_id": "cfb7688a-2d3f-4e91-8b6c-15a9e4f07d23",
"gateway_url": "https://gateway.aetelier.xyz",
"token": "your-agent-jwt"
}
The deploy returns the service_id, the binding_id, the gateway URL, and an agent
JWT. Nothing is running yet: this is a bring-your-own collector, so you launch the
agent yourself, pointing it at the returned gateway URL and passing the JWT.
Step 5 — run your own agent against the gateway
Set AETELIER_GATEWAY_URL to the deploy's gateway_url and AETELIER_TOKEN to its
token. The agent reads the binding and service ids from the JWT's claims, so
neither is a separate variable. The webapp's fleet view shows this command for the
binding, with a freshly minted token:
docker run -d --pull always --restart unless-stopped --name aetelier-agent-binance-orderbook-cfb7 \
-v "$HOME/aetelier-data:/home/agent" \
-e AETELIER_GATEWAY_URL="https://gateway.aetelier.xyz" \
-e AETELIER_TOKEN=your-agent-jwt \
-e RUST_LOG=info \
ghcr.io/aetelierxyz/aetelier-agent:latest
The full variable contract is in
aetelier-agent → Environment variables.
The JWT is a credential scoped to this binding. Treat it like a password: keep it out of shared configs and version control.
Step 6 — confirm data is landing
A fresh deploy has no lake rows for the first few minutes, so collector_health
leads with liveness and reads starting rather than reporting a failure.
Just after the agent starts:
{ "tool": "collector_health", "arguments": { "service_id": "63060972-4c1e-4b8a-9f2d-7a5e0c3b1d84" } }
{
"service_id": "63060972-4c1e-4b8a-9f2d-7a5e0c3b1d84",
"verdict": "starting",
"liveness": { "connected": true, "heartbeat_age_s": 4, "ws_latency_ms": null },
"landing": { "rows_last_5m": 0, "total_rows": 0,
"expected_first_data_by": "2026-07-04T18:05:00Z" }
}
A few minutes later, once rows land:
{ "tool": "collector_health", "arguments": { "service_id": "63060972-4c1e-4b8a-9f2d-7a5e0c3b1d84" } }
{
"service_id": "63060972-4c1e-4b8a-9f2d-7a5e0c3b1d84",
"verdict": "healthy",
"liveness": { "connected": true, "heartbeat_age_s": 3, "ws_latency_ms": null },
"landing": { "rows_last_5m": 8421, "total_rows": 33110, "last_row_age_s": 2 }
}
The verdict flips to healthy once fresh rows land, and the client tells you data is
flowing.
Step 7 — tear it down
{
"agent_id": "5b0e2c71-9a44-4f3e-8d16-c2a7f90b3e58",
"binding_id": "cfb7688a-2d3f-4e91-8b6c-15a9e4f07d23",
"session_id": "e41d9a03-6c2b-4f87-a5e9-0b3c7d18f246",
"command_id": "9d7f3b2e-1a65-4c08-b4f3-6e2a8c05d917"
}
The stop is accepted at once and returns the release command. The service reads
stopping until the agent acknowledges the release, then stopped.
Stop the collector when you are done to release the binding; a running collector
draws data units once per UTC day. Between deploy and stop
you can pause and resume the task with collector_command (task_pause,
task_resume).
Flow 2 — Fit and forecast a model¶
Ask — "Fit a Hawkes model to Kraken ETH trades and forecast the next 10 events."
This flow adapts mid-loop: the first fit does not converge at the default tolerance, so the client reads the error and refits with a looser one. The client drives:
list_datasets → fit_pricing → fit_hawkes → get_fit → forecast_fit
Step 1 — pick a dataset
Hawkes fits want an event stream, so the client picks a trades dataset.
fit_recommended marks a trades set in the size band a fit converges on well.
[
{ "dataset_id": "9f3a61c2d40b7e85", "venue": "kraken", "symbol": "ETH-USD",
"data_type": "trades", "n_events": 702, "fit_recommended": true }
]
Step 2 — check the fit price
A fit draws compute units, and only when it converges. The client reads the price and reports it before it runs one.
hawkes_fit_cost is the price in compute units, the catalog's
action_rates.hawkes_fit_compute. The balance is checked against it before the fit
starts; if it is short, fit_hawkes returns a 402 and runs nothing. See
Units and the 402 error.
Step 3 — first fit (does not converge)
{
"ok": false,
"error": "<service> 400: validation error: estimation did not produce a usable result: Not converged after 50000 iterations (gradient norm = 3.418207e4)"
}
The 400 is an ordinary result, and nothing was charged. Not converged after is
the signal to raise tolerance above the server default of 50. A 402 is a
different case: no tolerance clears it, so the client stops and reports it
(Reading a 402).
Step 4 — refit with a looser tolerance
{
"fit_id": "7c21e0a4-5b8f-4d0e-9a63-2f1c8b7d4e10",
"config": { "tolerance": 500, "max_iter": 50000, "train_ratio": 0.8 },
"parameters": { "mu": 0.00017, "alpha": 0.0042, "beta": 0.0231 },
"diagnostics": { "converged": true, "branching_ratio": 0.182, "iterations": 1843 },
"baseline": { "lr_reject_h0": true },
"data": { "n_events_train": 561 }
}
The refit converged, so it draws the fit price. baseline.lr_reject_h0 is true:
the likelihood-ratio test rejects a plain Poisson model, and a branching ratio of
0.182 says the series is mildly self-exciting. If it still had not converged, the
client would raise tolerance again.
Step 5 — read the full fit
fit_hawkes omits the chart series to keep the result small. The client fetches the
full artifact — parameters, diagnostics, and series — with get_fit.
{
"fit_id": "7c21e0a4-5b8f-4d0e-9a63-2f1c8b7d4e10",
"diagnostics": { "converged": true, "branching_ratio": 0.182 },
"series": { "intensity": [ ], "residual_ecdf": [ ], "residual_qq": [ ] }
}
Step 6 — forecast from the fit
{
"tool": "forecast_fit",
"arguments": { "fit_id": "7c21e0a4-5b8f-4d0e-9a63-2f1c8b7d4e10", "n_forecast": 10 }
}
{
"fit_id": "7c21e0a4-5b8f-4d0e-9a63-2f1c8b7d4e10",
"seed": 42,
"mc_paths": 500,
"deterministic": false,
"n_forecast": 10,
"points": [
{ "index": 0, "gap_ms": 3920, "gap_p25_ms": 1180, "gap_p75_ms": 6710 },
{ "index": 9, "gap_ms": 48183, "gap_p25_ms": 37950, "gap_p75_ms": 59420 }
]
}
Each point's gap_ms is the median cumulative gap since the end of the training
data, with gap_p25_ms and gap_p75_ms as the band; the reply above shows the first
and last of the 10 points. The client reports the 10th event near 48 seconds out.
The same seed gives the same forecast; raise mc_paths to cut Monte-Carlo noise in
the band.
Flow 3 — Audit an existing stream¶
Ask — "How complete is the Coinbase BTC/USDT order book?"
A short two-step read: the client resolves the stream in the governance catalog, then scores it. Governance reads draw no units. The client drives:
governance_catalog → stream_scorecard
Step 1 — find the stream
[
{ "exchange": "coinbase", "market_type": "spot", "symbol": "BTC/USDT",
"datatype": "orderbook", "presence": "present" }
]
Step 2 — score it
{
"tool": "stream_scorecard",
"arguments": {
"exchange": "coinbase", "market_type": "spot",
"symbol": "BTC/USDT", "datatype": "orderbook"
}
}
{
"stream": { "exchange": "coinbase", "market_type": "spot",
"symbol": "BTC/USDT", "datatype": "orderbook" },
"completeness": { "status": "critical", "completeness_pct": 0.049 },
"quality": { "exception_count": 0, "max_severity": "none", "checks": [] }
}
Completeness is critical (completeness_pct is a 0–1 ratio, so 4.9%) while quality
shows no exceptions — the stream is sparse, not corrupt. Add window_secs to
recompute completeness live over a trailing window.
Compose the whole engagement¶
Ask — "Stand up a Binance BTC collector in a low-latency region, confirm it's landing data, audit an established stream, fit a Hawkes model to a trades dataset, forecast from it, then tear the collector down."
A capable client chains the flows above into one engagement, reading each result before the next and adapting as it goes:
flowchart LR
H[platform_health] --> L[list_cex_options]
L --> Q[query_colocation]
Q --> D[deploy_collector]
D --> CH[collector_health]
CH --> G[stream_scorecard]
G --> F[fit_hawkes]
F --> FC[forecast_fit]
FC --> S[stop_collector]
Each arrow is a tool call whose result the client reads before the next, adapting as
it goes — a looser tolerance on a non-converged fit, starting versus healthy on a
fresh deploy.