Imagine an employee asking an AI agent to release a purchase order. The agent checks the order information and requests a manager's approval. That approval may take several minutes or several hours. The agent cannot truthfully report that the order is approved while the manager is still reviewing it. Keeping the original request-response interaction open for the entire approval process is also unsuitable for many long-running business operations.
This creates an important integration question: when the approval eventually arrives, how does Oracle Integration identify the agent conversation that is waiting and the particular tool invocation that needs the result? A callback provides the documented return path. However, it works only when the original callback correlation information is preserved and supplied correctly.
In this tutorial, we will trace a purchase-order approval through an asynchronous OIC agentic AI tool, a separate callback integration, and the native Callback AI agent action. We will also distinguish conversational continuity from restoring an entire integration execution, and examine why retrieving the last stored message is not automatically a safe callback-correlation strategy.
1. What You Will Build
The practical example uses an Oracle Integration 3 Project AI Agent that can request approval for a purchase-order release. The approval itself is handled by an external approval application. When the manager finishes reviewing the request, that application sends its decision to a separate OIC REST integration.
Worked example — Purchase order PO-20418
| Business field | Illustrative value |
|---|---|
| Order number | PO-20418 |
| Order amount | USD 18,500 |
| Initial business state | Awaiting approval |
| Approval request | APR-90041 |
| Illustrative decision | APPROVED |
All order, approval, and employee identifiers are fictional. The USD 18,500 approval requirement is an application-defined example, not an Oracle Integration product rule.
The intended event sequence is:
- The agent selects an asynchronous approval tool.
- The tool starts the approval request and preserves the callback correlation information.
- The agent enters the documented
Waiting for tool to processstate. - The external approval application sends its decision to a separate OIC callback integration.
- The callback integration validates the event and invokes the native Callback AI agent action.
- The agent receives the tool result and continues its reasoning.
Completion evidence: You can identify the original Conversation ID, the original asynchronous tool integration's runtime Instance ID, the approval event, the callback action inputs, the waiting status, and the observable tool response and subsequent agent activity.
Implementation boundary: This is a callback architecture and implementation prototype. The article provides an illustrative business request/result contract and the documented native OIC action configuration. It does not claim that a particular approval application, database, or OIC tenant has been deployed or tested.
2. In This Post
- What You Will Build
- In This Post
- Before You Begin — Shared Setup
- Understand the Agent Callback Model
- Build and Trace the Order-Release Approval Callback
- Test Correlation, Delay, Duplicates, and Ordering
- Troubleshooting and Production Controls
- Five Useful FAQs
- Official Oracle References
- Finally — Summary
3. Before You Begin — Shared Setup
3.1 Required OIC resources
The custom asynchronous callback example requires the following resources:
- An OIC project containing the Project AI Agent.
- An active asynchronous integration registered as an agentic AI tool.
- A persistence mechanism that can retain the original callback correlation information.
- A separate OIC integration that receives the external approval event and invokes the native callback action.
- An external approval application capable of sending a completion event to the callback integration.
Oracle's documented prerequisites for registering an integration as an agentic AI tool are:
- The integration must belong to a project.
- The integration must be active.
- The first connection must be a REST Adapter trigger connection.
- The REST trigger must use OAuth authentication and a JSON payload.
- The HTTP verb can be any verb supported by the REST Adapter: GET, POST, PUT, DELETE, or PATCH.
For this example, we choose POST and a JSON request body because the integration submits an approval request. POST is our design choice; it is not the only HTTP verb permitted by Oracle's registration prerequisites.
The integration is made asynchronous by configuring its REST trigger endpoint not to receive a response. This is a separate configuration decision from choosing POST.
References: Register an Integration as an Agentic AI Tool and How to Specify if an Integration is Synchronous or Asynchronous.
3.2 Shared business request
The approval tool receives a small business request. This is an application-defined request contract for the tutorial, not an Oracle callback schema.
{
"orderNumber": "PO-20418",
"amount": 18500,
"currency": "USD",
"reason": "Release requested after receiving and invoice checks"
}
The order number and amount identify the business request. The reason supplies useful context to the approval application. The identity of the approver and the final approval decision must come from the trusted approval process, not from generated agent text.
3.3 Understand the identifiers before building the callback
The most common callback design mistake is treating different identifiers as though they represent the same object. The callback requires the conversation identifier and the original asynchronous tool integration's runtime identifier. Your business application may also need its own correlation and approval identifiers.
| Identifier | What it identifies | Where it comes from |
|---|---|---|
| Conversation ID | The agent conversation in which the asynchronous tool was invoked. | The runtime-provided x-agentic-callback-uri header or the Conversation ID displayed for the agent run. |
| Tool integration runtime Instance ID | The particular execution of the integration registered as the asynchronous agentic AI tool. | Integration Metadata in the original tool integration's mapper, or the tool integration's runtime instance details. |
| Application correlation ID | The application-owned key used to connect the original request to the later approval event. | Generated and stored by your application or integration design. |
| Approval request ID | The actual approval request created in the external approval application. | Returned by the approval application or its workflow. |
For the callback action, Oracle requires the original asynchronous tool integration's runtime Instance ID to be mapped to both Tool Flow Id and Tool Invoke Event Id. The same value is used for both fields. It is not the Conversation ID, and it is not the callback integration's own runtime Instance ID.
References: Send a Response to an AI Agent with a Callback and Run an AI Agent with Knowledge of Previous Runs.
4. Understand the Agent Callback Model
4.1 Synchronous results versus asynchronous completion
Synchronous execution means the integration endpoint is configured to return a response as part of the original request-response interaction. The caller waits for that response.
Asynchronous execution means the endpoint is not configured to return a response in that original interaction. The integration performs its work independently of that request-response exchange, and a later result can be delivered through a separate mechanism.
Kid-friendly analogy
Imagine asking a shopkeeper whether an item is in stock. The shopkeeper can check the shelf and answer immediately. But if another warehouse must send the item, the shopkeeper records your request and contacts you when the answer arrives.
In this OCI AI integration, this means: A synchronous tool returns its result during the original tool interaction. An asynchronous tool performs work that completes later, so the agent waits for its result through the callback mechanism.
Oracle defines the synchronous/asynchronous distinction through the trigger's response configuration:
- When the endpoint is configured to receive a response, the integration is synchronous.
- When the endpoint is not configured to receive a response, the integration is asynchronous.
For a custom asynchronous agentic AI tool, the agent enters the documented Waiting for tool to process state after it invokes the tool. This is different from a synchronous tool returning its result during the original interaction.
| Tool type | What happens | How the agent proceeds |
|---|---|---|
| Synchronous | The tool returns a result during its original interaction. | The agent can use the returned tool result as it continues its execution. |
| Asynchronous | The tool starts an operation whose result is delivered separately. | The agent enters Waiting for tool to process and waits for the callback response. |
A long-running approval is a suitable example of an asynchronous operation. A quick read-only lookup that reliably returns during the original interaction may be better as a synchronous tool. Select the execution model according to the real behavior of the business operation, not simply because one option sounds more scalable.
Reference: How to Specify if an Integration is Synchronous or Asynchronous.
4.2 What is a callback?
A callback is a mechanism for returning a result to a process that previously requested work after that work has completed. In OIC Project AI Agents, the documented callback action sends the asynchronous tool's result back to the waiting agent conversation.
Kid-friendly analogy
A student asks a teacher to check a result with another school. The teacher records which student made the request. When the other school replies, the teacher returns the answer to that student instead of giving it to someone else.
In this OCI AI integration, this means: The callback sends the completed tool result together with the original conversation and tool-invocation identifiers so OIC can associate it with the correct waiting agent.
Oracle documents the following callback lifecycle for a custom asynchronous agentic AI tool:
- The agent invokes an integration registered as an asynchronous agentic AI tool.
- The agent stops reasoning and enters
Waiting for tool to process. - The asynchronous integration performs its external operation.
- When that operation completes, the external application invokes a separate OIC callback integration.
- The callback integration executes the native Callback AI agent action.
- After the callback response reaches the waiting agent, the agent continues reasoning.
Oracle also documents an important restriction: a callback can be sent to an AI agent only when its associated conversation is in the Waiting for tool to process status.
This is not the same as starting another unrelated agent run with a new prompt. It is also not a general facility for sending a message to any inactive conversation. The callback is the return path for a pending asynchronous tool response.
4.3 The callback correlation information
The callback must identify both the conversation waiting for the result and the original tool integration invocation. This relationship is called correlation: associating a later event with the earlier request that caused it.
Kid-friendly analogy
Imagine a school trip where several children have identical-looking lunch boxes. Each child has a name label, and each lunch box has its own number. The teacher checks both labels before returning a lunch box.
In this OCI AI integration, this means: Use the Conversation ID to identify the conversation and the original asynchronous tool integration's runtime Instance ID for the two required tool-correlation fields.
Oracle's callback operation uses the following logical inputs:
| Callback value | Purpose and source |
|---|---|
| Conversation Id | The Conversation ID of the agent conversation in which the asynchronous tool was invoked. |
| Tool Flow Id | The runtime Instance ID of the integration that ran as the asynchronous agentic AI tool. |
| Tool Invoke Event Id | Required. Oracle's mapping instructions use the same original tool integration Instance ID as Tool Flow Id. |
| Payload | A stringified JSON value containing the result to return to the agent. Oracle does not prescribe a fixed business JSON schema for this payload. |
There is a naming detail worth understanding. The callback guide describes the underlying operation inputs using names such as toolFlowId, conversationId, toolInstanceId, and responsePayload. The OIC mapper instructions display the corresponding fields as Tool Flow Id, Conversation Id, Tool Invoke Event Id, and Payload.
Use the target fields generated by the native callback action in your mapper. Do not create a guessed request schema from the underlying parameter names.
Most importantly, map both Tool Flow Id and Tool Invoke Event Id. Oracle explicitly marks both as mandatory, even though they use the same original tool integration runtime Instance ID.
4.4 Where do the two important values come from?
Conversation ID — the x-agentic-callback-uri header.
Oracle documents that you add an x-agentic-callback-uri header to the asynchronous tool integration trigger. At runtime, OIC populates this header with the agent callback URL, which includes the Conversation ID.
Oracle illustrates the general shape as follows:
https://agent_endpoint/callback?conversationId=CONVERSATION_ID
This is an illustrative URI format, not a URL to copy into your integration. The important value for the callback action is the conversationId included in the runtime-provided header. Oracle instructs you to persist the Conversation ID locally, for example in a database or file, so that it is available when the external operation finishes.
Do not confuse the URI header with the callback operation itself. In the custom design in this tutorial, the external approval application calls your own OIC callback integration. That integration uses the native callback action. The article does not prescribe direct invocation of the URL in the header as an alternative public API.
Tool integration Instance ID — Integration Metadata.
When the asynchronous tool integration runs, OIC makes its runtime Instance ID available in the integration mapper under Integration Metadata, within Runtime Details. Oracle identifies this as the original tool instance value used for callback correlation.
Persist that value along with the Conversation ID before the external approval operation can complete. The callback may arrive after the original asynchronous integration invocation has finished, so relying on values that existed only in the original integration's temporary mapping context is not a suitable design.
4.5 Conversation history is not the same as restoring an execution
Conversation history is the record of interactions associated with a Conversation ID. Oracle documents that an agent can reuse a Conversation ID across different runs to associate prompts, data, and decisions with one conversation.
Oracle also states that AI agent data is retained according to the data-retention period configured for the Oracle Integration service instance.
Kid-friendly analogy
Imagine a class project with a notebook that records the questions asked and the answers received. The notebook helps everyone remember what the group discussed, but it does not automatically restore every child's exact position while they were drawing or writing.
In this OCI AI integration, this means: Conversation history provides continuity for the agent. It does not mean developers should assume that every internal model step, integration cursor, mapper state, or execution position is restored by the callback.
This distinction is central to understanding the word resume.
When the callback response reaches the waiting conversation, Oracle documents that the agent continues reasoning with the returned tool result. This is a documented agent-runtime continuation. It should not be described as restarting every activity from the beginning, or as restoring a complete, developer-visible copy of the original execution stack.
The public documentation reviewed for this article describes the required conversation and tool identifiers and the observable waiting-to-resume lifecycle. It does not document the internal checkpoint format, the model's private reasoning state, or a full instruction-pointer restoration mechanism. Those internal implementation details must not be inferred from the callback mapper.
There are two separate persistence responsibilities:
| Persistence responsibility | What it supports | What it does not prove |
|---|---|---|
| OIC conversation history | Continuity of the agent conversation associated with the Conversation ID. | That every business correlation value or external approval record is available to your custom integration. |
| Application callback record | Retrieval of the correct Conversation ID, tool instance ID, business request, and callback-processing state. | That OIC has resumed the agent successfully. The callback and subsequent agent status still need to be inspected. |
A persistent-memory activity or store may be part of an implementation's persistence design. However, its presence does not by itself prove that it stores the exact callback identifiers required here. That must be established by inspecting its actual input, output, stored record, and retrieval logic.
Reference: Run an AI Agent with Knowledge of Previous Runs.
4.6 What if the agent has multiple asynchronous tools?
An agent can have multiple asynchronous tools in its tool list. This means it can be configured with several tools that may perform long-running work. It does not establish that one conversation can safely have several independent pending asynchronous tool callbacks at the same time.
Oracle documents that when the agent invokes an asynchronous agentic AI tool, it stops reasoning and waits for the callback response. Therefore, the safe design assumption for this tutorial is a sequential flow: the agent waits for the current asynchronous result before continuing to its next decision.
Kid-friendly analogy
Imagine a student who has asked one teacher to check a difficult answer. The student waits for that answer before deciding which question to ask next. Having several teachers available does not mean the student has already received all their answers at once.
In this OCI AI integration, this means: Treat an asynchronous wait as a pause in the current agent decision cycle. Do not assume parallel pending callbacks for one Conversation ID without a documented contract and tenant-level evidence.
For example, the agent may request approval for PO-20418. After the callback returns APPROVED, the agent can decide whether to invoke a separate order-release tool. Do not design the process as though it can depend on a second independent callback being outstanding while the first callback is still pending.
Oracle separately documents that starting another agent run with a Conversation ID that is already in progress, including a conversation in Waiting for tool to process, results in an error. Do not send a new independent run with the same Conversation ID as a way to poll or unblock the existing run.
For business processes that genuinely need parallel approvals, use a workflow or integration design that coordinates the parallel tasks and returns a reconciled result to the waiting agent. Do not assume that the agent callback mechanism itself provides parallel fan-out and fan-in orchestration.
4.7 Custom asynchronous tools versus Human in the Loop
The purchase-order example in this article uses a custom asynchronous agentic AI tool. In that design, an external application sends an event to a separate OIC integration, which invokes the native Callback AI agent action.
OIC also supports a Human in the Loop workflow path. Oracle documents that callback handling is implemented automatically for Human in the Loop. The workflow's End event can return a JSON response, and the callback URL is supplied by the agent at runtime rather than being manually configured inside the workflow.
The distinction is:
- Custom asynchronous tool: Configure a separate callback integration with the native Callback AI agent action when the tool does not use Human in the Loop.
- OIC Human in the Loop workflow: Follow the workflow's Start/End event and response mapping procedure. Callback handling is automatic; do not add an unnecessary custom callback action simply because the workflow waits for a human approval.
The fact that both designs can involve a delayed human decision does not make their implementation contracts interchangeable.
References: Send a Response to an AI Agent with a Callback and Configure Start and End Events.
5. Build and Trace the Order-Release Approval Callback
5.1 The prototype architecture
The design uses two OIC integrations. The first integration is registered as an asynchronous agentic AI tool and submits the approval request. The second integration receives the delayed approval event and sends the result to the agent.
Conceptual flow — one approval request
User asks to release PO-20418
↓ invokes tool
Persists Conversation ID and original tool Instance ID
↓ submits request
Manager reviews the order
↓ later sends event
Validates event and invokes Callback AI agent
↓ returns tool result
Continues reasoning with the approval result
The diagram shows the application architecture, not OIC's internal runtime implementation. The application-owned persistence layer stores the correlation information. Oracle's public callback documentation does not require you to manage an internal OIC conversation-history database.
5.2 Create the asynchronous approval tool integration
Step 1 — Create the integration in the project.
Create an integration in the same OIC project as the agent. Configure its first connection as a REST Adapter trigger with OAuth authentication and a JSON request payload, in accordance with Oracle's agentic AI tool registration prerequisites.
Use a business-oriented integration name such as RequestOrderReleaseApproval. Configure the trigger for POST and use the illustrative request contract from Section 3.3.
Step 2 — Configure the trigger as asynchronous.
For the REST trigger, choose the configuration in which the endpoint is not configured to receive a response. According to Oracle's integration guide, this configuration makes the integration asynchronous.
Do not confuse this with the later callback integration. The approval tool integration starts the external work. The callback integration is a separate endpoint that receives the delayed result.
Step 3 — Include the callback URI header in the trigger contract.
Add the x-agentic-callback-uri header to the asynchronous tool integration trigger as described in Oracle's callback guide. At runtime, OIC populates it with the callback URI containing the Conversation ID.
The header is runtime callback context. Do not expose it as a normal business parameter for the LLM to invent or populate. Do not ask the end user to provide it. Inspect the generated REST trigger request-header structure in your mapper to identify the actual source element.
The exact generated mapper element name and expression are not specified in this article because they depend on the actual trigger schema. Do not copy an XPath or element name guessed from a sample.
Step 4 — Capture the original tool integration runtime Instance ID.
In the integration mapper, inspect the Integration Metadata tree and locate Runtime Details → Instance ID. Oracle identifies this as the runtime tool instance value that can be used for callback correlation.
Do not substitute the Conversation ID or the callback integration's own runtime Instance ID. The original tool integration's Instance ID is the value used for both Tool Flow Id and Tool Invoke Event Id.
Step 5 — Persist the correlation record before submitting the approval request.
Oracle recommends storing the Conversation ID and tool instance ID locally, for example in a database or file. A production design needs an unambiguous way to retrieve the correct pair after the asynchronous integration has finished.
For a concurrent business process, an application-owned correlation row for each asynchronous tool invocation is a clearer design than retrieving a conversation-wide last message without verifying its contents.
The following is an example of an application-owned table. The table name, fields, types, and constraints are design choices for this tutorial. They are not an Oracle-provided callback table or OIC system schema.
CREATE TABLE OIC_AGENT_CALLBACK_CORR (
TOOL_INSTANCE_ID VARCHAR2(256) NOT NULL,
CONVERSATION_ID VARCHAR2(256) NOT NULL,
ORDER_NUMBER VARCHAR2(30) NOT NULL,
CLIENT_CORRELATION_ID VARCHAR2(128) NOT NULL,
APPROVAL_REQUEST_ID VARCHAR2(128),
STATE_CODE VARCHAR2(30) NOT NULL,
CALLBACK_EVENT_ID VARCHAR2(128),
DECISION VARCHAR2(20),
CREATED_AT TIMESTAMP DEFAULT SYSTIMESTAMP NOT NULL,
UPDATED_AT TIMESTAMP DEFAULT SYSTIMESTAMP NOT NULL,
CONSTRAINT PK_OIC_AGENT_CALLBACK_CORR
PRIMARY KEY (TOOL_INSTANCE_ID),
CONSTRAINT UK_OIC_AGENT_CALLBACK_CLIENT
UNIQUE (CLIENT_CORRELATION_ID),
CONSTRAINT UK_OIC_AGENT_CALLBACK_EVENT
UNIQUE (CALLBACK_EVENT_ID)
);
In this example, CLIENT_CORRELATION_ID is an application-generated or application-assigned unique key. Store its relationship to the original tool Instance ID and Conversation ID. Send the application correlation key to the approval system and require the completion event to return it.
The record should contain at least:
- The original Conversation ID.
- The original asynchronous tool integration Instance ID.
- The business order number.
- The application correlation key sent to the approval application.
- The approval request ID when it becomes available.
- A state indicating whether the request is pending, validated, submitted to the callback, or requires reconciliation.
The critical sequencing rule is to persist the callback values before the approval process can return its completion event. If the event arrives before the correlation record is committed, the callback integration may have no safe way to identify the original conversation.
For production designs, also consider the failure window between committing the correlation row and submitting the external request. An application-owned outbox or equivalent dispatch/reconciliation pattern can help prevent an accepted request from becoming untraceable after a timeout or process failure.
Step 6 — Submit the external approval request.
After recording the correlation values, send the business request to the approval application. Include the application correlation key so that the approval system can return it with its completion event.
{
"clientCorrelationId": "APP-CORR-90041",
"orderNumber": "PO-20418",
"amount": 18500,
"currency": "USD",
"reason": "Release requested after receiving and invoice checks"
}
The value APP-CORR-90041 is an illustrative application correlation key. Your integration must use the actual value generated or assigned by your application and stored alongside the original tool Instance ID and Conversation ID.
When the approval system accepts the request, store its returned approval request identifier and leave the correlation record in an application-defined pending state. If external submission fails, record a failure or reconciliation state instead of leaving an apparently valid pending approval request.
5.3 Register the integration as an agentic AI tool
Once the asynchronous integration is active, register it as an agentic AI tool.
- In the navigation pane, select Projects.
- Select the project that contains the asynchronous integration.
- In the Integrations section, locate the active approval integration.
- Open its Actions menu and select Create agentic AI tool.
- Provide the required tool name, identifier, and description.
- Click Create.
- On the Tool details page, review the guidelines and parameter configuration.
- Save the tool configuration.
Oracle distinguishes the purpose of the tool fields:
| Tool field | How to use it |
|---|---|
| Name | Required. Automatically populated from the integration name. Oracle states that this value is not sent to the LLM and cannot be changed after the tool is created. |
| Identifier | Required. Uniquely identifies the tool in the project. It is sent to the LLM as tool metadata and helps the agent understand the tool's purpose. Oracle states that it cannot be changed after creation. |
| Description | Required. Sent to the LLM as part of the system prompt. Explain what the tool does and when it should be used. |
| Guidelines | Optional. Sent to the LLM as part of the system prompt. Use them to describe constraints and conditions for selecting the tool. Guidelines influence the LLM's decision process; they do not enforce authorization. |
| Visible parameters | Only parameters marked Visible are sent to the LLM. Expose business inputs the agent needs, not internal integration values. |
| Required, Constant, Default, and Enum Values | Configure these according to the intended input behavior. Required indicates the LLM must assign a value; Constant and Default Values can be used where a value should not be selected freely by the LLM. |
For this tool, expose the business inputs required by the request, such as order number, amount, currency, and reason. Do not expose internal callback headers, Conversation IDs, tool instance IDs, or database keys as fields that the LLM must generate.
After registering the tool, add it to the intended agent. In the project workspace, open AI Agents, select the relevant agent in the Agents section, use the + control in its Tools section, select the registered approval tool, and add it. Confirm that the tool appears in the agent's configured tools.
The agent's guidelines can describe when approval must be requested and how to interpret the returned result. They are not an authorization mechanism. The approval service and the eventual order-release operation must enforce the business rules independently.
Reference: Register an Integration as an Agentic AI Tool.
5.4 Run the agent and verify that it pauses
Run the active agent and submit a request such as:
Illustrative user request
Please request approval to release purchase order PO-20418 for USD 18,500. The receiving and invoice checks have been completed.
The agent should select the registered approval tool when its configured role, guidelines, and tool metadata lead it to that action. The resulting tool request should contain the business inputs required by the integration.
As the asynchronous integration executes, inspect its runtime mapper and confirm that the expected callback context is available:
| Source in the tool integration | Application value to retain | Why |
|---|---|---|
Runtime x-agentic-callback-uri header |
Conversation ID parsed from the URI | Identifies the conversation that is waiting. |
| Integration Metadata → Runtime Details → Instance ID | Original tool integration Instance ID | Supplies both required tool identifiers in the callback. |
| Tool request body | Order number and business request details | Allows the callback integration to validate the approval event against the original request. |
The exact mapper element names for the trigger header and runtime metadata depend on the actual integration schema displayed in your designer. Use the source tree and mapper expression tools. Do not copy an XPath or node name guessed from this article.
After the asynchronous tool starts, inspect the project's Observe tab and the AI Agents monitoring area. The expected documented agent status while waiting is:
Expected agent status
Waiting for tool to process
That status is evidence that the asynchronous tool has not yet returned its result to the agent. A successfully submitted approval request is not the same as an approved purchase order, and it is not evidence that the agent has completed its task.
5.5 Create the callback integration
Create a second integration in the project. This integration receives the delayed approval event from the external approval application.
Step 1 — Configure the external callback trigger.
Use a REST Adapter trigger with POST and a JSON request body. Configure the trigger's authentication and authorization according to the security requirements of your OIC environment and the external approval caller. The external approval application must be authenticated and authorized to invoke this endpoint.
The following is an illustrative application-defined JSON body sent by the approval application. It is not the native OIC Callback AI agent operation schema.
{
"clientCorrelationId": "APP-CORR-90041",
"approvalRequestId": "APR-90041",
"orderNumber": "PO-20418",
"decision": "APPROVED",
"approverId": "manager-17",
"decisionTimestamp": "2026-11-10T04:40:00Z",
"eventId": "APPROVAL-EVT-90041-1",
"comments": "Approved after checking supporting documents"
}
The event returns the same application correlation key that was sent to the approval system. The callback integration uses that key to retrieve the original Conversation ID and tool Instance ID from the application-owned record.
The fields decision, approverId, decisionTimestamp, eventId, and comments belong to this example's business contract. They are not Oracle-reserved callback fields.
Step 2 — Retrieve and validate the correlation record.
Use clientCorrelationId to retrieve the exact pending record. The lookup should return one matching row. If it returns zero rows or more than one row, stop and investigate. Do not guess which conversation should receive the result.
Before invoking the agent callback, verify:
- The correlation record exists and is in the expected pending state.
- The order number in the callback matches the order number in the original request.
- The approval request ID matches the request previously created for this order.
- The decision is an allowed value in the application's approval contract, such as
APPROVEDorREJECTED. - The event identifier has not already been processed.
- The original Conversation ID and tool Instance ID were retrieved from the same correlation record.
A duplicate callback must not create a second approval result or repeat a downstream business action. Use a unique event identifier and an application-owned state transition to detect duplicates before attempting the agent callback.
Step 3 — Add the native AI Agent action.
In the callback integration canvas:
- On the canvas, use the Actions panel or the add control at the location where the action should be placed.
- Search for and select AI Agent.
- In Configure Basic Info, enter a meaningful value for What do you want to call your endpoint, such as
CallbackToOrderReleaseAgent. - Optionally provide a description.
- For Action, select Callback AI agent.
- In Configuration, select the current project or a shared project containing the target agent.
- Select the intended active AI Agent and finish the configuration wizard.
Only active AI agents are listed for selection. The action automatically creates a mapper for the callback operation. Inspect the generated target structure instead of inventing a custom target schema.
Step 4 — Map the callback values.
The required mappings are:
| Callback mapper field | Source value | Meaning |
|---|---|---|
| Conversation Id | The original Conversation ID retrieved from the correlation record. | Returns the result to the conversation that invoked the asynchronous tool. |
| Tool Flow Id | The original asynchronous tool integration's runtime Instance ID. | Identifies the tool flow being answered. |
| Tool Invoke Event Id | The same original asynchronous tool integration Instance ID. | A second mandatory correlation field. Do not leave it blank. |
| Payload | A string containing the JSON approval result constructed from the validated callback event. | The tool result the agent receives when reasoning continues. |
The following is a representative business result to return. Its fields are defined by the application, not by a fixed Oracle callback schema.
{
"approvalRequestId": "APR-90041",
"orderNumber": "PO-20418",
"decision": "APPROVED",
"approverId": "manager-17",
"decisionTimestamp": "2026-11-10T04:40:00Z",
"eventId": "APPROVAL-EVT-90041-1"
}
Oracle defines the callback Payload as a stringified JSON value. The logical JSON result above must therefore be serialized into a string before it is mapped to that field.
For illustration, the serialized value has this shape:
"{\"approvalRequestId\":\"APR-90041\",\"orderNumber\":\"PO-20418\",\"decision\":\"APPROVED\",\"approverId\":\"manager-17\",\"decisionTimestamp\":\"2026-11-10T04:40:00Z\",\"eventId\":\"APPROVAL-EVT-90041-1\"}"
Use a mapper function or an appropriate preceding transformation to construct the string. Do not assume that mapping a JSON object directly into a string field automatically performs the required serialization.
Oracle identifies Project Id and Agent Id as optional overrides. In this example, the project and agent are already selected in the action configuration, so leave these fields at their configured defaults unless your design intentionally targets a different project or agent.
Step 5 — Validate, save, and activate.
Validate the mapper. Confirm that Conversation Id, Tool Flow Id, Tool Invoke Event Id, and Payload are all mapped. Save and activate the callback integration.
The callback integration is separate from the original asynchronous tool integration. Its own runtime Instance ID must not be used as the callback's Tool Flow Id or Tool Invoke Event Id.
Primary reference: Send a Response to an AI Agent with a Callback.
5.6 REST route: what is supported, and what is not
The REST side of this design needs a careful distinction. The external approval application communicates with the REST trigger of your callback integration. That integration then invokes the native OIC Callback AI agent action.
Oracle's published Developer REST API catalogue includes AI Agent management operations, including creating, retrieving, and deleting AI Agents in projects, as well as operations for retrieving agent tools and patterns. The catalogue reviewed for this article does not list a direct REST operation for sending a callback response to a waiting Project AI Agent.
REST boundary
Do not invent a direct endpoint such as /ai/agents/{id}/callback. The documented custom route in this tutorial is an external HTTP request to your own OIC callback integration, followed by the native Callback AI agent action.
The external approval system calls the activated callback integration using its published REST trigger URL. The actual URL and authentication details depend on the OIC instance and the security policy configured for that trigger.
The following is a client-side request template:
curl --request POST "$CALLBACK_TRIGGER_URL" \
--header "Content-Type: application/json" \
--header "$CALLBACK_AUTH_HEADER" \
--data-binary @approval-callback.json
Replace CALLBACK_TRIGGER_URL with the endpoint copied from the activated callback integration. Set CALLBACK_AUTH_HEADER to the complete authentication header required by that REST trigger's configured security policy. The exact OAuth client configuration, token URL, scope, or other authentication details cannot be supplied without the tenant's actual security configuration.
The file approval-callback.json contains the application-defined event body shown in Section 5.5. This HTTP request calls your callback integration. It does not call the native agent callback operation directly.
The supported implementation route described here is:
- The external approval application sends an authenticated HTTP POST to your OIC callback integration.
- The callback integration validates the approval event and retrieves the correlation record.
- The callback integration maps the values into the native Callback AI agent action.
- OIC returns the response to the original waiting agent conversation.
It does not claim that an undocumented internal endpoint exists or that a custom direct REST operation is supported.
Reference: Oracle Integration 3 Developer REST API — All REST Endpoints.
5.7 What happens after the callback?
After the callback reaches the waiting conversation, the agent can continue reasoning using the returned approval result. The approval payload is now the tool result available to the agent.
For the illustrative result:
Illustrative callback result
Approval request APR-90041 for PO-20418 returned APPROVED. The event identifies manager-17 as the approver and includes the approval timestamp.
A possible next agent decision is to invoke a separate order-release tool because the approval result is APPROVED. If the response is REJECTED, the agent must not claim that the order was released.
This decision is not the authorization boundary. The release-order integration or target business system must independently verify the authoritative approval record, the correct order, its current business state, the caller's release permissions, and applicable idempotency controls.
A model-generated statement such as "the order is approved" must never be treated as proof of approval. The authoritative approval system supplies the decision; the downstream business operation enforces the release rules.
The agent's next tool choice is an observable agent decision. It is not a substitute for inspecting the approval record or the downstream transaction result.
5.8 Inspect the callback and the resumed activity
Do not stop when the callback integration reports that its action completed. Verify the agent-level result as well.
In the project workspace, use the Observe tab and the AI Agents monitoring area to locate the relevant agent run and inspect its status. Also inspect the integration instances for the asynchronous tool and callback integration.
Oracle's callback example shows the following evidence sequence: the agent is first in Waiting for tool to process; the callback integration sends the response; the associated ReAct pattern receives the callback; the callback flow completes; and the AI Agent instance can then reach Succeeded. The activity stream shows the tool call, the tool response, and the subsequent assistant answer.
Treat this as the observable sequence in Oracle's example, not as a guarantee that every agent configuration will have an identical visible pattern-flow label or exactly the same timing.
You can also add the native Get AI Agent Activity Stream action to an integration. Configure the operation and map the Conversation ID. Oracle documents that the response includes the activity stream and a Status value indicating the agent's current status.
The activity stream is evidence of observable messages and tool interactions. Do not present it as a complete dump of private model reasoning or an internal execution checkpoint.
References: Use Case: Send a Callback to an AI Agent for an Asynchronous Tool and Get the Activity Stream for an AI Agent.
5.9 The supplied integration's "last stored message" correlation — inspection status
BLOCKED — exact mapper behavior not verified
No actual project export, integration export, or mapper screenshot for the referenced integration is attached to this request. Therefore, it is not possible to confirm which persistent-memory activity retrieves the last message, which message collection it reads, how it orders the records, or which fields it maps into the callback action.
The phrase last stored message describes a possible application retrieval strategy. It is not the callback correlation contract documented by Oracle.
Oracle's callback instructions identify the Conversation ID from the runtime callback URI and the original asynchronous tool integration Instance ID from Integration Metadata. They do not establish that the runtime automatically selects the last stored conversation message to determine which callback to send.
A message-history lookup can help reconstruct context. It becomes a risky callback-routing mechanism when "last" is treated as equivalent to "the exact pending tool request."
Consider this illustrative sequence:
| Stored message | Possible meaning | Why "last" can be unsafe |
|---|---|---|
| User message | The user requested an approval. | It may contain no tool-invocation identifiers. |
| Assistant message | The agent explains that approval is pending. | It may not represent the pending tool invocation. |
| Tool request message | A specific asynchronous tool was invoked. | It still must be tied to the exact runtime tool instance and pending status. |
| Another conversation's latest message | An unrelated user or agent interaction. | An unscoped latest-message lookup can return the wrong conversation entirely. |
For the supplied integration, inspect these questions before declaring the "last stored message" method safe:
- Which data is retrieved? Identify the actual read/retrieve operation. Determine whether it returns a message list, one message, or a structured memory record.
- How is it scoped? Confirm that the query is restricted to the correct Conversation ID. A global latest-message query is not safe for callback correlation.
- How is "last" determined? Inspect the sort key, timestamp, ordering direction, result limit, tie-breaker, and pagination behavior. Do not assume that the last array element is the newest message.
- Which message type is selected? Determine whether the result represents a user message, assistant response, or tool request. A callback needs the correct pending invocation, not merely the most recently written text.
- Does the selected record contain the required identifiers? Confirm the original Conversation ID and original tool integration Instance ID are available and belong to the same pending invocation.
- When is the record saved? Confirm that the relevant correlation data is committed before the external approval system can send its completion event.
- What happens with concurrent conversations? Test interleaved writes, delayed callbacks, duplicate events, and out-of-order completion.
A design that retrieves the latest message can be safe only under deliberately validated conditions. For example, the lookup must be scoped to the correct conversation, select the expected tool-request record, and obtain the exact callback identifiers for the pending invocation. The word "last" by itself does not establish those conditions.
For a robust implementation, prefer one application-owned correlation record per asynchronous tool invocation. If the supplied flow intentionally stores callback metadata inside a message or persistent-memory record, inspect the actual record schema and confirm that the lookup is keyed to the exact invocation rather than relying on recency alone.
6. Test Correlation, Delay, Duplicates, and Ordering
A successful callback is not enough to prove that the design is correct. The important question is whether the returned approval result reaches the correct waiting conversation and whether the agent and business process handle that result correctly.
| Case | Expected behavior | Evidence to inspect |
|---|---|---|
| Positive — approved order | Agent waits; callback returns APPROVED; agent resumes and can choose the next business action. | Original Conversation ID, tool Instance ID, waiting status, callback integration instance, activity-stream tool response, and final agent status. |
| Business boundary — rejected approval | Agent receives REJECTED and does not claim that the order was released. | Approval record, callback payload, agent activity, and absence of a successful release transaction. |
| Invalid — wrong order number | Callback integration detects that the event does not match the original request and does not invoke the agent callback. | Correlation lookup, original order number, callback order number, and validation fault. |
| Duplicate — same approval event twice | The second event is recognized by its event ID and does not repeat the business action. | Unique event record, application state, callback integration instance, and order-release audit record. |
| Delayed — approval arrives late | The handler checks the current agent status and correlation record before attempting the callback. It does not assume that a stale conversation can be reopened. | Agent status, Conversation ID, stored correlation values, configured data retention, and event age. |
| Out of order — PO-20419 completes before PO-20418 | Each event is routed using its own correlation record, not whichever message was most recently stored. | Both Conversation IDs, both tool instance IDs, both approval request IDs, and their callback results. |
| Missing correlation record | Callback is not guessed or sent to a conversation selected by a global latest-message lookup. The event is held for reconciliation. | Lookup result, missing-row fault, event ID, and reconciliation record. |
| Same Conversation ID invoked again while waiting | A second run is not used as a polling or recovery mechanism. Oracle documents an error when starting another run for a conversation already in progress or waiting. | Conversation ID and agent status. |
6.1 Test out-of-order callbacks with separate conversations
Use two separate agent conversations for the concurrency test:
| Business request | Correlation record | Completion order |
|---|---|---|
| PO-20418 | Conversation A + Tool Instance A | Second |
| PO-20419 | Conversation B + Tool Instance B | First |
Send the callback for PO-20419 first, then send the callback for PO-20418. Each callback must retrieve its own correlation record using its own application correlation key.
The later-arriving PO-20418 event must not pick up PO-20419's Conversation ID simply because PO-20419 was the most recently updated record. This test is particularly important when the design uses a last-message retrieval. A successful single-request test does not prove that a recency-based lookup is safe under interleaved traffic.
6.2 Test sequential asynchronous tools in one conversation
For one Conversation ID, test a sequence such as:
- The agent requests approval for PO-20418.
- The agent enters
Waiting for tool to process. - The approval callback returns APPROVED.
- The agent resumes and makes its next decision.
- If the next action is asynchronous, the agent enters a new wait for that tool's result.
The sequence tests one pending asynchronous result at a time. It is not proof that multiple independent asynchronous invocations can remain outstanding concurrently in the same conversation.
7. Troubleshooting and Production Controls
7.1 Callback troubleshooting
| Symptom | Likely area to inspect | Targeted correction |
|---|---|---|
| Agent remains in Waiting | Callback integration was not invoked, failed, or used incorrect correlation values. | Inspect the callback integration instance and verify Conversation Id, Tool Flow Id, Tool Invoke Event Id, and Payload. |
| Callback integration ran but the agent did not continue | Wrong conversation, wrong original tool Instance ID, or conversation no longer in the waiting status. | Check the current agent status and compare callback values with the original tool integration's runtime metadata. |
| Callback mapping validation fails | A mandatory field is unmapped or Payload is not a stringified JSON value. | Inspect the generated callback mapper target. Map both tool ID fields and serialize the response as a string. |
| Approval event cannot find a pending request | Persistence failed, the external correlation key was not echoed, or the lookup selected the wrong record. | Trace the original insert and outbound request. Do not fall back to an unscoped latest-message lookup. |
| Wrong order receives the approval result | Business correlation and agent callback correlation were mixed, or the lookup returned an unrelated record. | Match the external correlation key and order number to the original pending row before invoking the callback. |
| Duplicate approval event repeats work | No event-level duplicate check or an uncertain callback outcome. | Use an event ID uniqueness control. Inspect agent status and activity before retrying a callback whose outcome is uncertain. |
7.2 Delayed and duplicate callback handling
A callback may be delayed because approval takes longer than expected, the external application retries event delivery, or the OIC callback integration is temporarily unavailable.
Oracle's callback guide establishes that the associated conversation must be in Waiting for tool to process when a callback is sent. The public callback instructions reviewed for this article do not establish a universal callback time-to-live or a guarantee that repeated callback submissions are automatically deduplicated.
The application should therefore manage its own callback-delivery state. A simple application-defined state model is:
PENDING
|
v
CALLBACK_RECEIVED
|
v
CALLBACK_VALIDATED
|
v
CALLBACK_SUBMITTED
|
+----> RECONCILIATION_REQUIRED
These are application-defined states, not OIC agent status values. They help the integration distinguish an event that has arrived from one that has passed validation and one that has been submitted to the native callback action.
For a duplicate event, check its unique event ID and current record state before invoking the callback. If the callback integration reports an uncertain outcome—for example, the callback action may have completed but a later persistence update failed—inspect the agent's status and activity stream before retrying.
Do not claim exactly-once callback delivery based only on an application state flag. A network timeout can make the result of a remote call uncertain. Your application should use duplicate-event handling, idempotent downstream business operations where supported, and a reconciliation process for ambiguous outcomes.
For an event that arrives after the conversation is no longer waiting, do not assume that resending the old callback will reopen the conversation. Hold the business result for reconciliation and determine whether a new business interaction is required.
7.3 Security and business authorization
A callback is a business event arriving through an integration endpoint. Protect that endpoint using an authentication method supported by its configured REST Adapter trigger, and authorize the external caller to invoke it.
Distinguish the following responsibilities:
- Authentication: Identify the system or principal sending the approval event.
- Authorization: Determine whether that principal is permitted to submit the event.
- Business validation: Verify the approval request, order, decision, and current business state.
- Agent callback: Return the validated tool result to the waiting conversation.
The agent's guidelines may influence when it selects an approval tool, but they do not enforce the approver's authority. Similarly, a model-generated statement such as decision = APPROVED is not a trusted approval record.
The authoritative approval application must supply the decision, and the downstream order-release operation must verify it independently.
Treat comments and other text returned by the external approval application as untrusted input. A comment may contain misleading instructions. Do not allow such text to override agent security instructions, integration authorization, or business rules.
7.4 Retention, missing history, and operational recovery
Oracle documents that AI agent data is retained according to the data-retention period configured for the Oracle Integration service instance. The application-owned callback record should have its own retention and audit policy.
Do not assume that deleting one record or changing the OIC instance retention setting automatically deletes every related external approval artifact. Define the retention and deletion requirements for both OIC conversation data and application-owned business correlation data.
If a callback event arrives but its correlation record is missing, fail closed. Do not choose the most recent conversation or infer the tool instance ID from an unrelated agent record. Record the event for reconciliation and inspect:
- The original asynchronous tool integration instance.
- The persisted Conversation ID and tool Instance ID.
- The original business request and external approval identifier.
- The current agent conversation status.
- Whether the event was already processed.
If the original conversation cannot be shown to be waiting, do not attempt to force a callback using guessed identifiers. Route the business result to a controlled reconciliation process.
7.5 Observe the agent and the integrations
Use OIC monitoring to verify the entire sequence rather than judging success from the agent's final sentence alone.
- Open the project and select Observe.
- Open the AI Agents monitoring area and locate the relevant agent run and Conversation ID.
- Check whether the status changes from
Waiting for tool to processafter the callback is sent. - Inspect the integration instances for the asynchronous tool and callback integration.
- Open the relevant instance details and verify the request, callback mapping, and integration outcome.
- Where useful, use the native Get AI Agent Activity Stream action to retrieve observable activity by Conversation ID.
A complete verification trace should connect the original business request, the pending correlation record, the external approval event, the callback action inputs, the agent's tool response, and any subsequent business transaction.
The generated agent response is not the source of truth for the approval or the order release.
References: Get the Activity Stream for an AI Agent and Run an AI Agent with Knowledge of Previous Runs.
8. Five Useful FAQs
1. Does a callback restart the AI Agent from the beginning?
No. Oracle documents that the agent resumes reasoning after receiving the callback response. This is a continuation of the waiting conversation with the returned tool result. It is not a documented promise to restore every internal model step, private reasoning state, or exact execution position of every integration activity.
2. Are Conversation ID and Tool Flow Id the same value?
No. Conversation ID identifies the conversation. Tool Flow Id identifies the runtime instance of the asynchronous integration invoked as the agentic AI tool. Oracle also requires Tool Invoke Event Id and instructs that it use the same value as Tool Flow Id. Do not substitute the Conversation ID or the callback integration's runtime Instance ID.
3. Can the external approval application call the URL in x-agentic-callback-uri directly?
Oracle documents the runtime-provided header as a way to obtain the callback URI containing the Conversation ID. The custom integration pattern described here is for the external application to call your own authenticated OIC callback integration, which then invokes the native Callback AI agent action. This tutorial does not prescribe direct invocation of the runtime URI as a separate public API contract.
4. Do I need a separate Callback AI agent action for an OIC Human in the Loop workflow?
No. Oracle documents that callback handling is automatic for Human in the Loop. Follow the workflow's configured End event and response mapping. The separate manual Callback AI agent action is for the custom asynchronous agentic AI tool path that does not use Human in the Loop.
5. Can one Conversation ID have several asynchronous tool callbacks pending at the same time?
Do not assume so. Oracle documents that the agent stops reasoning when it invokes an asynchronous tool and waits for the callback response. Multiple asynchronous tools may be available in the agent's tool list, but that does not establish parallel pending callbacks within one conversation. Prefer sequential tool completion unless the exact behavior is documented and validated for your OIC release and design.
9. Official Oracle References
The following Oracle documentation is the basis for the OIC-specific behavior and procedures described in this article. Application-specific request bodies, database structures, and approval-event examples are illustrative designs rather than Oracle-defined schemas.
- Send a Response to an AI Agent with a Callback — callback lifecycle, waiting status, runtime Conversation ID header, tool Instance ID, native callback action, mandatory mappings, and payload.
- Use Case: Send a Callback to an AI Agent for an Asynchronous Tool — example of the waiting-to-callback-to-agent-completion sequence and monitoring evidence.
- Register an Integration as an Agentic AI Tool — project, activation, REST trigger, OAuth, JSON, supported verbs, tool metadata, guidelines, and parameter configuration.
- How to Specify if an Integration is Synchronous or Asynchronous — the trigger response configuration that determines integration execution type.
- Run an AI Agent with Knowledge of Previous Runs — Conversation ID reuse, conversation history, retention, and restrictions on starting another run while the conversation is active or waiting.
- Get the Activity Stream for an AI Agent — native Get AI Agent Activity Stream action and Conversation ID mapping.
- Configure Start and End Events — Human in the Loop workflow response payload and runtime-provided callback URL behavior.
- Oracle Integration 3 Developer REST API — All REST Endpoints — public Developer REST API catalogue reviewed for a direct AI Agent callback operation.
- Oracle Integration 26.07 release notes — Oracle's release announcement identifying Callback AI agent as a new asynchronous tool response operation.
- Oracle Integration 26.10 release notes — later release documentation used as the review baseline.
10. Finally — Summary
An asynchronous OIC agentic AI tool allows a task such as purchase-order approval to finish after the initial tool interaction. When the agent invokes that tool, OIC places the conversation in Waiting for tool to process. The result must return through the documented callback mechanism before the agent can continue reasoning.
The most important engineering responsibility is correlation. Preserve the original Conversation ID and the original asynchronous tool integration's runtime Instance ID. Map that tool Instance ID to both Tool Flow Id and Tool Invoke Event Id, and return the business result as a stringified JSON payload.
Conversation history supports continuity, but it is not a replacement for application-owned business correlation or approval records. A "last stored message" lookup is safe only when its scope, ordering, message type, and invocation identifiers have been verified.
For a production design, correlate each callback to a specific pending tool invocation, validate the approval independently, handle duplicate and delayed events, and inspect the resumed agent activity as well as the final business outcome.

Comments
Post a Comment