AI Agent Reference

Compact reasoning layer for automated agents. The agent reads params, schemas, types, and status codes directly from the spec; the material below supplies intent, ordering, side effects, and safety that the spec does not encode.

Operation intent table

operation_id	Goal
`CreateTransaction`	Submit a new MD title/registration transaction for asynchronous DMV processing.
`UpdateTransaction`	Amend an existing transaction, addressed by `transactionId` or `refNumber`.

Prerequisite / dependency tree

OAuth token (scope oneapi:access)
- CreateTransaction  (no prior resource required)
  - produces a transaction (identified by refNumber / transactionId)
    - UpdateTransaction  (requires an existing transaction id/refNumber)

Callback delivery (onStatusChange)
- requires callbackUrl supplied at Create/Update time
  - requires a network-accessible HTTPS endpoint

Per-operation reasoning contracts

OPERATION: CreateTransaction
AUTH: oneapi:access (keycloak client-credentials)          [REQUIRED]
PRECONDITIONS:
  - Valid access token                                     [REQUIRED]
  - MDEVRTransactionDTO body conforming to spec            [REQUIRED]
  - Client-generated refNumber for correlation             [OPTIONAL, RECOMMENDED]
  - callbackUrl (HTTPS, network-accessible)                [OPTIONAL, RECOMMENDED]
  - transactionType query param                            [OPTIONAL]
SIDE_EFFECTS:
  - Creates a new transaction in the Vitu system           [REQUIRED]
  - Initiates asynchronous DMV processing
  - No idempotency key defined: repeat calls may duplicate
SUCCESS_SIGNAL:
  - Acceptance = request accepted for async processing (NOT completion)
  - True outcome arrives via onStatusChange callback; inspect
    callbackType and status/universalStatus fields, not the HTTP code
AGENT_NOTE: There is no read/list operation. Do not attempt to poll for status.

OPERATION: UpdateTransaction
AUTH: oneapi:access (keycloak client-credentials)          [REQUIRED]
PRECONDITIONS:
  - Valid access token                                     [REQUIRED]
  - An existing transaction                                [REQUIRED]
  - transactionId OR refNumber path value                  [REQUIRED]
  - Revised MDEVRTransactionDTO body                        [REQUIRED]
  - callbackUrl                                            [OPTIONAL, RECOMMENDED]
SIDE_EFFECTS:
  - Modifies an existing transaction                        [REQUIRED]
  - Re-triggers asynchronous processing
  - Replace-vs-merge semantics UNCONFIRMED (assume replace)
SUCCESS_SIGNAL:
  - Acceptance = accepted for async processing
  - Confirm effect via subsequent onStatusChange callback

Safety classification table

operation_id	Classification	Rationale
`CreateTransaction`	mutating	Creates a new transaction; may trigger a DMV filing. Not idempotent — potentially effectively irreversible once filed.
`UpdateTransaction`	mutating	Alters an existing transaction and re-triggers processing.

No read-only (safe) operations exist in this spec. Agents cannot verify state by query; rely on callbacks.

Failure-handling rules

ON_FAILURE_AUTH  (401)
  MEANING: Missing/expired/invalid token.
  RETRY: Yes, once, after obtaining a fresh token.
  BACKOFF: None on first retry.
  STOP: If a freshly issued token still fails — escalate; do not loop.

ON_FAILURE_FORBIDDEN  (403)
  MEANING: Authenticated but not authorized for the operation.
  RETRY: No — token refresh will not help.
  STOP: Immediately; escalate to support.

ON_FAILURE_VALIDATION  (400)
  MEANING: Malformed/invalid payload; see the Errors schema for detail.
  RETRY: No — not until the payload is corrected.
  STOP: Surface the Errors content; require input change before resubmit.

ON_FAILURE_NOT_FOUND  (404)
  MEANING: Target transaction (id/refNumber) does not exist.
  RETRY: No — verify the identifier first.
  STOP: On repeat; the resource reference is wrong.

ON_FAILURE_RATE_LIMIT  (429)
  MEANING: Throttled.
  RETRY: Yes.
  BACKOFF: Honor Retry-After / RateLimit-Reset; then exponential backoff + jitter.
  STOP: After a bounded number of attempts or persistent limiting.

ON_FAILURE_SERVER  (5xx)
  MEANING: Server-side error.
  RETRY: Yes, but cautiously — CreateTransaction is not idempotent.
  BACKOFF: Exponential + jitter.
  STOP: After bounded attempts. For CreateTransaction, reconcile via callback
        before retrying to avoid duplicate transactions.

Workflow recipes

RECIPE: File a new transaction

1. Obtain token (client-credentials, scope oneapi:access).
2. Generate and store a refNumber.
3. CreateTransaction(body=MDEVRTransactionDTO, callbackUrl, transactionType?).
4. Store returned/assigned transactionId once known.
5. On onStatusChange callback: verify HMAC (if configured),
   - - branch on callbackType, record status + universalStatus.
6. Match callback to request via refNumber.

RECIPE: Amend a transaction

1. Obtain token.
2. UpdateTransaction(path=transactionId|refNumber, body=revised DTO, callbackUrl).
3. Await onStatusChange callback confirming the amended state.
NOTE: Treat as full replacement until merge semantics are confirmed.

RECIPE: Interpret an outcome

1. Receive onStatusChange callback.
2. Read callbackType discriminator -> select subtype.
3. SUCCESS-type: read status/universalStatus, shipment/indicia, controlNumber.
4. FAILURE-type: read errors[] and act on validation issues.
5. INVOICED-type: read per-transaction fees.
DO NOT infer success from the submission HTTP code alone.