AI Agent Reference

Compact reasoning layer for automated agents. The agent reads params, schemas, types, and status codes directly from the OpenAPI spec; this section supplies only intent, ordering, prerequisites, side effects, safety, and workflows.

Operation intent

operation_id	Goal
`CreateTransaction`	Submit a new CO title/registration transaction for async processing.
`UpdateTransaction`	Resubmit/revise an existing transaction (full representation).
`CancelTransaction`	Withdraw/cancel an existing transaction.
`GetTransactionFees`	Read platform-calculated fees for a transaction.

Prerequisite / dependency tree

OAuth token (scope oneapi:access)
- CreateTransaction
  - produces transactionId (system) ; refNumber (client-supplied) addresses same txn
  - UpdateTransaction      (requires existing transaction)
  - CancelTransaction      (requires existing, non-terminal transaction)
  - GetTransactionFees     (requires existing transaction AND completed fee calc)
Callback endpoint (callbackUrl)  — OPTIONAL, enables outcome delivery for the 3 mutating ops

Per-operation reasoning contracts

OPERATION: CreateTransaction
  AUTH:           REQUIRED — oneapi:access (keycloak client-credentials)
  PRECONDITIONS:  REQUIRED — valid COEVRTransactionDTO body
                  OPTIONAL — callbackUrl (to receive outcome)
                  OPTIONAL — transactionType (see KNOWN_ISSUE)
  SIDE_EFFECTS:   Creates a transaction; initiates async DMV processing.
  SUCCESS_SIGNAL: HTTP 202 = accepted only. TRUE success = later
                  SUCCESS callback (SuccessCallbackDTO) with success status
                  in status/universalStatus. NOT the 202 itself.

OPERATION: UpdateTransaction
  AUTH:           REQUIRED — oneapi:access
  PRECONDITIONS:  REQUIRED — existing transaction (transactionId OR refNumber)
                  REQUIRED — full COEVRTransactionDTO body
                  OPTIONAL — callbackUrl
  SIDE_EFFECTS:   Replaces/revises stored transaction; re-triggers async processing.
  SUCCESS_SIGNAL: HTTP 202 = accepted. TRUE outcome via subsequent callback.
  AGENT_NOTE:     Assume FULL REPLACEMENT, not merge — send complete body.
                  Merge-vs-replace not specified in spec.

OPERATION: CancelTransaction
  AUTH:           REQUIRED — oneapi:access
  PRECONDITIONS:  REQUIRED — existing, non-terminal transaction (id OR refNumber)
                  OPTIONAL — message (cancellation reason)
  SIDE_EFFECTS:   Cancels the transaction; async.
  SUCCESS_SIGNAL: HTTP 202 = accepted. Confirm terminal state via callback/status.
  AGENT_NOTE:     Treat as effectively irreversible from the agent's view
                  (no un-cancel operation exists).

OPERATION: GetTransactionFees
  AUTH:           REQUIRED — oneapi:access
  PRECONDITIONS:  REQUIRED — existing transaction (id OR refNumber)
                  REQUIRED — fee calculation completed (timing-dependent)
  SIDE_EFFECTS:   None (read-only).
  SUCCESS_SIGNAL: HTTP 200 with FeeDTO array. Empty/absent may mean
                  fees not yet calculated, not an error.

Safety classification

operation_id	Class
`GetTransactionFees`	safe (read-only)
`CreateTransaction`	mutating
`UpdateTransaction`	mutating
`CancelTransaction`	irreversible (no reverse operation defined)

Failure-handling rules

ON_FAILURE_AUTH        (401)
  MEANS:   token missing/expired/invalid
  RETRY:   yes — re-obtain token, retry ONCE
  BACKOFF: none for the single retry
  STOP:    persistent 401 after fresh token → credential/scope fault; stop

ON_FAILURE_FORBIDDEN   (403)
  MEANS:   authenticated but not entitled
  RETRY:   no
  STOP:    immediately; escalate to owner

ON_FAILURE_VALIDATION  (400)  [Errors schema]
  MEANS:   invalid/malformed request
  RETRY:   no (not without changing the request)
  STOP:    correct per Error messages, then resubmit as new attempt

ON_FAILURE_NOT_FOUND   (404)  [Errors schema]
  MEANS:   transaction/resource id not found
  RETRY:   no
  STOP:    verify transactionId/refNumber; do not blind-retry

ON_FAILURE_RATE_LIMIT  (429)
  MEANS:   throttled
  RETRY:   yes
  BACKOFF: honor Retry-After / RateLimit-Reset, then exponential + jitter
  STOP:    after bounded attempts/elapsed time

ON_FAILURE_SERVER      (500)  [Errors schema]
  MEANS:   platform-side failure
  RETRY:   yes
  BACKOFF: exponential + jitter
  STOP:    after bounded attempts; escalate

Workflow recipes

RECIPE: File and confirm

1. obtain token (oneapi:access)
2. CreateTransaction (body + callbackUrl); generate refNumber for correlation
3. expect 202
4. await callback → branch on callbackType (SUCCESS|FAILURE|EVR|DMVDESK|INVOICED)
5. on SUCCESS: optionally GetTransactionFees
6. on FAILURE: read errors; correct; go to RECIPE: Revise

RECIPE: Revise

1. UpdateTransaction (FULL body; id or refNumber; callbackUrl)
2. expect 202
3. await callback; re-evaluate

RECIPE: Cancel

1. CancelTransaction (id or refNumber; optional message)
2. expect 202
3. confirm terminal state via callback/status

RECIPE: Quote fees

1. ensure transaction exists and processing has advanced
2. GetTransactionFees
3. if empty → treat as "not yet calculated"; backoff and re-read (no status-read op exists)