Why YAAgents

Most “AI agent” integrations today expose a single /agents/invoke endpoint that accepts freeform JSON and returns freeform JSON. That works for demos — it breaks down the moment you need governance, observability, or multi-framework interoperability.

YAAgents is a thin, normative REST profile that closes the gap with three properties:

1. Domain resources, not `/agents/invoke`

Agentic operations are expressed as ordinary REST resource actions:

POST /campaigns/{id}/optimizations
POST /contracts/{id}/reviews
POST /inventory/{id}/reorder-suggestions

Standard HTTP semantics apply: POST creates a resource, GET retrieves it, DELETE cancels it. Clients, gateways, load balancers, and API management tools treat agentic endpoints exactly like any other REST endpoint — no special-casing required.

2. Typed responses for every agentic outcome

The Profile defines 10 normative response types — each with a fixed HTTP status, Content-Type header, and JSON body shape:

Type	Status	When
`success`	200	Operation completed; result in body
`created`	201	Resource created; result in body
`accepted`	202	Async operation queued
`clarification_required`	400	Agent needs more input before proceeding
`validation_failed`	422	Inputs are structurally invalid
`approval_required`	412	Human-in-the-loop approval required
`forbidden`	403	Authorization or policy failure
`conflict`	409	Conflicting state prevents the operation
`failed_dependency`	424	Dependent tool or service failure
`error`	500	Unhandled failure

Every response carries a discriminator field (type) so clients can switch cleanly — no guessing at status-code ranges or parsing error strings.

3. Gateway-controlled access + framework-neutral runtime

The YAAgents gateway enforces governance at the edge via a plugin chain:

token-validator — validates bearer tokens; rejects unauthenticated requests before they reach any agent code.
tenant-injector — extracts and propagates X-Tenant-ID; scopes every agentic operation to the correct tenant context automatically.
license-check — verifies feature entitlements per tenant; returns policy_violation (403) for unlicensed operations at the gateway — agent code never runs.

Because governance is a gateway concern, any agent framework runs behind it: LangChain, LlamaIndex, custom Python, Go, Node — all serve the same Profile-compliant responses through the same gateway plugin chain.