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, side effects, and safety.

Operation intent

operation_id	Goal
`createInquiry`	Submit a license/document verification request; acknowledged asynchronously.
`LoadInquiryById`	Retrieve an inquiry by its server-assigned identifier.
`LoadInquiryByRefNumber`	Retrieve an inquiry by the caller-supplied reference number.
`LoadInquiryRecord`	Retrieve the structured verification outcome for an inquiry.
`GetReport`	Retrieve the verification result as a PDF.

Prerequisite / dependency tree

OAuth token (scope: oneapi:access)
- createInquiry            [generate reference number first]
  - inquiry exists & processed
    - LoadInquiryById / LoadInquiryByRefNumber
    - LoadInquiryRecord   (meaningful only after completion)
    - GetReport           (meaningful only after completion)

Per-operation reasoning contracts

OPERATION: createInquiry
  AUTH:           REQUIRED — oneVituOauth, scope oneapi:access
  PRECONDITIONS:  REQUIRED — valid token; caller-generated reference number (UUID)
                  OPTIONAL — location header, on-behalf-user header
  SIDE_EFFECTS:   REQUIRED — creates a new inquiry; initiates async verification against state records
  SUCCESS_SIGNAL: REQUIRED — request accepted for processing (acknowledgment, not result)
  AGENT_NOTE:     Result is NOT in this response. Correlate later via reference number.

OPERATION: LoadInquiryById
  AUTH:           REQUIRED — oneVituOauth, scope oneapi:access
  PRECONDITIONS:  REQUIRED — inquiry exists; hold its server identifier
  SIDE_EFFECTS:   none (read-only)
  SUCCESS_SIGNAL: REQUIRED — inquiry returned; check processed timestamp / error field for completion

OPERATION: LoadInquiryByRefNumber
  AUTH:           REQUIRED — oneVituOauth, scope oneapi:access
  PRECONDITIONS:  REQUIRED — inquiry exists; hold the reference number used at creation
  SIDE_EFFECTS:   none (read-only)
  SUCCESS_SIGNAL: REQUIRED — inquiry returned; check processed timestamp / error field for completion

OPERATION: LoadInquiryRecord
  AUTH:           REQUIRED — oneVituOauth, scope oneapi:access
  PRECONDITIONS:  REQUIRED — inquiry exists AND has completed processing
  SIDE_EFFECTS:   none (read-only)
  SUCCESS_SIGNAL: REQUIRED — verification outcome present (pass/fail boolean + description)
  AGENT_NOTE:     verificationPassed=false is a valid completed result, NOT a call failure.

OPERATION: GetReport
  AUTH:           REQUIRED — oneVituOauth, scope oneapi:access
  PRECONDITIONS:  REQUIRED — inquiry exists AND has completed processing
  SIDE_EFFECTS:   none (read-only)
  SUCCESS_SIGNAL: REQUIRED — PDF binary returned

Safety classification

operation_id	Classification
`createInquiry`	mutating (creates inquiry; triggers external verification)
`LoadInquiryById`	safe (read-only)
`LoadInquiryByRefNumber`	safe (read-only)
`LoadInquiryRecord`	safe (read-only)
`GetReport`	safe (read-only)

No irreversible operations are defined. createInquiry has no defined cancel/delete counterpart.

Failure-handling rules

ON_FAILURE_AUTH:
  MEANING:   Token missing/invalid/expired.
  RETRY:     Yes, once, after acquiring a fresh token.
  BACKOFF:   None needed for the token refresh itself.
  STOP:      If still failing after refresh → treat as authorization/config issue; stop.

ON_FAILURE_AUTHORIZATION:
  MEANING:   Authenticated but lacks permission for the resource.
  RETRY:     No.
  STOP:      Immediately; escalate credential/permission config.

ON_FAILURE_VALIDATION:
  MEANING:   Malformed/invalid request (see Errors schema messages/fields).
  RETRY:     No (not without changing the request).
  STOP:      Immediately; correct inputs per error messages.

ON_FAILURE_NOT_FOUND:
  MEANING:   Inquiry not present or not yet available (may surface as validation/empty).
  RETRY:     Conditional — if inquiry recently created, treat as not-yet-ready and poll.
  BACKOFF:   Poll with capped exponential backoff.
  STOP:      After max poll attempts or once inquiry confirmed nonexistent.

ON_FAILURE_RATE_LIMIT:
  MEANING:   TooManyRequests response; limit window exceeded.
  RETRY:     Yes, after the window resets.
  BACKOFF:   Wait for reset window, then exponential backoff with jitter.
  STOP:      After capped attempts.
  KNOWN_ISSUE: No Retry-After header defined in spec; derive wait heuristically.

ON_FAILURE_SERVER:
  MEANING:   Server-side error.
  RETRY:     Yes.
  BACKOFF:   Exponential backoff with jitter.
  STOP:      After capped attempts; escalate to support.

Workflow recipes

RECIPE: Verify via polling

1. Acquire token (scope oneapi:access).
2. Generate reference number (UUID).
3. createInquiry (retain reference number).
4. Poll LoadInquiryByRefNumber (or LoadInquiryById) until processed timestamp present.
   - - - Apply ON_FAILURE_NOT_FOUND while awaiting availability.
5. LoadInquiryRecord → read verificationPassed + description.
6. (Optional) GetReport → archive PDF.

RECIPE: Verify via callback

1. Acquire token (scope oneapi:access).
2. Generate reference number (UUID).
3. createInquiry with callback URL (see KNOWN_ISSUE on callback URL delivery).
4. On transactionCompleted callback: correlate via reference number / inquiry identifier.
5. LoadInquiryRecord → read outcome. (Optional) GetReport.
  FALLBACK: If no callback within expected window, switch to polling recipe.