Design Multi-Agent Systems: Reliable and Secure Agent Workflows with Human Approval
An Accounts Payable analyst receives an invoice for ten units. The purchase order authorizes eight, and the receiving record also confirms eight. An investigation agent can collect these facts, while a second agent can interpret the policy governing the mismatch. But the design fails if OIC passes a conversation transcript instead of a validated finding, or starts the policy review before the investigation has actually finished.
The challenge is not getting two agents to communicate. It is preserving the case, evidence and decision boundaries while one specialist's output becomes another specialist's input. In this article, we will build that coordination model using OIC's native AI Agent actions, explicit JSON contracts and deterministic validation gates. We will also distinguish the documented runtime behavior from the result-mapping detail that must be confirmed in the actual OIC environment.
1. The Workflow You Will Build
This is an integration-led architecture. OIC owns the case, routing, validation, sequence and completion. Two separately configured AI agents perform specialist reasoning.
Practical outcome: Design an OIC project containing an Invoice Investigation Agent, a Policy Interpretation Agent, their read-only evidence integrations, and an orchestration integration that invokes the agents in sequence. The article provides the architecture, artifact configuration, application contracts, deterministic validation, durable-ledger schema and recovery workflow. It remains an implementation blueprint, not a tenant-tested, importable end-to-end lab: generated conversation-ID/result mappings, database adapter details, callback schema and REST Adapter retry behavior must be verified in the target OIC instance.
Our illustrative business case
| Case ID | CASE-1001 |
| Invoice | INV-1042 |
| Purchase order | PO-2087 |
| Invoice quantity | 10 units |
| Ordered quantity | 8 units |
| Accepted receipt quantity | 8 units |
All identifiers, quantities, policy excerpts and statuses in this tutorial are synthetic. The quantity comparison is a deliberately bounded teaching rule, not a complete financial invoice-matching implementation. The coordinator—not either LLM—computes the result from source records.
The complete specialist interaction
1. User request
{
"caseId": "CASE-1001",
"invoiceId": "INV-1042"
}
2. Investigation Agent — first contribution
The agent retrieves the invoice, purchase order and receipt through its registered read-only tools. It reports the following illustrative finding:
{
"contractVersion": "1.0",
"caseId": "CASE-1001",
"invoiceId": "INV-1042",
"investigationStatus": "COMPLETE",
"findings": [{
"code": "INVOICE_QTY_EXCEEDS_PO_AND_RECEIPT",
"itemId": "ITEM-440",
"unitOfMeasure": "EA",
"invoiceQty": 10,
"purchaseOrderQty": 8,
"acceptedReceiptQty": 8
}],
"missingInformation": []
}
3. OIC — independently verified handoff
OIC checks the agent's response contract, then independently reads the invoice, purchase order and receipt through trusted REST invoke connections. It compares the agent's reported values with those source responses, confirms matching line and item identifiers, and constructs the evidence references itself. Only this OIC-created evidence snapshot—not the agent's assertions—is passed to the Policy Agent.
4. Policy Interpretation Agent — second contribution
The second agent retrieves the relevant policy and interprets it against the investigation findings.
{
"contractVersion": "1.0",
"caseId": "CASE-1001",
"evidenceSnapshotId": "SNAP-CASE-1001-01",
"policyStatus": "COMPLETE",
"decision": "HOLD_FOR_AP_REVIEW",
"recommendedNextAction": "REQUEST_CORRECTED_INVOICE",
"applicablePolicy": {
"policyId": "PROC-AP-017",
"version": "1.0",
"effectiveFrom": "2026-01-01",
"clauseId": "QTY-4.2"
},
"missingInformation": [],
"rationale": "The invoice quantity exceeds both the ordered and accepted receipt quantities."
}
5. Final OIC response
{
"caseId": "CASE-1001",
"evidenceSnapshotId": "SNAP-CASE-1001-01",
"workflowStatus": "RECOMMENDATION_READY",
"decision": "HOLD_FOR_AP_REVIEW",
"recommendedNextAction": "REQUEST_CORRECTED_INVOICE",
"evidenceRefs": [
"INV:INV-1042",
"PO:PO-2087",
"RCPT:RCPT-3091",
"POLICY:PROC-AP-017:QTY-4.2"
],
"transactionExecuted": false
}
This is the intended business interaction, not an executed tenant trace. It is important that the final output is a recommendation and not an instruction to release payment.
2. In This Post
- Environment and naming conventions
- Coordination ownership and handoff contracts
- Read-only tools and sample data
- Two specialist agents and their boundaries
- OIC orchestration and native AI Agent actions
- Response extraction and validation gates
- Positive, missing-data and invalid-response tests
- Troubleshooting and recovery
- Enterprise engineering considerations
- Completion checklist
- Five useful FAQs
- Verified references
- Finally — Summary
3. Before You Begin
Minimum prerequisites
- An Oracle Integration 3 instance with Agentic AI available and the required project access.
- A supported LLM connection, including its endpoint, model and credential information. The selected ReAct pattern must support the chosen provider.
- Permission to create and edit project integrations, agent tools and AI agents, and activate the necessary components. Project access is governed using OIC project RBAC.
- Four read-only REST-triggered integrations for the simulated invoice, purchase order, receipt and policy data.
- Two active specialist agents and an active ReAct thinking pattern.
- An integration capable of using the native AI Agent action and, for status monitoring, the Get AI Agent Activity Stream operation.
- Coordinator-side authenticated REST invoke connections for independent reads of invoice, PO, receipt and policy data.
You do not need access to Oracle Fusion Financials or a real Accounts Payable database for this lab. The simulated integrations below provide the required records.
The supported LLM routes depend on the chosen agentic AI pattern. Oracle documents OpenAI, Anthropic and Azure support for its ReAct and Plan patterns, and OCI Generative AI options for the corresponding OCI GenAI patterns. Model availability can vary by region. The two agents can use the same approved model; different models are not a prerequisite for multi-agent architecture.
Official references: Supported Large Language Models and About Projects.
4. Concepts That Affect This Workflow
4.1 Integration-led coordination versus agent-led delegation
Our design uses deterministic integration-led coordination.
OIC decides that the invoice must be investigated first and the relevant policy must be evaluated second. The Investigation Agent cannot independently decide to skip the evidence-validation stage, and the Policy Agent cannot initiate a business transaction.
There is no Supervisor Agent in this architecture. We have two specialist agents called explicitly by an integration.
This is a custom composition pattern built using documented OIC capabilities. It is not a claim that OIC automatically creates an autonomous agent team or supplies a shared agent-memory service.
4.2 What exactly is a handoff?
A handoff is the transfer of an agreed application-level payload from one participant to another.
Here, the investigation result is not simply a paragraph that the second agent is expected to understand. It is a versioned JSON contract with a case identifier, findings, evidence references, missing-information details and an allowed next action.
The contract separates three things:
- Evidence: Which application records support the finding?
- Interpretation: What does the specialist conclude from those records?
- Recommendation: What should happen next according to the business rules?
The receiving agent must get the relevant evidence, not merely a conversation ID. A conversation ID is an identifier for an agent conversation; it is not proof that another agent has access to that conversation's complete history.
4.3 Why we need explicit contracts
An LLM can be instructed to return JSON, but that instruction alone does not enforce a JSON schema. It may omit a property, return a string instead of a number, introduce an unsupported decision, or produce text that cannot be parsed.
Therefore, the coordinator must validate the actual returned representation before routing it onward. The JSON contract belongs to the application layer; the model instruction is only a request to follow it.
4.4 Case ID, integration instance ID and conversation ID
These identifiers solve different problems.
| Identifier | Purpose |
|---|---|
| CASE-1001 | Business correlation identifier. Remains associated with the same invoice investigation across workflow stages. |
| OIC integration instance ID | Identifies an individual integration runtime execution. |
| Agent conversation ID | Identifies the AI agent conversation and its associated interaction history. |
Oracle documents that a conversation ID can span multiple agent instance IDs. The agent monitoring screen also uses an Instance ID column for the conversation identifier. Do not confuse that screen's identifier with the integration instance ID displayed under integration monitoring.
For this exercise, each specialist gets its own generated conversation ID. OIC retains CASE-1001 as the business correlation value across both calls. We do not reuse a conversation ID to imply shared specialist context.
A simple analogy
Imagine an Accounts Payable team. One employee collects the invoice, purchase order and goods-receipt records. A second employee reads the payment policy. The case number identifies the investigation, while the actual documents carry the evidence. Merely telling the second employee the first employee's desk number does not transfer the documents.
In this OIC workflow, this means: carry the case ID and validated evidence in the handoff payload. Keep agent conversation identifiers for conversation tracking, not as substitutes for business data.
5. Practical Work — Prepare the Tools and Sample Data
5.1 Establish consistent project and artifact names
Use one project for this learning prototype so the integrations, agents, tools and thinking pattern remain together.
| Artifact | Tutorial name |
|---|---|
| Project | AP_MULTI_AGENT_LAB |
| Coordinator | AP_COORDINATE_INVOICE_CASE |
| Investigation Agent | AP_INVOICE_INVESTIGATION_AGENT |
| Policy Agent | AP_POLICY_INTERPRETATION_AGENT |
| Invoice tool | AP_GET_INVOICE |
| PO tool | AP_GET_PURCHASE_ORDER |
| Receipt tool | AP_GET_RECEIPT |
| Policy tool | AP_GET_POLICY |
These names are tutorial conventions, not Oracle-reserved identifiers.
5.2 Create the four focused read-only integrations
Create each tool as a project integration with a REST Adapter trigger. For registration as an agentic AI tool, Oracle's current documentation requires an active project integration, an OAuth-protected REST trigger and a JSON payload. Oracle documents GET, POST, PUT, DELETE and PATCH as supported REST Adapter verbs for registered tools. This tutorial uses POST consistently as a fixture design choice; POST is not a universal product requirement. The coordinator-side verification connections described above are independent reads and should use a method appropriate to the endpoint.
The simulated integrations should return records without updating any source system. A simple fixture-based implementation can use the input identifier and a switch/assignment to return the appropriate response.
Additional coordinator-side verification requirement: The coordinator must be able to read the same source records independently of the LLM. Configure REST Adapter invoke connections, with the required OAuth access, so AP_COORDINATE_INVOICE_CASE can call the invoice, purchase-order and receipt endpoints directly after the Investigation Agent finishes. The Policy Agent's policy reference must likewise be checked against an independent read of AP_GET_POLICY. These reads are separate from the agent's registered tools. They let OIC verify source values and construct its own evidence snapshot. For a real system, prefer a versioned snapshot or source revision identifier so that a second read cannot silently compare records from different points in time.
| Integration | Input | Purpose |
|---|---|---|
| AP_GET_INVOICE | invoiceId | Invoice header and line quantities, including linked PO. |
| AP_GET_PURCHASE_ORDER | poId | Ordered quantities and line identifiers. |
| AP_GET_RECEIPT | poId | Received and accepted quantities. |
| AP_GET_POLICY | policyTopic | Applicable policy identifier, version and clause. |
Illustrative request:
{
"invoiceId": "INV-1042"
}
AP_GET_INVOICE response:
{
"found": true,
"invoiceId": "INV-1042",
"poId": "PO-2087",
"supplierId": "SUP-7001",
"currency": "USD",
"lines": [{
"lineId": "1",
"itemId": "ITEM-440",
"unitOfMeasure": "EA",
"invoiceQty": 10
}]
}
AP_GET_PURCHASE_ORDER response:
{
"found": true,
"poId": "PO-2087",
"lines": [{
"lineId": "1",
"itemId": "ITEM-440",
"unitOfMeasure": "EA",
"orderedQty": 8
}]
}
AP_GET_RECEIPT response:
{
"found": true,
"receiptId": "RCPT-3091",
"poId": "PO-2087",
"lines": [{
"lineId": "1",
"itemId": "ITEM-440",
"unitOfMeasure": "EA",
"acceptedQty": 8
}]
}
AP_GET_POLICY response:
{
"found": true,
"policyId": "PROC-AP-017",
"version": "1.0",
"effectiveFrom": "2026-01-01",
"clauses": [{
"clauseId": "QTY-4.2",
"text": "An invoice line quantity must not exceed the corresponding purchase order and accepted receipt quantities. Quantity discrepancies must be held for Accounts Payable review until corrected documentation or an authorized purchase order correction is recorded."
}]
}
This policy is fictional. The exercise assumes that the three source records refer to the same invoice line, item and unit of measure, and that the illustrated receipt quantity represents the accepted quantity. Actual three-way matching must account for partial receipts, multiple invoice lines, prior invoices, reversals, currency, taxes, tolerances and other applicable business conditions.
5.3 Register the integrations as agentic AI tools
For each applicable integration:
- Open Projects and select AP_MULTI_AGENT_LAB.
- Locate the active integration in the Integrations section.
- Open its Actions menu and select Create agentic AI tool.
- Enter the tool metadata and create it.
- Configure the tool's parameters and save.
The important tool fields are:
| Field | Decision |
|---|---|
| Name | Use the integration's descriptive name. It is not sent to the LLM. |
| Identifier | Use a unique, meaningful tool identifier. It is exposed as tool metadata to the LLM. |
| Description | Explain precisely what record the tool retrieves and when it should be used. |
| Visible | Expose only parameters the agent needs to supply. |
| Required | Use for mandatory identifiers such as invoiceId and poId. |
| Constant / Default | Use only when a fixed, safe value is justified by the tool design. |
| Enum Values | Restrict parameters where the permitted values are known. |
| Description of parameters | Explain the meaning and source of every input. |
Tool guidelines and metadata influence model tool selection. They do not replace OAuth authentication or application authorization. An instruction saying "read-only" is not a security boundary: keep the underlying integrations genuinely read-only.
Checkpoint: all four integrations must be active, registered and available as project tools. Each must return its expected JSON fixture when called independently.
6. Configure the Two Specialist Agents
6.1 Invoice Investigation Agent
In the project workspace, select AI Agents, open the Agents section and create the first specialist. Choose an active ReAct thinking pattern already configured for your approved LLM route.
| Configuration | Value |
|---|---|
| Name | Invoice Investigation Agent |
| Identifier | AP_INVOICE_INVESTIGATION_AGENT |
| Thinking pattern | Supported active ReAct pattern |
| Tools | AP_GET_INVOICE, AP_GET_PURCHASE_ORDER, AP_GET_RECEIPT |
Role:
You are an Invoice Investigation Specialist in an
Accounts Payable process.
Your responsibility is to collect and explain factual
evidence relating to a submitted invoice.
You do not interpret corporate policy, approve invoices,
release payments or modify source records.
Guidelines:
1. Read the supplied caseId and invoiceId.
2. Retrieve the invoice using AP_GET_INVOICE.
3. Obtain the linked poId from the returned invoice.
Do not invent a purchase order identifier.
4. Retrieve the purchase order using
AP_GET_PURCHASE_ORDER.
5. If the purchase order is found, retrieve its
receipt information using AP_GET_RECEIPT.
6. Compare only corresponding item and line records.
7. Report the source record identifiers and factual
quantities. Distinguish unavailable information
from an actual mismatch.
8. If a required record is missing, stop the
investigation and report the missing record.
9. Do not interpret policy or recommend payment.
Do not invoke any update or transaction operation.
10. Return one JSON object matching the
investigation response contract. Report observations only;
do not invent evidence references or choose the next
orchestration step.
Tools and stopping conditions:
- The invoice tool establishes the invoice and linked PO.
- The purchase order tool establishes the ordered quantity.
- The receipt tool establishes the accepted quantity.
- Stop when all required evidence has been retrieved and the findings are complete.
- Stop earlier when a mandatory source record is unavailable. Return INCOMPLETE rather than filling the gap with assumptions.
These instructions influence the LLM's behavior. The final OIC routing decision must still check the returned status and evidence requirements.
6.2 Policy Interpretation Agent
Create the second agent separately in the same project.
| Configuration | Value |
|---|---|
| Name | Policy Interpretation Agent |
| Identifier | AP_POLICY_INTERPRETATION_AGENT |
| Thinking pattern | Supported active ReAct pattern |
| Tool | AP_GET_POLICY |
Role:
You are an Accounts Payable Policy Interpretation
Specialist.
Your responsibility is to interpret the applicable
policy against validated invoice investigation
findings and recommend the appropriate next step.
You do not approve payments or modify financial
records.
Guidelines:
1. Accept the validated investigation payload.
2. Confirm that the caseId matches the supplied case.
3. If the investigation status is INCOMPLETE or the
verified evidence snapshot is missing, return
policyStatus INCOMPLETE, decision NEEDS_MORE_EVIDENCE,
recommendedNextAction MANUAL_REVIEW, and identify
the missing information. Do not interpret a partial case.
4. Retrieve the policy using AP_GET_POLICY.
5. Interpret the actual returned policy version,
effective date and relevant clause against the
verified findings.
6. Return the policy identifier, version, effective
date and clause exactly as retrieved. Do not invent them.
7. If the applicable policy cannot be retrieved, return
policyStatus INCOMPLETE, decision NEEDS_MORE_EVIDENCE,
recommendedNextAction MANUAL_REVIEW, and a null
applicablePolicy object.
8. Return a recommendation, not an approval or
financial transaction instruction.
9. Return one JSON object matching the
policy response contract.
Evidence required: The case ID, invoice ID, complete investigation status, finding details, source evidence references and the relevant policy topic. An investigation marked INCOMPLETE must not be treated as a completed policy review.
Stopping condition: Stop when the relevant policy has been retrieved and interpreted, or when required investigation or policy evidence is unavailable.
Save both agents and activate them. The AI Agent action in an integration lists only agents in Active status.
7. Design the OIC Orchestration Integration
Architecture-prototype boundary
The steps below specify the native actions, the intended control flow and the application contracts. Oracle's public action pages document how to start an agent and how to request its activity stream, but they do not publish a stable mapper property path for the generated conversation ID returned by the start action or for extracting the final assistant message from the activity-stream response. Those two mappings are therefore tenant-verification checkpoints, not completed instructions in this article. No field name or JSON path is guessed here. Until both are confirmed in the target mapper and a real run, treat the integration as a design prototype rather than a deployable end-to-end lab.
7.1 Define the coordinator input contract
Create an integration named AP_COORDINATE_INVOICE_CASE with a REST trigger.
The business request is intentionally small. The coordinator owns the case identifier and receives the invoice identifier. The specialist agents receive only the information needed for their responsibilities.
{
"caseId": "CASE-1001",
"invoiceId": "INV-1042"
}
Validate both properties before calling either agent. Reject an empty identifier or an unsupported request rather than allowing the model to decide what the missing identifier might mean.
7.2 Understand the native AI Agent action
OIC provides a native AI Agent action for starting an agent from an integration.
In the integration canvas:
- Open Actions and add the AI Agent action.
- In Configure Basic Info, give the endpoint a meaningful name and description.
- In Configuration, select AP_MULTI_AGENT_LAB and AP_INVOICE_INVESTIGATION_AGENT.
- Complete the configuration. OIC automatically creates a mapping stage.
- Configure the agent input and validate the mapping.
The relevant mapping parameters are:
| Parameter | Meaning and decision |
|---|---|
| Project Id | Optional override. The selected project is sufficient for this lab. |
| Agent Id | Optional override. The selected active agent is used. |
| Conversation Id | Optional. Leave unspecified to use a newly generated conversation for this specialist execution. |
| Prompt | A direct prompt string sent to the selected agent. |
| Prompt Template Id | Optional template identifier, including version, when using a configured prompt template. |
| Payload | Stringified JSON used with a prompt template. |
For the first call, send a prompt containing the case and invoice identifiers, the required investigation responsibility, and the output contract. If using a prompt template, map its identifier in the documented ID-and-version format and serialize the payload to a JSON string. Do not assume that an ordinary JSON object can be mapped directly into a field requiring stringified JSON.
7.3 Obtain completion information and classify the run state
Starting an agent and establishing that its work is complete are separate coordination concerns. Oracle documents that an agent run receives a conversation ID by default unless one is supplied. The Get AI Agent Activity Stream operation uses that conversation ID and returns the agent's current status.
Configure the native actions:
- Add the AI Agent action and select the start/invoke operation for AP_INVOICE_INVESTIGATION_AGENT.
- Map the case and invoice information through Prompt, or use Prompt Template Id and a stringified JSON Payload.
- Inspect the generated start-action mapper schema and confirm whether the automatically generated Conversation ID is available as an output that can be mapped to a variable. Do not invent an output element name. If it is not exposed in the generated schema, stop: this same-flow polling design is not yet implementable through the documented mapping alone.
- Add another AI Agent action and select Get AI Agent activity stream.
- Map the verified Conversation ID from the first action to the activity-stream action. Validate the mapping and inspect the generated response schema.
- Repeat the activity-stream check using the control-flow mechanism available to the selected integration type, with a configured deadline and bounded retry budget.
The following table is a logical state-classification model, not a published list of OIC status-enum values. Oracle's action documentation says that the response contains the current status, but it does not publish a complete status enumeration or prescribe polling intervals and retry counts.
| Observed state or condition | Coordinator behavior |
|---|---|
Terminal success (the Agent Instances page displays Succeeded) | Stop polling. Continue only after confirming the corresponding value and response shape in the action mapper. |
| Nonterminal processing (the run has not reached a terminal state) | Poll again within the configured budget. Do not launch the next specialist while the first is still processing. |
Waiting for tool to process | The agent is suspended while an asynchronous agentic AI tool completes. Do not treat this as ordinary processing or repeatedly poll without a recovery plan. The asynchronous tool must send its response using the Callback AI agent operation; the agent resumes after the callback. |
| Terminal failure, unrecognized state or deadline exceeded | Fail closed. Do not invoke the next specialist. Record the conversation ID, raw status, last activity and timeout/failure reason for diagnosis. |
In this sample, the four fixture integrations are intended to complete synchronously. Therefore, Waiting for tool to process is not an expected happy-path state. If it appears, the run is using an asynchronous-tool path that is outside the simple fixture flow; implement and verify the callback integration before continuing. Oracle documents that the callback can be sent only while the associated conversation is in that waiting state.
Polling algorithm (logical pseudocode, not OIC mapper syntax):
start the selected specialist agent
capture its conversation ID using the verified action output
set a deadline and maximum poll count
repeat while the deadline and poll budget remain:
request the activity stream for that conversation ID
read the actual status value from the generated response schema
if status is the verified terminal-success value:
stop polling and continue to result inspection
else if status is the verified nonterminal-processing state:
wait according to the locally configured backoff
continue polling
else if status is "Waiting for tool to process":
wait for the asynchronous tool's callback path
then check the conversation again
else:
fail closed and record the raw status
if the deadline or poll budget is exhausted:
mark the orchestration timed out and do not start the next agent
Choose polling intervals and a maximum duration from measured agent latency and the end-to-end response-time objective. They are solution settings, not Oracle defaults. The integration must also use the exact status values exposed by its generated mapper schema; the logical categories above must not be copied as literal enum values unless the tenant confirms them.
Implementation checkpoint — conversation ID and final assistant response
The public documentation confirms that the start action generates a conversation ID by default and that the activity-stream action accepts a conversation ID and returns status. Oracle's asynchronous-tool example also shows the activity stream displaying the tool call, tool response and final LLM answer.
Consequently, this article teaches the documented orchestration pattern and its control requirements. It does not claim that the final-answer extraction mapping or full runtime loop has been executed or verified in a tenant.
7.4 Define the investigation response contract and verify its facts
The Investigation Agent returns a claim/analysis contract. It is not the authoritative evidence record. The following is the expected application-level response:
{
"contractVersion": "1.0",
"caseId": "CASE-1001",
"invoiceId": "INV-1042",
"investigationStatus": "COMPLETE",
"findings": [{
"code": "INVOICE_QTY_EXCEEDS_PO_AND_RECEIPT",
"itemId": "ITEM-440",
"unitOfMeasure": "EA",
"invoiceQty": 10,
"purchaseOrderQty": 8,
"acceptedReceiptQty": 8
}],
"missingInformation": []
}
Incomplete investigation response:
{
"contractVersion": "1.0",
"caseId": "CASE-1002",
"invoiceId": "INV-1099",
"investigationStatus": "INCOMPLETE",
"findings": [],
"missingInformation": [
{
"code": "PURCHASE_ORDER_NOT_FOUND",
"source": "PURCHASE_ORDER",
"recordId": "PO-9999"
}
]
}
The missingInformation array contains objects with a reason code, source name and record identifier where available. The incomplete example is a business-level result returned when the agent completes its reasoning but cannot obtain required evidence. An action failure, agent execution failure or timeout is handled by OIC as an orchestration failure; it must not be disguised as a successful agent response.
The agent must not generate authoritative evidence references or decide whether OIC should invoke the Policy Agent. Those decisions belong to the coordinator. Use these contract rules:
contractVersionmust equal the supported version, currently1.0.caseIdandinvoiceIdmust exactly match the original request.investigationStatusmust beCOMPLETEorINCOMPLETE.- For
COMPLETE, require at least one finding when the sample scenario has a discrepancy, an emptymissingInformationarray, and numeric non-negative quantities. - For
INCOMPLETE, require at least one missing-information item; do not route to the Policy Agent's normal complete-evidence branch. - For this simplified lab,
findings[].codeis restricted toINVOICE_QTY_EXCEEDS_PO_AND_RECEIPTorNO_QUANTITY_DISCREPANCY. OIC independently derives the expected code from the source quantities and rejects a mismatch. - Each finding's
itemIdand reported quantities are agent assertions until independently compared with source responses. missingInformationis an array of objects containingcode,sourceandrecordIdwhen known. ForCOMPLETE, it must be empty; forINCOMPLETE, it must contain at least one item.- Reject unknown finding codes, unsupported fields where strict schema enforcement is configured, invalid types, missing mandatory fields and malformed JSON.
Independent OIC source verification: After the agent run reaches terminal success, the coordinator calls AP_GET_INVOICE, AP_GET_PURCHASE_ORDER and AP_GET_RECEIPT through its own authenticated REST invoke connections. It builds a source snapshot from the returned records and verifies:
- The invoice endpoint returned
found=trueand the exact requested invoice ID. - The PO ID used for the PO and receipt reads came from the returned invoice record, not from the agent.
- The PO and receipt records were found and refer to the same PO, line ID, item ID and unit of measure as the invoice line.
- The invoice, ordered and accepted quantities are numeric and non-negative. OIC compares the agent's reported quantities with these source values.
- OIC derives the discrepancy code and creates the evidence references from the source responses. It does not copy references supplied by the LLM.
The OIC-created object is the trusted handoff evidence. A compact illustration is:
{
"evidenceSnapshotId": "SNAP-CASE-1001-01",
"caseId": "CASE-1001",
"evidenceVerificationStatus": "VERIFIED",
"verifiedFinding": {
"code": "INVOICE_QTY_EXCEEDS_PO_AND_RECEIPT",
"itemId": "ITEM-440",
"unitOfMeasure": "EA",
"invoiceQty": 10,
"purchaseOrderQty": 8,
"acceptedReceiptQty": 8
},
"evidenceRefs": [
"INV:INV-1042",
"PO:PO-2087",
"RCPT:RCPT-3091"
]
}
The snapshot identifier and references above are synthetic examples. A transient variable is not durable evidence. Before starting the Policy Agent, persist the complete canonical snapshot and its metadata in a durable case store. Store the exact source values used—not only the three reference strings—including invoice/PO/receipt identifiers, line IDs, item, UOM, quantities, source revision or ETag when available, retrieval timestamps, policy-relevant case date, verification result and contract version. If source revisions are unavailable, record that limitation and use a bounded read window; do not imply a transactionally consistent cross-system snapshot. If a source is missing, identifiers or units do not match, or the agent quantities differ from the source values, mark the snapshot NOT_VERIFIED and do not invoke the Policy Agent.
Important distinction: Schema validation proves that the agent returned data in the expected shape. Source verification proves that its factual claims match the source snapshot. Neither, by itself, proves that a later policy interpretation is correct.
7.4A Make invoice matching deterministic
The Investigation Agent may explain what it found, but it must not decide whether the invoice matches. OIC applies the business rule to the authoritative source values after validating that the records refer to the same business line.
For this one-line fixture, the deterministic rule is:
require invoice.found = true
require purchaseOrder.found = true
require receipt.found = true
require invoice.poId = purchaseOrder.poId = receipt.poId
require invoice.lineId = purchaseOrder.lineId = receipt.lineId
require invoice.itemId = purchaseOrder.itemId = receipt.itemId
require invoice.unitOfMeasure = purchaseOrder.unitOfMeasure = receipt.unitOfMeasure
require all quantities are numeric and >= 0
if invoiceQty > orderedQty OR invoiceQty > acceptedQty:
findingCode = INVOICE_QTY_EXCEEDS_PO_AND_RECEIPT
else:
findingCode = NO_QUANTITY_DISCREPANCY
This is the complete matching rule for the synthetic single-line case only. It does not implement tolerance, cumulative receipts, prior invoice consumption, returns, reversals, price/amount matching, tax, currency conversion or multi-line allocation. For a real AP process, those rules must be specified by the business owner and implemented as deterministic logic (for example, a governed database procedure or an OIC decision branch), not inferred by an LLM.
OIC must compare the agent's reported quantities with the source values as a consistency check. The source-derived rule determines the finding code. If the agent reports a different code or quantity, record AGENT_SOURCE_MISMATCH and stop the normal route; do not average, choose the more plausible value or ask the Policy Agent to resolve the conflict.
7.4B Persist the complete evidence snapshot and derive stable keys
Use a durable store accessible to the coordinator and its recovery integration. A relational table is a practical implementation choice; the schema below is an application-owned design, not a predefined OIC system table.
AP_CASE
-------
CASE_ID primary key
REQUEST_KEY unique
INVOICE_ID
CASE_STATUS RECEIVED | INVESTIGATING | EVIDENCE_VERIFIED |
POLICY_PENDING | RECOMMENDATION_READY |
MANUAL_REVIEW | FAILED
INVESTIGATION_CONV_ID
POLICY_CONV_ID
CURRENT_SNAPSHOT_ID
ROW_VERSION
CREATED_AT / UPDATED_AT
AP_EVIDENCE_SNAPSHOT
--------------------
SNAPSHOT_ID primary key
CASE_ID foreign key
SNAPSHOT_VERSION
CANONICAL_PAYLOAD complete immutable source snapshot
SNAPSHOT_HASH hash of canonical payload
VERIFICATION_STATUS VERIFIED | NOT_VERIFIED
SOURCE_READ_AT
SOURCE_REVISION_METADATA
UNIQUE(CASE_ID, SNAPSHOT_VERSION)
AP_AGENT_RUN
------------
CASE_ID, AGENT_ROLE, ATTEMPT_NO
CONVERSATION_ID
RUN_STATE START_REQUESTED | RUNNING | WAITING_CALLBACK |
SUCCEEDED | FAILED | UNKNOWN
LAST_ACTIVITY_AT
RESULT_PAYLOAD / RESULT_HASH
UNIQUE(CASE_ID, AGENT_ROLE, ATTEMPT_NO)
AP_CALLBACK_INBOX
-----------------
CALLBACK_EVENT_KEY unique
CONVERSATION_ID
TOOL_INSTANCE_ID
PAYLOAD_HASH
PROCESSING_STATE RECEIVED | APPLIED | REJECTED
RECEIVED_AT / APPLIED_AT
AP_TARGET_OPERATION
-------------------
OPERATION_KEY primary key
SNAPSHOT_HASH
TARGET_REFERENCE
STATE NOT_SENT | SENT | CONFIRMED | UNKNOWN | REJECTED
LAST_ERROR / UPDATED_AT
Build the canonical snapshot from a fixed field order and normalized representations (stable date/time zone, decimal scale, null handling, character encoding and array ordering). Compute snapshotHash over that canonical representation. The idempotency key for any later business operation must be derived from the complete immutable evidence snapshot, not merely from caseId, invoice ID or an agent conversation ID. For example:
operationKey = SHA-256(
"AP-RECOMMENDATION|" + caseId + "|" + snapshotHash + "|" + policyId + "|" + policyVersion + "|" + clauseId
)
This means a changed invoice, receipt, PO revision or policy reference produces a different key. A retry for the same immutable evidence and policy decision reuses the same key. Store the key under a unique constraint and reject reuse if the same key is presented with a different payload hash. The hash is a deduplication identity, not a security signature or authorization token.
7.4C Practical OIC workflow for persistence and recovery
- Receive and register: In
AP_COORDINATE_INVOICE_CASE, validate the request, derive a stable request key from the caller's business request identity, and call a small database REST service or supported database integration to insertAP_CASE. Enforce uniqueness in the database; a prior request returns the existing case rather than creating another. - Claim the stage: Update the case with an optimistic version check (or a database-side compare-and-set procedure) before starting a specialist. Only the process that successfully claims the expected state may proceed. Do not rely on an in-memory OIC variable as a cross-instance lock.
- Start Investigation Agent: Insert an
AP_AGENT_RUNrow withSTART_REQUESTEDbefore the native Start AI Agent action. After the action returns, persist the generated conversation ID immediately and move the run toRUNNING. The exact mapper output must be verified in the tenant, as stated above. - Poll and persist: After each activity-stream response, persist the observed raw status and timestamp. On verified success, persist the extracted result and its hash before moving to contract validation. On timeout, persist
UNKNOWN; do not blindly start another agent conversation. - Verify and freeze evidence: Independently read invoice, PO and receipt; apply the deterministic checks above; create the canonical snapshot; insert it as immutable
AP_EVIDENCE_SNAPSHOT; updateAP_CASE.CURRENT_SNAPSHOT_IDand stage in one database transaction/procedure. - Invoke Policy Agent: Only after the snapshot transaction commits, construct the policy payload from the stored snapshot and start the second agent. Persist its conversation ID and status independently.
- Finalize: Validate the policy response, independently read the policy source and verify ID, version, effective date and clause. Persist the recommendation and its evidence links before returning it to the caller.
- Recover: A scheduled or operator-triggered recovery integration queries cases in nonterminal states whose lease/updated timestamp has expired. It reads the durable run state and activity stream; it resumes polling, applies an unprocessed callback, reconciles an unknown start, or routes to MANUAL_REVIEW. It never assumes that an expired OIC integration instance means the external agent or target operation did not complete.
Use a database-side procedure for multi-row state transitions that must be atomic. OIC coordinates the calls; the database transaction protects the ledger update. This does not create a distributed transaction with the AI Agent runtime or any external target.
7.4D Callback crash recovery and duplicate delivery
For an asynchronous tool, the callback integration must first write the callback into AP_CALLBACK_INBOX using a unique event key derived from the conversation ID, tool instance ID and a stable callback/event identifier supplied by the actual callback contract. If the callback contract exposes no stable event identifier, use a documented payload hash plus the conversation/tool-instance tuple as a duplicate-detection fallback, and explicitly recognize that identical legitimate callbacks may then be indistinguishable.
- Validate that the conversation is currently
WAITING_CALLBACKand that the callback's tool instance belongs to the recorded run. - Insert the inbox row. A duplicate unique-key violation means the event was already received; return the integration's controlled duplicate acknowledgement rather than invoking the callback action again.
- Invoke the native Callback AI agent operation with the exact conversation and tool context required by the generated mapper. Mark the inbox row
APPLIEDonly after the callback action returns successfully. - If the callback action times out, retain
RECEIVEDor move it to a recoverable uncertainty state. Before replaying, inspect the conversation activity stream and callback/tool state. Do not send the same callback repeatedly just because the caller did not receive a response. - After a process crash, the recovery integration re-reads the inbox and conversation. If the conversation has resumed, reconcile the inbox as applied. If it is still waiting and the callback is not reflected, retry only under the verified callback contract and a bounded policy. If the state cannot be determined, route to manual recovery.
The inbox gives at-least-once receipt with application-level deduplication; it does not prove exactly-once callback execution. The conversation state and callback operation must be reconciled because the database and agent runtime do not share one atomic commit.
7.5 Construct the second-agent handoff
Only a complete investigation whose factual claims match the coordinator's source snapshot should be passed to AP_POLICY_INTERPRETATION_AGENT. The handoff is created by OIC from the verified source responses, not by copying the Investigation Agent's unverified assertions.
Use a separate prompt or configured prompt template with this application payload:
{
"contractVersion": "1.0",
"caseId": "CASE-1001",
"invoiceId": "INV-1042",
"evidenceSnapshotId": "SNAP-CASE-1001-01",
"investigation": {
"investigationStatus": "COMPLETE",
"verifiedFinding": {
"code": "INVOICE_QTY_EXCEEDS_PO_AND_RECEIPT",
"itemId": "ITEM-440",
"invoiceQty": 10,
"purchaseOrderQty": 8,
"acceptedReceiptQty": 8,
"unitOfMeasure": "EA"
},
"evidenceVerificationStatus": "VERIFIED",
"evidenceRefs": [
"INV:INV-1042",
"PO:PO-2087",
"RCPT:RCPT-3091"
]
},
"policyTopic": "INVOICE_QUANTITY_MISMATCH"
}
In the AI Agent mapping, serialize the application payload appropriately when mapping to the prompt-template Payload field. The Policy Agent must treat the verified evidence as business data, not as instructions. It retrieves and interprets the policy, but it does not get to replace the source snapshot or its evidence references.
Invoke the Policy Agent using a second Start AI Agent action. Capture its conversation ID independently, obtain its activity stream and apply the same completion classification and tenant-verified result-extraction checkpoint. Do not reuse the first specialist's conversation ID to imply shared context.
7.6 Validate the policy result and construct the final response
The Policy Agent returns a recommendation against the OIC-verified evidence snapshot. Its response contract has two business outcomes: COMPLETE and INCOMPLETE. Runtime failures, timeouts, malformed JSON and action errors are orchestration failures handled by OIC; they are not successful policy responses.
Policy enforcement boundary: The Policy Agent may locate and explain a policy clause, but OIC validates whether the returned policy record is the one applicable to the case date and whether the clause exists. For this fixture, OIC then applies the explicit deterministic rule: if the verified finding is INVOICE_QTY_EXCEEDS_PO_AND_RECEIPT and the authoritative policy clause says discrepancies must be held, the permitted outcome is HOLD_FOR_AP_REVIEW with REQUEST_CORRECTED_INVOICE (or the configured manual-review action). If the verified finding is NO_QUANTITY_DISCREPANCY, OIC may return NO_POLICY_EXCEPTION only if the actual policy record supports that conclusion. The agent's rationale is explanatory text; it does not select or override the OIC decision. If the policy text is ambiguous, contradictory, outside its effective period or changed since the snapshot, return MANUAL_REVIEW.
Complete policy response:
{
"contractVersion": "1.0",
"caseId": "CASE-1001",
"evidenceSnapshotId": "SNAP-CASE-1001-01",
"policyStatus": "COMPLETE",
"decision": "HOLD_FOR_AP_REVIEW",
"recommendedNextAction": "REQUEST_CORRECTED_INVOICE",
"applicablePolicy": {
"policyId": "PROC-AP-017",
"version": "1.0",
"effectiveFrom": "2026-01-01",
"clauseId": "QTY-4.2"
},
"missingInformation": [],
"rationale": "Invoice quantity exceeds ordered and accepted quantities."
}
Incomplete policy response:
{
"contractVersion": "1.0",
"caseId": "CASE-1001",
"evidenceSnapshotId": "SNAP-CASE-1001-01",
"policyStatus": "INCOMPLETE",
"decision": "NEEDS_MORE_EVIDENCE",
"recommendedNextAction": "MANUAL_REVIEW",
"applicablePolicy": null,
"missingInformation": [
{
"code": "POLICY_NOT_FOUND",
"policyTopic": "INVOICE_QUANTITY_MISMATCH"
}
],
"rationale": "The applicable policy could not be retrieved."
}
Contract rules and enumerations:
contractVersionmust be1.0;caseIdandevidenceSnapshotIdmust match the coordinator's current case and verified snapshot.policyStatusmust beCOMPLETEorINCOMPLETE.decisionmust be one ofHOLD_FOR_AP_REVIEW,NO_POLICY_EXCEPTIONorNEEDS_MORE_EVIDENCE.recommendedNextActionmust be one ofREQUEST_CORRECTED_INVOICE,RECONCILE_RECEIPT,MANUAL_REVIEWorNO_ACTION.- For
COMPLETE, require a non-nullapplicablePolicy, a supported policy ID/version/clause, an effective policy for the case date, and an emptymissingInformationarray. The decision must beHOLD_FOR_AP_REVIEWorNO_POLICY_EXCEPTION.NEEDS_MORE_EVIDENCEis not a valid complete outcome. - For
HOLD_FOR_AP_REVIEW, the next action must beREQUEST_CORRECTED_INVOICE,RECONCILE_RECEIPTorMANUAL_REVIEW. ForNO_POLICY_EXCEPTION, useNO_ACTIONfor this recommendation-only sample. - For
INCOMPLETE, requiredecision=NEEDS_MORE_EVIDENCE,recommendedNextAction=MANUAL_REVIEW, a null policy object when no policy was found, and at least one missing-information item. - OIC independently calls AP_GET_POLICY and checks that the returned policy ID, version, effective date and clause actually exist. OIC constructs the policy evidence reference from that source response; it does not trust an LLM-supplied reference.
- Even when the policy reference is real, the agent's semantic interpretation remains a recommendation. A production process must retain human policy review where the business rule requires it.
A value such as PAY_NOW or RELEASE_PAYMENT is not part of this module's contract. OIC must reject it even when the LLM returns it confidently.
Final integration output for the illustrative complete case:
{
"caseId": "CASE-1001",
"evidenceSnapshotId": "SNAP-CASE-1001-01",
"workflowStatus": "RECOMMENDATION_READY",
"decision": "HOLD_FOR_AP_REVIEW",
"recommendedNextAction": "REQUEST_CORRECTED_INVOICE",
"evidenceRefs": [
"INV:INV-1042",
"PO:PO-2087",
"RCPT:RCPT-3091",
"POLICY:PROC-AP-017:QTY-4.2"
],
"transactionExecuted": false
}
For an incomplete investigation, a source mismatch, an incomplete policy response or any invalid contract, OIC must return an appropriate non-success workflow status and must not create the normal recommendation-ready response.
The intended sequence is: start Investigation Agent, classify completion, extract its result using the verified tenant mapping, validate the contract, independently verify invoice/PO/receipt facts, construct the OIC-owned evidence snapshot, start Policy Agent, classify completion, extract and validate its response, independently verify the policy reference, and construct the final response.
8. What Must Never Advance Silently?
There are three distinct gates in this design.
| Gate | Required condition | Failure outcome |
|---|---|---|
| Completion gate | The agent run is complete. | Do not extract or route a partial result. |
| Contract gate | The response parses and contains every required field with permitted values. | Reject malformed or unsupported output. |
| Source-evidence gate | OIC independently confirms source record identity, line/item/UOM alignment, quantities, policy version, effective date and clause; agent claims match the source snapshot. | Do not hand off unverified claims. Hold the case for missing evidence, mismatch or manual review. |
For example, a valid JSON result containing plausible quantities is still not a valid investigation handoff until OIC compares those quantities with its own source snapshot. Similarly, a completed Policy Agent run with an unsupported decision or a nonexistent policy clause must not be returned as a valid recommendation.
9. Test and Prove the Required Scenarios
The following are expected test outcomes, not claims that these tests have been executed in an Oracle tenant.
Test 1 — Quantity mismatch
Input: CASE-1001, INV-1042, PO-2087, and receipt RCPT-3091.
Expected: The Investigation Agent reports 10 invoice units against 8 ordered and 8 accepted units. OIC independently reads the invoice, PO and receipt, verifies their line/item/UOM alignment, compares the reported quantities with the source values and constructs the evidence references. Only the OIC-created verified snapshot reaches the Policy Agent. OIC independently confirms the returned policy ID/version/clause before returning HOLD_FOR_AP_REVIEW with REQUEST_CORRECTED_INVOICE.
Proof: Verify the agent's three tool calls, the coordinator's independent source reads, the source snapshot, the comparison result, the OIC-generated evidence references, the validated handoff payload, the policy source check and the final coordinator response.
Test 2 — Missing purchase order
Use an invoice fixture linked to PO-9999 and configure AP_GET_PURCHASE_ORDER to return:
{
"found": false,
"poId": "PO-9999",
"reasonCode": "PURCHASE_ORDER_NOT_FOUND"
}
Expected: The Investigation Agent returns INCOMPLETE and identifies PURCHASE_ORDER_NOT_FOUND. OIC does not invoke the Policy Agent through the normal complete-investigation branch.
Proof: Inspect the investigation response, the evidence gate and the absence of a Policy Agent invocation for this case.
Test 3 — Invalid policy response
Simulate an otherwise valid response that contains this unsupported value:
{
"contractVersion": "1.0",
"caseId": "CASE-1001",
"policyStatus": "COMPLETE",
"evidenceSnapshotId": "SNAP-CASE-1001-01",
"decision": "PAY_NOW",
"recommendedNextAction": "RELEASE_PAYMENT",
"applicablePolicy": {
"policyId": "PROC-AP-017",
"version": "99.0",
"effectiveFrom": "2099-01-01",
"clauseId": "PAY-99.9"
},
"missingInformation": [],
"rationale": "Invoice appears acceptable."
}
Expected: The integration rejects the response because the decision and action are not permitted and the referenced policy version/clause does not match the authoritative policy response. Agent-supplied evidence references are not used to construct the final result. The response must not be converted into a recommendation or sent to a payment integration.
Proof: Inspect the validation error, the final workflow status and the fact that no downstream transaction was invoked.
Test 4 — Source values disagree with the agent
Configure the fixture so the agent reports an invoice quantity of 10 while the coordinator's invoice source returns 9, or make the receipt line use a different UOM.
Expected: OIC rejects the handoff as AGENT_SOURCE_MISMATCH or SOURCE_LINE_MISMATCH, persists a NOT_VERIFIED snapshot/audit outcome, and does not start the Policy Agent.
Proof: Inspect the exact source payloads, comparison result, case state and absence of a second agent run.
Test 5 — Duplicate callback after coordinator restart
Deliver the same asynchronous-tool callback twice, with a simulated coordinator interruption after inbox insertion but before the callback action result is recorded.
Expected: The unique inbox key prevents a second logical application. Recovery inspects the conversation before deciding whether the callback action must be resumed. No callback is blindly replayed.
Proof: Inspect inbox rows, callback action count, conversation state and final AP_AGENT_RUN state.
Test 6 — Timeout with an uncertain target write
For a separately enabled test-only target operation, let the target commit a record but suppress/delay its response until OIC times out.
Expected: OIC records UNKNOWN, queries the target using the operation key derived from the complete evidence snapshot, finds the committed record and reconciles it as CONFIRMED. It does not issue a second create.
Proof: Inspect the immutable snapshot hash, operation key, target audit record, reconciliation query and exactly one target-side create. This test is an acceptance design; it has not been executed.
Test summary:
| Case | Expected behavior | Evidence to inspect |
|---|---|---|
| Quantity mismatch | Both agents contribute and a validated hold recommendation is returned. | Tool calls, handoff payloads and both final responses. |
| Missing PO | Investigation becomes INCOMPLETE and policy review is skipped. | Missing record, status and routing branch. |
| Invalid response | Unsupported decision/action and invalid policy version/clause are rejected. | Contract/source-validation error and absence of downstream execution. |
| Agent/source mismatch | Snapshot is NOT_VERIFIED; policy agent is not started. | Source payloads, mismatch record and run ledger. |
| Duplicate callback/restart | Inbox deduplicates; recovery reconciles before callback replay. | Inbox unique key, callback count and conversation state. |
| Uncertain target write | Target is queried before any replay; duplicate create is prevented. | Snapshot hash, operation key and target audit record. |
Execution status for this published lab: Not executed. These are reproducible fixtures, expected outcomes and verification criteria. No live agent run, imported OIC integration, callback replay or uncertain-write test, or tenant-generated response schema was available for confirmation.
10. Troubleshooting and Recovery
10.1 Retry ownership and the timeout demonstration
Do not combine an OIC fault-handler retry, a REST Adapter connection retry and an application-level retry without proving how they interact. The effective behavior depends on the configured invoke operation, adapter/runtime behavior and fault path. Inspect the generated integration's fault handling and REST Adapter connection settings in the target release; this article does not claim a universal retry count or default.
For this tutorial, the timeout demonstration uses a read-only coordinator lookup (GET) or activity-stream status read. A repeated read is safe with respect to business duplication, although it can still add load and must be bounded. Configure one explicit retry owner in the orchestration for transient read failures, with a maximum attempt count, deadline and backoff. Do not also enable a second independent retry loop for the same call. Treat authentication, authorization, validation and not-found responses as non-retryable unless the source contract explicitly says otherwise.
Never use a blind retry of the native Start AI Agent action to demonstrate timeout recovery. If the start call times out before OIC records the conversation ID, the outcome may be unknown: the agent may have started. Persist START_REQUESTED before the action; if the action outcome is ambiguous, mark the run UNKNOWN, inspect available agent instances/activity evidence using the durable case correlation and operator-supported lookup, and reconcile before any new start. If the runtime provides no supported way to locate that conversation, stop for manual reconciliation rather than creating a second agent run.
For any future non-idempotent target POST, a transport timeout is not proof that the target rejected the request. Persist the operation key and payload hash before sending. On timeout, set target state to UNKNOWN, query the target using the same stable business reference, and reconcile: one exact match means confirm the original operation; multiple matches mean duplicate incident; no match means wait/recheck for the target's documented consistency window. Only resend when the target's idempotency contract or a verified negative reconciliation result makes replay safe. A local OIC retry setting cannot manufacture target-side idempotency.
10.2 REST Adapter retry interaction checklist
- Identify whether the failing call is the REST Adapter invoke, the native AI Agent action or the callback action; they are different operations.
- Record the configured REST Adapter connection policy and the integration fault-handler behavior. Confirm whether a retry is performed by the adapter/runtime, the fault handler or the calling workflow.
- For a read-only GET, choose one retry owner and prove the bounded attempt count in activity tracking.
- For a POST/PUT/PATCH/DELETE, do not retry automatically unless the target operation is idempotent by contract or protected by the target's idempotency key.
- In the timeout test, deliberately delay a read-only GET and confirm one controlled retry path. Do not simulate an ambiguous financial write and then assert that retry is safe.
- Record the request correlation, attempt number, target response or timeout, and reconciliation outcome. Keep secrets and invoice contents out of diagnostic logs.
| Symptom | Likely cause | Targeted check |
|---|---|---|
| Agent unavailable in action selection | Agent is not active or project selection is incorrect. | Check project, agent activation and access. |
| No activity-stream result | Incorrect conversation ID or incomplete run. | Compare the captured conversation ID with the Agent instances page. |
| Agent waiting for tool | The agent invoked an asynchronous agentic AI tool and is paused for its callback response. | Inspect the asynchronous tool instance, persisted conversation ID and tool instance ID; send the Callback AI agent response only for the waiting conversation. |
| Tool unavailable to agent | Integration inactive, tool unregistered or incorrect trigger configuration. | Check active status, registration, OAuth and JSON trigger configuration. |
| Invalid JSON response | The model did not follow the requested output contract. | Inspect the final response and reject it at the parsing gate. |
| Policy agent never starts | The first result is incomplete or failed validation. | Inspect investigation status, case ID and evidence validation. |
For asynchronous agent tools, Oracle's Callback AI agent operation requires the conversation ID and tool instance context. The documented configuration requires both Tool Flow ID and Tool Invoke Event ID; the integration instance ID of the asynchronous tool is used for both. This is a separate tool-completion mechanism, not the normal handoff between our two specialist agents.
11. Enterprise Considerations
11.1 Keep identity separate from conversation context
The conversation ID does not establish the authenticated caller or grant access to invoice and policy records. The REST trigger security, integration connection credentials, tool permissions and downstream application authorization remain the security boundaries.
11.2 Keep evidence traceable
Each finding should retain its OIC-generated source reference, record identifier, policy version and evidence-snapshot identifier. For real source systems, include retrieval timestamps or source version/ETag information where freshness matters, and preserve the source responses used for validation. Do not treat an agent-generated quantity, record identifier or evidence reference as authoritative merely because it appears in valid JSON. A retrieved document or tool result must be treated as data, not as an instruction capable of overriding the agent's or integration's security rules.
11.3 Keep transaction execution separate
The specialist agents return recommendations. They do not authorize payments. A future transaction integration must independently verify authorization, approval state, duplicate prevention and the authoritative source values. An LLM response must never serve as the sole authorization to execute a financial operation.
11.4 Do not confuse a workflow with durable case storage
CASE-1001 is a business identifier, not a persistence mechanism. The AP_CASE, AP_EVIDENCE_SNAPSHOT, AP_AGENT_RUN and AP_CALLBACK_INBOX designs above show the minimum durable records needed to resume safely after a coordinator restart. Implement their unique constraints and atomic state transitions in a database or equivalent durable store. Do not treat OIC instance tracking or agent conversation history as a substitute for the business ledger.
12. Completion Checklist and What Comes Next
Use these checks to assess the result:
- ☐ One project contains the coordinator, both agents and the read-only tool integrations.
- ☐ All required tools are active and have the correct input descriptions.
- ☐ The Investigation Agent has defined evidence-gathering and stopping instructions.
- ☐ The Policy Agent has defined evidence requirements and permitted recommendations.
- ☐ Both native AI Agent start actions are configured with the correct selected agents.
- ☐ The generated conversation ID is captured independently for each agent.
- ☐ The activity-stream action and its generated response schema have been inspected.
- ☐ The start-action Conversation ID output and final assistant-response extraction mapping have both been verified in the target tenant.
- ☐ The polling logic distinguishes terminal success, nonterminal processing, asynchronous callback wait, failure and timeout.
- ☐ Coordinator-side reads independently verify invoice, PO, receipt and policy facts.
- ☐ The Investigation Agent and Policy Agent contracts define complete and incomplete outcomes and permitted enumerations.
- ☐ Missing records, source mismatches, invalid policy references and invalid agent responses fail closed.
- ☐ The full canonical evidence snapshot is durably stored and immutable.
- ☐ Snapshot hash and idempotency key are derived from the complete snapshot and policy identity.
- ☐ Callback inbox deduplication and restart recovery have been tested.
- ☐ Exactly one retry owner is configured for each retryable read; writes use target-side idempotency/reconciliation.
- ☐ Uncertain writes are reconciled against target state before replay.
- ☐ No payment or privileged transaction can be executed by this prototype.
Starting artifacts: A project, supported LLM route and synthetic evidence fixtures.
Expected ending artifacts: Two configured specialist agents, four focused read-only tools, an integration-led orchestration design, two versioned handoff contracts and six defined test scenarios, including source mismatch, duplicate callback recovery and uncertain-write reconciliation.
13. Five Useful FAQs
1. Does invoking two AI agents from one integration automatically make it a multi-agent system?
It establishes a multi-agent solution when the two separately configured agents have distinct responsibilities and participate in a coordinated workflow. It does not imply autonomous agent-to-agent collaboration. Here, OIC explicitly owns the sequence and handoff.
2. Must both agents use different LLMs?
No. Separate agent responsibilities, tools, instructions and context boundaries do not require separate models. Using the same approved model route is a valid starting point.
3. Can I use one conversation ID for both agents?
Do not assume that this produces shared specialist context. Each agent should have its own conversation identifier in this design. The coordinator explicitly passes the validated business evidence to the second agent.
4. Does requesting JSON guarantee a valid JSON response?
No. The requested format is an instruction to the model. The OIC integration must parse the actual response and enforce its application-level contract, including required fields, types, enumerations and evidence references.
5. Can the Policy Agent directly approve or release the invoice?
Not in this design. The Policy Agent interprets the supplied policy and returns a recommendation. Authorization, approval and financial transaction execution belong in separately governed business integrations or workflows.
14. Additional References
These official Oracle sources were consulted for the product behavior and release-sensitive statements in this article.
- Using Agentic AI in Oracle Integration 3 — October 2026 documentation edition.
- Invoke an AI Agent from an Integration — native start action, selected project and active agent, input mapping and conversation ID.
- Get the Activity Stream for an AI Agent — conversation-ID-based activity-stream retrieval and status.
- Register an Integration as an Agentic AI Tool — REST trigger prerequisites, tool metadata and parameter configuration.
- Send a Response to an AI Agent with a Callback — asynchronous tool completion and callback context.
- Use Case: Send a Callback to an AI Agent for an Asynchronous Tool — worked example showing the waiting state, callback resumption and final answer in the activity stream.
- Run an AI Agent with Knowledge of Previous Runs — conversation scope and retention.
- Supported Large Language Models — supported LLM routes for agentic AI patterns.
- Agentic AI Issues — release-specific known issues and workarounds.
- What's New — Oracle Integration 26.10 — article's documentation baseline.
- What's New — Oracle Integration 26.07 — formal release notes listing Get AI Agent activity stream and Callback AI agent as new AI Agent action operations.
- What's New — Oracle Integration 26.04 — formal release notes for the 26.04 Agentic AI feature set; useful for comparing release claims.
- What's New in Oracle Integration 26.04 — product-management blog that says Get Agent Activity Stream was supported in 26.04; the page is explicitly labelled a working document, so treat its release statement cautiously.
- New Adapters and Connectivity Enhancements in Oracle Integration 26.07 — product-management explanation of activity-stream status and asynchronous callback context.
15. Finally — Summary
We have designed an integration-led architecture prototype in which two specialist agents contribute to one Accounts Payable investigation without taking ownership away from OIC. The Investigation Agent reports observations about invoice, PO and receipt records; OIC independently verifies those claims against source responses and constructs the trusted evidence snapshot; the Policy Agent interprets the applicable policy; and OIC validates the policy contract and source reference before returning a recommendation.
The most important engineering lesson is this: a successful agent execution is not automatically a successful business workflow. Completion, contract validity, deterministic source matching, policy applicability, immutable evidence persistence, callback deduplication and target-side idempotency must be checked independently. The examples and tests in this article are synthetic expected outcomes, not executed tenant results. The generated Conversation ID mapping, activity-stream schema, final assistant-response extraction and polling loop remain implementation checkpoints that must be verified before this prototype is promoted to a deployable lab.

Comments
Post a Comment