Example: Call an Agent Like a Typed Function

This example triages support tickets from a backend job. Each ticket becomes an application request with a typed result contract:

• Validated results: the platform checks the agent's answer against the schema before the job can read it.
• Safe retries: resubmitting the same Idempotency-Key returns the original acceptance, not new work.
• Crash-safe batches: a local ledger records the key before submitting, so a run that dies mid-batch is recovered by running it again.

Everything is Python 3.12+ and the standard library. Download the files into one directory. In a repository checkout, they live under docs/static/examples/typed-agent-calls/.

• README.md: the full walkthrough and sample output.
• agent_function.py: a copyable submit / wait / result helper.
• triage.py: the batch CLI with its SQLite ledger and a --crash-after switch.
• triage.schema.json: the application-result-v1 contract.
• tickets.jsonl: five sample tickets.

Run it

This requires API_APPLICATION_REQUESTS_ENABLED and API_STRUCTURED_RESULTS_ENABLED on the deployment. Both default off.

export DT_API_BASE="https://your-deployment.example/api/v1"
read -r -s -p "API key: " DT_API_KEY; export DT_API_KEY
python3 triage.py create-agent
export DT_AGENT_ID=...               # printed above
python3 triage.py run --crash-after 3
python3 triage.py run                # T-1003 replays its original acceptance; all five validate
python3 triage.py show T-1004

What the example relies on

• Acceptance: 202 acceptance proves durable local acceptance only. The example stores request_id because replay receipts expire (24 hours by default).
• Waiting: revision waits return when the request changes, hold at most 30 seconds, and never cancel work. Capacity limits return 429 with Retry-After.
• Settlement: the example settles on result.state (validated, validation_failed, generation_failed, no_result, purged). It stops early when execution_state is awaiting_action or the request is blocked. Chat replies are not a substitute for the typed result.
• Reading the value: GET …/result/ returns native JSON. A validated null has has_value: true.
• Validation: a validated result proves shape, not that any external action succeeded.
• Rejected inputs: unsupported schema keywords return 400 unsupported_schema. Reusing a key with a changed body returns 409.