Examples
Pick your starter
Each example is a complete, runnable service. Choose the domain closest to your use case,
then run docker compose up inside the example directory — the compose file starts both
the gateway and the service automatically.
| Example | Purpose | Port | Main endpoint | Required headers | Success status |
|---|---|---|---|---|---|
examples/store/ — full | E-commerce product recommendations (Python) | 8120 | POST /products/{id}/recommendations | Authorization · X-Tenant-ID | 200 |
examples/store-go/ — full | E-commerce product recommendations (Go) | 8120 | POST /products/{id}/recommendations | Authorization · X-Tenant-ID | 200 |
examples/campaign-api/ — full | Campaign optimization (Python) | 8120 | POST /campaigns/{id}/optimizations | Authorization · X-Tenant-ID | 200 |
examples/campaign-api-go/ — full | Campaign optimization (Go) | 8120 | POST /campaigns/{id}/optimizations | Authorization · X-Tenant-ID | 200 |
examples/customer-support-triage/ — skeleton | Triage support tickets; clarification flow | 8120 | POST /tickets/{id}:triage | Authorization · X-Tenant-ID | 201 |
examples/financial-risk-screening/ — skeleton | Screen financial claims; approval flow | 8120 | POST /claims/{id}/risk-screens | Authorization · X-Tenant-ID · X-License-Tier | 201 |
examples/agent-graph-ecom/ — multi-service | 2-service inter-agent: recommendations + inventory | 8124 | POST /products/{id}/recommendations | Authorization · X-Tenant-ID | 200 |
examples/llm-gateway/ | SSE streaming + per-tenant concurrency | 8122 | POST /completions | Authorization · X-Tenant-ID | 200 |
All single-service examples run the YAAgents Gateway on port 8120; it handles auth, tenant context, and audit before forwarding to the service. The
agent-graph-ecomexample uses two gateway instances (gateway-A on 8124 for end-user requests, gateway-B on 8126 for service-to-service calls).
By agentic response type
E-commerce recommendations (store/, store-go/) — demonstrates clarification_required
(400): when a customer has no purchase history, the service asks the client for anchor items
rather than returning empty results.
Campaign optimization (campaign-api/, campaign-api-go/) — demonstrates
success (200) for optimization results and clarification_required (400) when the
budget delta is ambiguous.
Customer support triage (customer-support-triage/ · skeleton) — demonstrates
clarification_required (400) for missing context: when severity or SLA tier is absent
from the request, the service returns a structured clarification request rather than guessing.
Financial risk screening (financial-risk-screening/ · skeleton) — demonstrates
approval_required (412): when a claim exceeds the auto-approve threshold, the service
returns a structured approval request instead of making the decision unilaterally.
Inter-agent recommendation graph (agent-graph-ecom/ · multi-service) — demonstrates
outcome propagation across two services: when the inventory service returns
clarification_required or failed_dependency, the recommendation service forwards the
structured outcome faithfully rather than converting it to a generic error.
Multi-service example
examples/agent-graph-ecom/ shows two YAAgents-governed services calling each other through
a second gateway instance. The recommendation service mints a service-account token and
forwards X-Tenant-ID and Idempotency-Key to the inventory service via gateway-B.
client → gateway-A:8124 → recommendation-agent:8125 │ service-account token ▼ gateway-B:8126 → inventory-agent:8127See inter-agent calls for the routing pattern, token-forwarding contract, and outcome propagation rules.