AI Agent Reference

Compact reasoning layer for automated agents. The agent reads params, schemas, enums, and status codes directly from the OpenAPI spec; this section supplies only what the spec cannot express.

Operation intent

operation_id	Goal
`CalculateFees`	Compute an estimated title/registration fee breakdown from a full, state-discriminated transaction model (vehicle + optional trade-ins), optionally scoped by transaction type and on-behalf-of user.
`CalculateEstimateFees`	Compute the same fee breakdown from a lighter, state-discriminated estimate model.

Prerequisite / dependency tree

Valid OAuth token (scope oneapi:access)
└─ Known jurisdiction (state discriminator)
   └─ Correct state-specific request variant selected
      ├─ CalculateFees      → transaction variant + vehicle (+ optional tradeInVehicles)
      └─ CalculateEstimateFees → estimate variant

No prior resource creation. No inter-operation ordering. Calls are independent.

Per-operation reasoning contracts

OPERATION: CalculateFees
  AUTH:           REQUIRED — keycloak / scope oneapi:access
  PRECONDITIONS:  REQUIRED — valid token; state discriminator set to a supported jurisdiction;
                  body conforms to that state's transaction variant (additionalProperties:false)
                  OPTIONAL — transactionType query param; on-behalf-of user header (see spec)
  SIDE_EFFECTS:   NONE (read-only computation; no persisted state)
  SUCCESS_SIGNAL: 200 with fee-breakdown body populated (itemized fees + tax/price summary
                  fields per response schema). Presence of the fee array is the signal, not the
                  status code alone.
  ERRORS:         see Errors schema; handle by class (below)
  AGENT_NOTE:     Field validity is governed by the state variant. Do not send fields from a
                  different state's variant.

OPERATION: CalculateEstimateFees
  AUTH:           REQUIRED — keycloak / scope oneapi:access
  PRECONDITIONS:  REQUIRED — valid token; state discriminator set; body conforms to that state's
                  estimate variant (additionalProperties:false)
  SIDE_EFFECTS:   NONE (read-only computation)
  SUCCESS_SIGNAL: 200 with fee-breakdown body populated (same response shape as CalculateFees)
  ERRORS:         see Errors schema; handle by class (below)
  AGENT_NOTE:     Same response model as CalculateFees; response-handling logic is shared.

Safety classification

operation_id	Classification
`CalculateFees`	safe (read-only)
`CalculateEstimateFees`	safe (read-only)

No mutating or irreversible operations exist in this API.

Failure-handling rules

ON_FAILURE_AUTH (401):
  MEANING:  Token missing/expired/invalid.
  RETRY:    Yes, once, after acquiring a fresh token.
  BACKOFF:  Immediate single retry post-refresh.
  STOP:     If 401 persists after refresh → stop; credential/scope issue.

ON_FAILURE_AUTHORIZATION (403):
  MEANING:  Authenticated but lacks permission.
  RETRY:    No.
  STOP:     Immediately; escalate to Vitu access provisioning.

ON_FAILURE_VALIDATION (400):
  MEANING:  Body invalid for the selected state variant (bad/unknown/missing fields;
            additionalProperties violation; wrong discriminator).
  RETRY:    No (not without changing input).
  STOP:     Correct request per spec; re-issue as a new attempt.

ON_FAILURE_NOT_FOUND (404):
  MEANING:  Route/resource not found.
  RETRY:    No.
  STOP:     Verify base URL, environment segment, operation path.

ON_FAILURE_RATE_LIMIT (429):
  MEANING:  Rate limit exceeded (windowed).
  RETRY:    Yes.
  BACKOFF:  Exponential with jitter; wait for window reset.
  STOP:     After capped attempts → escalate.
  KNOWN_ISSUE: No retry-after/limit headers defined in spec; use blind backoff.

ON_FAILURE_SERVER (500):
  MEANING:  Server-side error, typically transient.
  RETRY:    Yes.
  BACKOFF:  Exponential with jitter.
  STOP:     After capped attempts → escalate.

Workflow recipes

RECIPE: Single fee estimate (estimate model)

1. Ensure valid token (scope oneapi:access); reuse cached token if unexpired.
2. Set state discriminator to target jurisdiction.
3. Build estimate variant body for that state (respect additionalProperties:false).
4. POST CalculateEstimateFees.
5. On 200: read fee array + tax/price summary. On failure: apply ON_FAILURE_* rules.

RECIPE: Fee estimate from full transaction

1. Ensure valid token.
2. Set state discriminator; build transaction variant with vehicle (+ optional tradeInVehicles).
3. Optionally set transactionType query param and/or on-behalf-of user header.
4. POST CalculateFees.
5. On 200: read fee breakdown. On failure: apply ON_FAILURE_* rules.

RECIPE: Scenario comparison

1. Ensure valid token (reuse across all calls).
2. For each scenario, vary only the relevant inputs (e.g., tradeIn values, saleType, lease terms).
3. Issue independent CalculateFees / CalculateEstimateFees calls (safe, idempotent, parallelizable
   - - subject to rate limits).
4. Compare fee-breakdown responses. No correlation IDs needed; calls are stateless.