A procurement agent receives a request to investigate a supplier delivery. It selects a tool, sends an order reference, receives a response, and prepares an answer. But suppose the answer is wrong—or the agent stops before completing the task. Looking only at the final response does not tell us whether the model selected the wrong tool, the integration mapped an incorrect argument, the external system failed, or the result never reached the agent's next execution step.
For an integration engineer, the important skill is reconstructing the execution from evidence. OIC provides separate ways to observe agent conversations, integration instances, and asynchronous tool callbacks. These records describe related parts of a run, but they are not interchangeable. This tutorial follows one synthetic procurement request through the ReAct lifecycle and shows how to build an evidence-based explanation without confusing a visible trace with the model's private reasoning or assuming that every action was successfully persisted.
1. What You Will Build
We will reconstruct one hypothetical OIC project AI Agent execution from the initial user request to the final response. The scenario uses a procurement agent investigating purchase order PO-5821.
The practical outcome is an execution narrative that answers five questions:
- What information was presented to the agent?
- What action did the model request?
- Which OIC integration actually executed, and what did it return?
- Which evidence was recorded, and which information was available to a subsequent model invocation?
- Why did the run finish, wait, fail, or stop?
We will use the native OIC AI Agent activity-stream action and the documented callback action. We will not invent a public REST endpoint for the agent conversation activity stream: the available generic integration activity-stream REST endpoint is for an integration instance, not an agent conversation.
Completion evidence
You should be able to produce a chronological event table, correlate the conversation and tool integration identifiers, distinguish tracking from model context, classify a failure by its responsible layer, and write a short explanation supported by observable records.
2. In This Post
- Before You Begin — Evidence and Scenario
- Reconstructing the ReAct Execution Lifecycle
- Identifiers, Working Memory, and Tracking
- Investigating Tool Selection, Arguments, and Lost Context
- Understanding Asynchronous Tool Callbacks
- Retrieving the AI Agent Activity Stream
- Faults, Persistence, Retries, and Reasoning Boundaries
- Practical Prototype — Explain One Execution
- Completion Checklist
- Five Useful FAQs
- Official References Inspected
- Finally — Summary
3. Before You Begin — Evidence and Scenario
3.1 Documentation baseline
Keep these version concepts separate:
- OIC release: the Oracle Integration service release running in your instance.
- Thinking-pattern version: the version of the selected ReAct or Plan pattern recipe associated with the agent. Pattern recipes and their versions are separate from the OIC service release.
- LLM/model version: the provider's model selected in the pattern connection.
- API version: the version of an API operation, where a public REST operation exists.
3.2 What you need
For the diagnostic exercise, have access to an OIC project containing an active AI Agent, its thinking pattern, and at least one integration registered as an agentic AI tool. You should also have permission to observe the agent instances and the integration instances involved.
You do not need to create a new agent or tool. The investigation starts with an existing execution. If your project has no execution yet, first confirm that its configured tools are read-only or isolated test substitutes, then use the Test Agent page with synthetic data. A synthetic prompt can still invoke real integrations; it does not make a write-capable tool harmless.
The OIC documentation describes these useful locations:
Begin with Projects in the OIC navigation pane and select the project. The paths below are within that project. They refer to project AI Agents in Oracle Integration 3; do not apply them to a different OCI service console or to the OIC connectivity agent.
| OIC location | Evidence to inspect |
|---|---|
| Project → Design tab → AI Agents page → Agents box → Actions → Run | Opens Test Agent. Inspect the visible System, User, Tool, and Assistant entries and the Activity details for the selected run. |
| Project → Observe tab → AI Agents page → Agent instances tab | Agent name, Conversation ID, status, user prompt, and duration. |
| Project → Observe tab → Integrations page → Integrations tab | Integration-level message counts for the system-generated and business-tool integrations involved in the run. |
| Project → Observe tab → Integrations page → Instances tab | Individual integration execution status, activity stream, and available message payloads and error details. Payload visibility depends on tracing, retention, and access; a successful run does not guarantee that every payload is available. |
Oracle's Run and Test the AI Agent guide explains the test view. The Projects Workspace guide describes the Observe pages.
3.3 Our synthetic procurement request
We will use one consistent example throughout the article:
Business request
Investigate purchase order PO-5821. Was the delivery late? Check the supplier evidence, compare the committed and actual delivery dates, and recommend the next procurement action. Do not change the order.
Assume the procurement agent is configured with a tool that retrieves delivery evidence. For the example, its illustrative tool identifier is resolve-delivery-evidence. Its input parameter is poNumber.
The hypothetical supplier data is:
{
"poNumber": "PO-5821",
"status": "DELIVERED",
"promisedDate": "2026-11-07",
"actualDeliveryDate": "2026-11-09",
"lateByDays": 2,
"source": "SUPPLIER_ERP"
}
This is original synthetic data. The task is read-only: the agent must report the evidence, not update the purchase order.
Define the example before interpreting it: both values are date-only calendar dates under one agreed delivery-date convention. Subtracting 7 November from 9 November gives two calendar days, not two business days or a measured 48-hour interval. We assume one relevant delivery and no revised commitment, grace period, partial shipment, or dispute about the delivery milestone. A real procurement rule must define those cases before declaring a contractual breach or applying a penalty.
The lateByDays and source properties are custom example fields. Recompute the date difference and confirm the returned poNumber matches the request. A source label in JSON is an assertion in the payload; corroborate it with the actual target invocation if source provenance matters. The recommendation is buyer review, not an automatic order change.
4. Reconstructing the ReAct Execution Lifecycle
4.1 First understand what ReAct means
An AI Agent is an application that uses a language model to interpret a request, choose from available actions, and use the returned information to continue toward a task outcome. A Large Language Model (LLM) is the model that processes the supplied messages and generates a response. A tool is an operation the agent can request to obtain information or perform an action outside the model itself.
ReAct means Reasoning and Acting. As a general agent design pattern, ReAct alternates between selecting an action, receiving an observation, and deciding what to do next. Rather than preparing every action in advance, the agent can use new information to choose its next step.
Kid-friendly analogy
Imagine a student solving a puzzle. The student checks the first clue, tries a move, sees whether it works, and then chooses the next move. The student does not have to know every move before starting.
In this OCI AI integration, this means: The ReAct pattern enables the agent to request a tool, use the returned observation, and continue the agent's execution rather than treating the first model response as necessarily final.
Oracle distinguishes four supplied pattern recipes: ReAct and Plan for non-OCI Generative AI models, plus ReAct for OCI GenAI and Plan GenAI for OCI Generative AI models. The selected recipe must match the model/provider configuration documented for that pattern. With ReAct, the agent prompts the LLM for an action, acts, uses the result, and repeats. Here, using a result means supplying task context; it does not mean retraining the model. Oracle describes Plan as producing a plan for stepwise execution, and separately says the Plan and ReAct patterns must be orchestrated in sequence. Selecting a Plan recipe alone should not be presented as a complete planner-and-executor implementation. This article follows ReAct because the diagnostic objective is to understand a sequence of tool requests and observations.
For the documented ReAct setup, Oracle creates a system-generated integration named ReAct Pattern Intg when the pattern is saved. Oracle states that this integration is required by the agent and does not need to be changed or edited. Treat it as a system-managed runtime component, not as an ordinary business integration to customize casually. Confirm the generated integration name in the project and pattern version you are actually using.
The pattern also has a Max iterations setting. An iteration limit constrains the number of reasoning and action steps before the agent provides a final answer or exits. It helps prevent an endless loop, but it is not a guarantee that the requested business task will be completed. Inspect the actual configured value rather than assuming a default.
References: Configure the Agentic AI Thinking Pattern.
4.2 Understand the visible Test Agent records
Open the relevant project, select Design → AI Agents, select the agent, and run it. The Test Agent page displays activity associated with the run.
Oracle documents four important labels in this view:
| Visible label | What it represents | Diagnostic use |
|---|---|---|
| System | The system-prompt content sent to the LLM, including the agent role, agent guidelines, and thinking-pattern guidelines. | Check the instructions and the agent's supplied tool context. |
| User | The user's natural-language input. | Confirm what task the agent was asked to perform. |
| Tool | The response returned from the tool. | Compare the returned data with the actual tool integration result. |
| Assistant | The visible assistant response. Oracle's page describes this display as showing agent reasoning. | Use the visible explanation and conclusion as trace evidence, not as access to private model reasoning. |
These labels are useful, but they are not a full substitute for the integration execution records. A visible tool response does not independently prove that the target system completed the intended business operation. Correlate the agent activity with the corresponding OIC integration instance.
4.3 Follow one complete execution
For the synthetic PO-5821 request, the expected logical sequence is:
Conceptual execution sequence — not a screenshot of OIC internals
System instructions and the user's PO-5821 question are supplied to the model.
The model selects the delivery-evidence tool and supplies
poNumber = PO-5821.The registered tool integration receives its input and calls the supplier system.
The supplier response reports delivery on 9 November against the 7 November commitment.
The agent uses the available observation to prepare its next response or request another action.
The final response identifies the two-day delay and recommends review without changing the order.
This is the logical ReAct story. A real run can contain more than one model request, more than one tool invocation, an error branch, or an asynchronous pause. The actual execution count and order must come from your run evidence.
For example, the model might first ask for delivery data, then ask for a policy lookup, and finally prepare a recommendation. Do not compress that into one tool call merely because the final response mentions only one conclusion.
5. Identifiers, Working Memory, and Tracking
5.1 Why identifier correlation matters
A single agent conversation can span multiple agent instances. A tool integration invocation also creates its own integration instance. These identifiers describe related but different runtime objects.
A Conversation ID identifies the logical agent conversation. OIC generates one by default unless a value is supplied. Reusing the same Conversation ID across runs associates those requests with the same conversation and allows the agent to have knowledge of previous prompts, data, and decisions.
An Agent instance represents an individual execution record. A tool integration instance ID identifies the OIC integration execution that implements the selected tool. A model-provider tool-call identifier, when exposed by a provider or trace, is another correlation value and must not be assumed to be the OIC integration instance ID.
Kid-friendly analogy
Think of a school project. The project has one shared folder, each work session has its own attendance entry, and every student assignment has a separate submission receipt. They are connected, but none of those labels means the same thing.
In this OCI AI integration, this means: Use the Conversation ID to connect agent runs, the agent instance record to inspect a particular run, and the tool integration instance ID to find the execution of a particular tool.
Use this correlation table when investigating a run:
| Identifier | What it identifies | Where to investigate |
|---|---|---|
| Conversation ID | The logical agent conversation, potentially across multiple runs. | Agent activity information and Observe → AI Agents. |
| Agent instance ID | A particular agent execution record. | Agent test activity and the relevant Observe record. Preserve the exact displayed label. |
| Tool integration instance ID | The execution of the integration registered as the tool. | Observe → Integrations → Instances. |
| Provider tool-call ID | A model/provider-level identifier for a requested tool call, where exposed. | The relevant provider or model response record, if available. |
Oracle documents that a Conversation ID can span multiple instance IDs. A conversation that is already in progress, or has status Waiting for tool to process, cannot simply be started again using the same Conversation ID. AI Agent data follows the service-instance data-retention period.
Reference: Run an AI Agent with Knowledge of Previous Runs.
5.2 What is working memory?
Working memory is a general AI-agent design term for the information made available while the agent is working on its current task. It can include the current user request, relevant earlier messages, tool requests, tool observations, and other context selected for a subsequent model invocation.
For example, after the supplier tool returns the delivery date, a subsequent model request may receive the original question and the new supplier observation. That lets the model compare the two dates. The important question is not merely whether OIC recorded the tool response, but whether the next model request actually received the information needed to continue.
Kid-friendly analogy
A student keeps a small notebook while solving a maths problem. The student writes down the question, a useful clue, and the result of a calculation so the next step can use them.
In this OCI AI integration, this means: Treat the context assembled for the next LLM request as the evidence of what the model was given. Do not assume that every recorded event automatically becomes part of that context.
OIC's Conversation ID capability documents continuity across agent runs. It does not, by itself, document the precise internal representation of every context item sent to every model request, nor does it guarantee byte-for-byte replay of a complete transcript on each invocation.
5.3 What is tracking?
Tracking is an observability concept: recording events or values so an engineer can inspect what happened. A tracked response can be useful evidence even when it is not included in the next LLM request.
Consider two separate data flows:
- Tracking flow: an LLM response is copied into a record used for inspection.
- Context flow: an LLM response or tool observation is included in the message or request structure used by a later model call.
Those flows can be connected, but they do not have to be. One record can be written to tracking only. Another can be added to the context and also tracked. A record can also be neither retained in the tracking structure nor supplied to a later model call.
Kid-friendly analogy
Imagine a teacher writing a student's answer in a class register. The register proves what the student wrote, but it is not automatically the notebook the student uses to solve the next question.
In this OCI AI integration, this means: A value visible in tracking shows that it was recorded at that point; inspect the later request construction and available outbound request before concluding that the model received it again.
5.4 How to determine whether an LLM Response activity is tracking-only
The supplied article refers to an activity named LLM Response. That label alone establishes neither its existence in your pattern version nor its data flow. If a matching-version integration or export contains it, investigate whether it records a response, contributes to later context, or does both.
Do not infer that an activity is tracking-only simply because its label contains the word Tracking. Inspect the complete data flow:
- Obtain the relevant project export or permitted view of the generated ReAct integration. Record the integration name and version. Do not modify a system-generated pattern integration merely to investigate it.
- If an activity named
LLM Responseexists, locate it and inspect its mappings, assignments, collection updates, branches, and loop behavior. If it is absent or renamed, identify the response-handling activity from the actual flow; do not invent a replacement activity name or click path. - Follow the response value after that activity. Determine whether it is appended to a tracking structure, a context/message structure, both, or neither.
- Inspect the mapping that assembles the input to the next LLM invocation. Follow the source elements all the way into the request payload or message collection.
- Compare the matching-version mapping with any available captured outbound model request. A mapping establishes the configured data path; the executed branch and actual request establish what was sent in that run. If the request is unavailable, report that limit. The displayed activity stream alone cannot prove the complete later request.
The result should be classified using evidence, not the activity name:
| What the mapper establishes | Defensible conclusion |
|---|---|
| Response goes to tracking; next LLM request does not consume that value. | The response is tracked but is not shown to be replayed through that next request mapping. |
| Response is added to the context structure and consumed by the next LLM request. | The inspected flow includes the response in the next model request. |
| Response is copied to both structures. | The response is both tracked and included in the inspected later context. |
| Only the response activity is visible; downstream mappings or runtime requests are unavailable. | The later-context conclusion remains unresolved. Seeing a value at one point does not establish its retention duration or replay policy. |
Why this matters: a displayed LLM response can make a run appear to have retained information even when the next model request does not contain it. Equally, a response can be passed forward without being preserved in a tracking structure. The complete mapping path supports a design conclusion; a matching runtime request is stronger evidence of what the model actually received in a particular execution. Neither alone proves how the model used each value internally.
6. Investigating Tool Selection, Arguments, and Lost Context
6.1 When the agent selects an unexpected tool
The model does not select a tool from its display name alone. In OIC, a registered agentic AI tool has an Identifier and a Description. Oracle documents that the identifier is sent to the LLM as tool metadata and that the description is supplied as part of the system prompt. The tool's Name is not sent to the LLM.
The optional Guidelines field also influences the LLM's tool-use decision. Guidelines are instructions to the model; they are not a replacement for authorization controls in the tool integration or target application.
To investigate an unexpected selection, open the project tool definition and verify:
- Identifier: Does it describe the intended tool unambiguously?
- Description: Does it explain the task the tool performs and when it should be used?
- Guidelines: Do they state relevant use and non-use conditions?
- Visible parameters: Are only the parameters needed by the model exposed?
- Parameter descriptions: Do they explain the meaning and expected format of each exposed value?
For example, a tool described as “retrieves supplier shipment evidence for a purchase order” is more precise than “checks supplier information.” A vague description gives the model less information for distinguishing it from unrelated supplier or invoice tools.
Reference: Register an Integration as an Agentic AI Tool.
6.2 When the tool arguments are incorrect
A model-generated argument is a proposed value, not a validated business fact. Suppose the user asks about PO-5821 but the tool invocation receives PO-5281. The correct investigation is to compare the original user input, the visible model tool request, the tool integration's inbound request, and the target system query.
OIC's tool configuration provides parameter controls with different purposes:
| Tool parameter setting | Diagnostic meaning |
|---|---|
| Visible | Controls whether the parameter is sent to the LLM. Do not expose internal fields unnecessarily. |
| Required | Indicates that the LLM must assign a value to the parameter. |
| Constant | Supplies a fixed value that the LLM does not decide. |
| Default Values | Provides a configured default when a safe default is appropriate. |
| Enum Values | Lists the configured comma-separated choices for the model. Validate membership in the integration as well; do not treat model-facing metadata as a universal server-side enforcement guarantee. |
| Description | Explains what the parameter means so the LLM can assign a suitable value. |
These settings help shape tool selection and arguments, but they do not replace server-side validation. Your integration must still validate that the purchase order exists, that the caller is permitted to retrieve it, and that the value meets the target application's format and business rules.
For a read operation, compare the tool request and the supplier system response. For a write operation, also verify authorization, duplicate protection, and the actual target-side result before deciding to retry.
Find the first mismatch: if the visible tool request already contains PO-5281, investigate the model input and tool metadata. If that request contains PO-5821 but the integration receives or forwards PO-5281, investigate dispatch and mapping at the first evidenced change. If the target query is correct but the response identifies another PO, investigate the target contract or response mapping. When a stage is unavailable, leave that boundary unresolved instead of assigning blame.
Use this when: the final answer names the wrong order, a required argument is absent, or the agent repeatedly chooses a neighbouring supplier tool. Change only the responsible metadata or mapping after capturing the baseline. A prompt is not an authorization boundary: enforce the read-only scope in the tool and target permissions, and treat supplier-provided text as data rather than instructions.
6.3 When the agent appears to lose context
Suspected context loss means that information needed for the next step may be absent, inaccessible, transformed, or omitted from the relevant model request. A wrong answer alone does not establish that this happened: the information might have been present but misinterpreted. It is not enough to observe that an earlier response exists somewhere in OIC.
Investigate the following questions in order:
- Was the next run associated with the intended Conversation ID?
- Did the earlier run reach a state that allowed a subsequent run?
- Was the previous tool result returned successfully?
- Does the next request construction include the earlier information?
- Does the prompt or pattern configuration preserve enough context for the task?
- Has the service-instance retention period affected the availability of earlier conversation data?
Oracle documents conversation continuity across runs using the same Conversation ID. It does not make every internal context-construction detail visible in the conversation ID field. If the problem depends on which exact messages were replayed, inspect the next LLM request mapping and the available activity evidence.
6.4 When the agent finishes too early
A completed runtime status means that the agent execution has reached a terminal runtime state. It does not independently prove that the business task was correctly completed.
For PO-5821, the agent might return “Delivery information is unavailable” even though the supplier tool never ran. Or it might return “Delivery was on time” after using a different PO number. Both cases could produce a final assistant response, but neither satisfies the requested business outcome.
Investigate these possible causes:
- The model selected a final response rather than a tool.
- The tool was selected but the dispatch or integration failed.
- The tool returned data that was not included in the next model context.
- The model produced a conclusion that misinterpreted the tool observation.
- The configured Max iterations limit was reached.
- A fault-handling branch or mapping transformed an error into a response that allowed the flow to exit.
Do not diagnose premature completion from the final sentence alone. Reconstruct which of these stages actually occurred.
Use this when: the agent gives an answer before a required lookup, forgets a constraint on a later turn, or stops after an incomplete result. Preserve the original run, configured iteration value, and actual tool evidence. Do not assume an OIC-specific truncation, compression, or replay algorithm that the inspected documentation and artifacts do not establish.
7. Understanding Asynchronous Tool Callbacks
7.1 What changes when a tool is asynchronous?
A synchronous tool normally returns its result during the tool invocation. An asynchronous tool starts work that finishes later. Instead of keeping the same request waiting for the entire external operation to complete, the agent waits for a response to arrive through a callback.
Kid-friendly analogy
A student asks the school office to find an old certificate. The office says it needs time and gives the student a reference number. Later, the office sends the certificate back using that reference.
In this OCI AI integration, this means: An asynchronous agentic tool can pause the agent while an external operation runs, then resume the agent when the callback supplies the result and the correct correlation values.
Oracle documents that when the AI Agent invokes an asynchronous agentic AI tool, the agent stops reasoning and displays the status Waiting for tool to process. It resumes reasoning only after it receives a response through the callback. A callback can be sent only while the associated conversation is in that waiting status; a callback is not a general mechanism for injecting a message into any conversation state.
The documented callback mechanism is an OIC AI Agent action named Callback AI agent. This callback procedure applies to asynchronous agentic AI tools that do not call Human in the Loop; Oracle states that callback is implemented automatically for Human in the Loop. It is not necessary to invent a separate public REST endpoint for this action.
7.2 The complete callback sequence
Assume the supplier evidence service takes time to prepare the PO-5821 response. The business tool integration is configured as an asynchronous tool, and a separate callback integration returns its completed result.
- The agent invokes the asynchronous tool integration.
- The tool integration starts the external operation and captures the correlation information needed for the callback.
- The agent remains in
Waiting for tool to process. - The external application completes its work and invokes the callback integration.
- The callback integration uses the native AI Agent action with operation Callback AI agent.
- The callback action sends the correlation identifiers and the response payload.
- The agent resumes and uses the returned observation to continue its ReAct execution.
7.3 Configure the native callback action
The asynchronous tool must first exist as a valid agentic AI tool. Oracle documents that an integration registered as a tool must belong to a project, be active, and use a REST Adapter trigger as its first connection. The trigger must use OAuth authentication, a JSON payload, and an HTTP method supported by the REST Adapter: GET, POST, PUT, DELETE, or PATCH.
The callback integration is a separate integration that sends the result to the waiting agent.
In the callback integration, add an AI Agent action. In Configure Basic Info, give the endpoint a meaningful name and select Callback AI agent as the action. Click Continue. In Configuration, select the current project or a shared project containing the agent, then select the AI Agent; only agents with status Active are listed. Click Continue, then Summary → Finish. OIC creates a map for the action.
Oracle documents these callback parameters:
| Callback parameter | Value to map |
|---|---|
| Conversation Id (required) | The Conversation ID of the agent run that invoked the asynchronous tool. |
| Tool Flow Id (required) | The integration instance ID of the asynchronous tool invocation. |
| Tool Invoke Event Id (required) | The same value as Tool Flow Id: the tool integration instance ID. |
| Payload (required) | The response to send back to the agent, supplied as stringified JSON. |
The callback documentation describes two important runtime values:
The mapper also provides optional Project Id and Agent Id overrides. Leave them unset when the wizard selection is correct. If you use them, preserve evidence that they identify the same intended waiting agent and project. These are documented mapper inputs, not permission to construct an undocumented external callback URL.
- On the asynchronous tool integration’s REST trigger, add the
x-agentic-callback-uriheader. At runtime Oracle populates it with the agent callback URL, typically containing aconversationIdquery parameter. Parse the actual URL, extract and URL-decode itsconversationIdquery value, and persist it in a durable location, such as a database or file, so the later callback integration can retrieve it. Do not assume a fixed host, parameter order, or complete URL format from the example. - Read the tool integration’s runtime instance ID from the mapper’s Integration Metadata section. Persist that ID with the conversation correlation data. Map it to Tool Flow Id and map the same value to Tool Invoke Event Id; Oracle requires both fields to be mapped.
For the synthetic PO-5821 exercise, imagine the tool integration instance ID is TOOLINST-742, and the Conversation ID is CONV-EXAMPLE-001. These are invented values solely to illustrate the mapping. In a real delayed workflow, store the pair together with a business correlation key; do not rely on an in-memory value that may be lost before the callback executes.
Complete the handoff in your own integration contract: assign the external job a correlation key and store it with the original Conversation ID, tool integration instance ID, intended project/agent, and processing state. When the external completion event arrives, use that key to load the original values. Do not use the callback integration's own instance ID as the tool ID, and do not correlate by PO number alone if several investigations of the same PO can overlap.
This durable lookup is a recommended application design, not a built-in correlation table supplied by the callback action. Your external service's completion endpoint, authentication, event schema, timeout policy, and duplicate handling are not supplied in the article. Configure them from that service's real contract; the Oracle action does not create that external completion route for you.
The callback payload could contain the supplier result:
{
"poNumber": "PO-5821",
"status": "DELIVERED",
"promisedDate": "2026-11-07",
"actualDeliveryDate": "2026-11-09",
"lateByDays": 2,
"source": "SUPPLIER_ERP"
}
This example is the custom JSON content carried in the callback action's Payload value. It is not a published wire-level callback REST request contract. Oracle documents the payload as stringified JSON and does not require one fixed business JSON schema.
Object versus string: the preceding block shows the business object. The callback Payload input must receive JSON serialized as text. For example, serializing a smaller illustrative object gives this JSON string literal:
"{\"poNumber\":\"PO-5821\",\"lateByDays\":2}"
The outer quotation marks and escapes illustrate a string represented inside JSON; they are not instructions to paste extra backslashes into a mapper. Serialize once using the mechanism supported by your actual source and target types. Inspect the mapped value to detect an unconverted object or a twice-encoded string. The exact mapper expression cannot be supplied without that schema.
Click Validate, return with Back, and click Save; then activate the callback integration. When the external application completes its work, invoke that callback integration with the appropriate values. Then verify both sides:
- The callback integration instance processed successfully.
- The agent no longer remains indefinitely in
Waiting for tool to process; inspect its later activity and terminal status.
Reference: Send a Response to an AI Agent with a Callback and Use Case: Send a Callback to an AI Agent for an Asynchronous Tool.
7.4 How to diagnose a callback problem
If the agent remains in Waiting for tool to process, do not immediately rerun the agent. First inspect the asynchronous tool integration and callback execution.
| Symptom | Check | Correction |
|---|---|---|
| Agent stays waiting. | Did the external operation finish? Was the callback integration invoked? | Complete the external operation and send the callback using the original correlation data. |
| Callback integration errors. | Are Conversation Id and the two tool identifiers correctly mapped? | Compare the values against the agent run and actual tool instance. |
| Callback executes but agent does not continue as expected. | Is the callback for the correct waiting conversation and tool invocation? | Verify the original run, callback inputs, and activity stream before attempting recovery. |
Do not assume that a callback request being accepted proves that the agent has completed its business task. Callback delivery, agent resumption, and final business correctness are separate checkpoints.
Observe the continuation: capture the callback action result, the original waiting conversation, subsequent agent activity, and the final answer or later fault. Oracle's callback use case shows a continuation with the business identifier Callback flow; use that as a documented example, not a guaranteed identifier in every recipe. A successful HTTP response from your own callback wrapper is not sufficient if its fault handler concealed an action failure.
Use this when: a long-running supplier lookup finished but the agent still waits. Establish whether the callback was never sent, failed correlation, or resumed into a later fault. Do not send repeated callbacks to a non-waiting conversation or promise duplicate-callback safety without a documented contract.
8. Retrieving the AI Agent Activity Stream
8.1 What an activity stream tells you
An activity stream is a chronological record of observable activity associated with an execution. In an agent investigation, it helps connect the conversation to actions and state transitions, such as a tool request, a response, or a waiting status.
Do not confuse the agent activity stream with the activity stream of an individual OIC integration instance. They answer different questions:
- The agent activity stream helps explain the agent conversation and its status.
- The integration activity stream helps explain what an individual integration instance processed, including relevant payload and error evidence.
8.2 Native OIC action: Get AI agent activity stream
Oracle documents a native AI Agent action named Get AI agent activity stream. This operation is available from the AI Agent action in an OIC integration.
To implement the retrieval route:
- Open an integration in the project and add an AI Agent action from the canvas.
- In Configure Basic Info, enter a meaningful endpoint name, such as
getActivityStream. - For Action, select Get AI agent activity stream.
- Click Continue, then Summary → Finish, and open the generated mapper.
- Map the intended Conversation ID from your source to the generated AI Agent action input. The source may be your integration trigger or an earlier action that started the agent; use the actual generated elements.
- Validate, save, and activate the integration.
- Invoke it with the Conversation ID of an agent run and inspect the result. Oracle documents that the response status indicates the current status of the AI Agent.
For a production implementation, make the Conversation ID an explicit input to the integration contract. Do not hardcode a value from a developer's test run. Apply appropriate caller authorization and avoid exposing conversation activity to users who are not entitled to inspect it.
Finish the surrounding integration: the AI Agent action alone does not publish a monitoring API or return data to a caller. For a request/response wrapper, define its REST trigger and authentication, expose a Conversation ID input, invoke the action, and map the generated action output into the trigger response. For a scheduled integration, define where the result will be written. These are application design steps; the complete trigger/response schema and output mapper paths must come from the actual integration.
Use your permitted integration test route or its configured endpoint to run the completed wrapper with a real test Conversation ID. Capture the response and compare its status and available activity with the same conversation in OIC. Record retrieval time: a waiting or in-progress result is a snapshot, not proof that the execution will eventually finish.
Reference: Get the Activity Stream for an AI Agent.
9. Faults, Persistence, Retries, and Reasoning Boundaries
9.1 Separate the possible failure layers
One agent run can involve several different components. A single final error message can hide the component where the failure occurred. Investigate the layer that owns the failing operation.
| Layer | Evidence to inspect | Typical diagnostic direction |
|---|---|---|
| Model / thinking pattern | Agent activity and ReAct Pattern Intg instance. |
Check the configured LLM connection, model availability, request construction, and the integration error details. |
| Tool selection / dispatch | Visible assistant/tool request, Get Tool Data Intg activity, and tool instance records. |
Check the selected tool identifier, available tool metadata, and whether dispatch reached the expected integration. |
| Tool integration / mapping | The tool integration request mapper, inbound payload, invoke mapping, and instance error details. | Compare the original argument with the values actually passed to the target. |
| External system | The target response, its correlation value, and any target-side transaction record. | Check authorization, business validation, service availability, and whether the requested operation completed. |
| Callback / conversation continuation | Callback integration instance, callback mappings, and agent waiting/resumption status. | Verify Conversation ID, Tool Flow Id, Tool Invoke Event Id, and the returned payload. |
| Context / state handling | The relevant assignments, collection updates, next LLM request mapping, and available conversation history. | Determine whether the required information was actually retained and consumed by the next step. |
9.2 An external action can finish before agent state is safely continued
Consider a tool that updates a purchase order. The external system might commit that update successfully, while a later callback, response mapping, or agent continuation fails. The agent may not have a completed conversation record reflecting the successful business action.
This is a distributed execution boundary. The external application and the OIC agent conversation are separate processing components. Unless a specific documented transaction mechanism provides a shared atomic commit, do not assume that the external business action and the subsequent agent-state update succeed or fail as one indivisible transaction.
Kid-friendly analogy
A shop assistant successfully hands a parcel to a courier, but the computer stops before recording the dispatch. The parcel has moved even though the computer still shows an incomplete record.
In this OCI AI integration, this means: A completed external business operation does not prove that the later tool response, callback, or agent conversation state was also saved successfully.
For operations with side effects, design for this uncertainty:
- Use a stable business key or idempotency key where the target operation supports it.
- Record the target-side transaction reference before attempting recovery.
- Before resubmitting, query the target to determine whether the action already completed.
- Separate a retry of an idempotent read from a repeat of a financial or operational write.
- Reconcile the external state with the agent conversation rather than assuming a replay will restore the missing state.
Beginner terms: a side effect is an external change such as an order update. An idempotent operation has the same intended effect when repeated with the same request; that does not mean its logs or response timestamps are identical. An idempotency key helps a target recognize repeated attempts at one business operation only when the target implements that contract. Merely repeating a locally stored key provides no duplicate protection by itself.
9.3 What can you infer about retries?
Inspect the visible fault-handling coverage in the actual tool integration, callback integration, and any custom pattern components. Look for explicit scope-level fault handlers, retry branches, wait logic, resubmission paths, and duplicate-prevention controls.
Keep these separate:
- Visible retry logic: logic explicitly present in the inspected integration or workflow.
- Adapter behavior: retry behavior associated with a particular adapter and operation, where documented.
- Agent behavior: whether the agent requests another model action after an observation or error.
- Platform recovery: behavior that cannot be inferred from a visible export unless Oracle documents it or runtime evidence establishes it.
9.4 Visible execution evidence is not private chain-of-thought
Chain-of-thought refers to internal reasoning processes that may not be exposed as ordinary user-facing output. An OIC Test Agent display, assistant message, activity entry, or integration payload is observable execution evidence. It is not a guarantee of access to every internal model computation.
For example, a visible Assistant entry might state that delivery evidence is required and then show a tool request. A valid diagnosis can say:
“The visible assistant activity requested the delivery-evidence tool with PO-5821. The corresponding tool integration instance returned the supplier dates. The subsequent assistant entry reported a two-day delay.”
That statement is grounded in visible evidence. It does not claim to reproduce hidden model thoughts.
9.5 Use diagnostic tracing carefully
Integration-level activity streams and payload traces can expose useful request and response evidence. However, Oracle warns that Audit and Debug tracing can affect performance, and payload tracing can retain sensitive data. Oracle strongly discourages enabling Audit or Debug tracing in production. Payload availability must therefore be established from the actual run, not assumed.
When additional evidence is required, use the narrowest permitted scope and duration. Use synthetic or redacted data where possible. Do not put API keys, credentials, unnecessary supplier personal information, or full confidential prompts in routine business identifiers or alert messages. Restore the intended tracing level after the investigation.
Preserve existing evidence before configuration changes. Oracle's deactivation guidance warns about loss of history and runtime data, and about pending asynchronous messages. Do not deactivate a generated pattern integration merely to inspect its mapping. Use a permitted read-only view or matching-version export; if that access is unavailable, state the gap instead of inventing an editing route.
Reference: Activate and Deactivate Integrations — Manage Tracing Levels.
10. Practical Prototype — Explain One Execution
10.1 Build an evidence timeline
Now combine the concepts into a single investigation. The values below are illustrative. They show the kind of evidence to collect and how to explain it; they are not captured runtime results from an OIC tenant.
To perform the exercise on an actual permitted test execution:
- Select one existing run, or use Projects → selected project → Design → AI Agents → Agents → Actions → Run. Verify the tool capabilities first; then submit the synthetic procurement request with Send prompt to agent.
- Record the project, agent, pattern, and tool integration names and versions, the tenant release, the Conversation ID, and any separately displayed agent instance ID. Keep the original labels beside each captured value.
- Capture the visible System, User, Tool, and Assistant entries. If tool arguments are exposed, record the selected identifier and
poNumber. An assistant sentence saying it will call a tool is weaker evidence than an actual tool request and matching execution. - Use Observe → Integrations → Instances within the project to locate the matching tool execution. Match identifiers and PO values, and record the inbound request, target request/response, status, and available fault details. Nearby timestamps or aggregate message counts alone do not establish a match under concurrency.
- For an asynchronous run, also collect the durable correlation lookup, callback inputs, callback result, and subsequent agent activity. For a claim about the next model input, collect the matching-version construction and available actual outbound request.
- Write one timeline with timestamps and time zones, the source of each record, and any missing evidence. Use the illustrative table below as a worksheet, replacing fictional IDs with actual captured values. Mark a missing correlation as unresolved.
Do not fabricate timestamps or fill an absent payload from the expected example. Not observed means the evidence is unavailable or incomplete; it does not necessarily mean the event did not happen. If two records cannot be reliably correlated, stop that part of the conclusion at the last established boundary.
| Order | Event | Evidence and interpretation |
|---|---|---|
| 1 | Agent receives user request. | User asks whether PO-5821 was delivered late and explicitly prohibits an order update. |
| 2 | Model receives configured instructions. | The illustrative System entry contains role and guideline information. Its display order is not a transport-level timestamp sequence; preserve actual timestamps separately. |
| 3 | Model requests a tool. | The visible tool request selects resolve-delivery-evidence and supplies poNumber = PO-5821. |
| 4 | OIC tool integration runs. | A hypothetical integration instance TOOLINST-742 processes the input and invokes the supplier system. |
| 5 | Supplier response is returned. | The result reports delivery on 9 November against a commitment of 7 November. |
| 6 | Agent receives an observation. | The visible Tool response can be correlated with the supplier result and the tool integration instance. |
| 7 | Agent produces a final response. | The visible Assistant response identifies a two-day delay and recommends buyer review. |
If the tool were asynchronous, insert the callback events between steps 4 and 6. The agent would enter Waiting for tool to process, the external operation would complete, and the callback integration would send the response using the original conversation and tool identifiers.
10.2 Interpret what was received, requested, executed, and retained
Use this four-part inspection worksheet:
| Question | Evidence to collect |
|---|---|
| What did the model receive? | Visible System and User entries, plus the inspected context/request mapping for the relevant model invocation. |
| What did the model request? | Visible tool identifier and arguments, where available in the agent activity. |
| What actually happened? | The tool integration instance, target response, callback integration if applicable, and their statuses. |
| What was available to the later request? | Conversation history, matching-version tracking/context mappings, and any captured next model request. State separately what was configured, what was sent, and what retention remains unknown. |
These questions prevent four common diagnostic errors:
- Calling a tool request a successful tool execution.
- Calling a tracked response model context.
- Calling an agent terminal status proof of business correctness.
- Calling a visible assistant explanation the model's complete internal reasoning.
10.3 Example execution narrative
Illustrative diagnostic narrative — not an observed tenant execution
The procurement agent received a request to investigate PO-5821. Its visible system instructions supplied the procurement role and the relevant tool-use guidance. The user's request asked for the committed and actual delivery dates and prohibited any order update.
The visible agent activity showed a request to invoke the delivery-evidence tool with poNumber = PO-5821. The associated tool integration instance was identified separately from the Conversation ID. The tool's synthetic supplier response reported delivery on 9 November against the promised date of 7 November.
The returned observation was then visible in the agent activity, and the final assistant response reported a two-calendar-day delay and recommended buyer review. No order update was part of this example.
The evidence supports the conclusion that the agent requested the correct read operation, the tool response contained the two relevant dates, and the final visible response interpreted those dates as a late delivery. It does not, without mapper evidence, establish precisely how every intermediate LLM response was persisted or replayed.
10.4 Test the diagnostic method
Use the following tests to check whether your execution story is supported by the records. These tests are Not executed against a tenant in this tutorial.
| Case | Expected diagnostic result | Evidence to inspect |
|---|---|---|
| Positive: valid PO-5821 request. | Correct tool request, correct tool execution, consistent dates, and a final response aligned with the evidence. | Test Agent entries, tool integration payload, target response, and final status. |
| Boundary: nonexistent PO number. | A controlled not-found or validation response, with no unsupported assumption that the purchase order exists. | Tool request argument, target result, and model interpretation. |
| Failure: tool integration returns an error. | The tool failure is visible and is not presented as a successful supplier lookup. | Integration instance details, fault handler, and agent activity following the fault. |
| Correlation: proposed callback uses an incorrect tool instance ID. | First compare IDs offline. Any deliberate negative callback test belongs in an isolated waiting test conversation; record the actual result without assuming an error code or recovery behavior. | Original tool instance ID, callback Tool Flow Id, Tool Invoke Event Id, and Conversation ID. |
| Context: suspected tracking without later request inclusion. | Compare the later request with the earlier value. A proven omission differs from an unavailable request; mark unavailable evidence inconclusive. | LLM Response output mapping, assignments, and next LLM request construction. |
A small number of tests is useful for diagnosing a particular run, but it does not certify overall model accuracy. For production evaluation, retain representative examples of correct tool choices, incorrect tool choices, argument errors, context omissions, and business outcomes. Review them against the risk of each error type.
11. Completion Checklist
You have completed the learning outcome when you can:
- Explain the ReAct sequence: model request, action, observation, and continuation or final response.
- Identify what the visible System, User, Tool, and Assistant records represent.
- Correlate a Conversation ID with agent execution records and tool integration instance IDs without mixing the identifiers.
- Explain why a tracking record does not, by itself, prove that its contents were supplied to the next LLM request.
- Inspect a tool's identifier, description, guidelines, and parameter settings when investigating incorrect tool selection or arguments.
- Trace an asynchronous callback using Conversation Id, Tool Flow Id, Tool Invoke Event Id, and Payload.
- Use the native Get AI agent activity stream action without mistaking an integration-instance REST endpoint for an agent-conversation endpoint.
- Separate model, dispatch, tool, external-system, callback, and state-handling failures.
- Write a concise execution narrative that distinguishes observed facts from unresolved assumptions.
12. Five Useful FAQs
1. Is the Conversation ID the same as the OIC integration instance ID?
No. The Conversation ID correlates an agent conversation and can span multiple agent runs. A tool integration instance ID identifies the execution of one integration. Preserve both values when investigating a tool invocation.
2. Does a response appearing in tracking mean the LLM will remember it?
No. Tracking provides evidence that a value was recorded. To establish that the next model request received it, inspect the next request's message or context mapping.
3. Does an Assistant entry show the model's complete internal reasoning?
No. It is visible execution or explanatory content in the OIC interface. It can support an explanation of visible decisions, but it does not establish access to every internal model computation.
4. Does a Succeeded agent status prove that the business request was completed correctly?
No. It indicates a successful runtime outcome according to the agent instance status. Validate the tool execution, target-system result, returned observation, and business rules separately.
5. Can I retrieve the AI Agent activity stream through the generic integration activity-stream REST endpoint?
Do not treat the endpoints as equivalent. The deprecated generic REST activityStream operation takes an integration instance ID. The documented agent-conversation retrieval route is the native Get AI agent activity stream action, which accepts a Conversation ID.
13. Additional References
A tenant’s installed release and functional patch must still be verified separately.
- Using Agentic AI in Oracle Integration 3 — product guide and current topic documentation.
- Configure the Agentic AI Thinking Pattern — ReAct and Plan and Execute definitions, Max iterations, and generated pattern integration.
- Run and Test the AI Agent — Test Agent activity labels and runtime investigation.
- Register an Integration as an Agentic AI Tool — tool registration prerequisites, identifier, description, guidelines, and parameter controls.
- Run an AI Agent with Knowledge of Previous Runs — Conversation ID, continuity, and retention.
- Send a Response to an AI Agent with a Callback — asynchronous callback behavior and mapping inputs.
- Use Case: Send a Callback to an AI Agent for an Asynchronous Tool — documented callback execution example.
- Get the Activity Stream for an AI Agent — native retrieval action and Conversation ID mapping.
- Oracle Integration REST API Endpoints — comparison with the generic integration-instance activity-stream resource.
- Retrieve Integration Instance Activity Stream (Deprecated) — GET contract, required service-instance parameter, and recommended alternative.
- Retrieve Integration Instance Activity Stream Details — integration-instance scope and GET request requirements.
- Tour of the Projects Workspace — Observe pages and available monitoring views.
- Activate and Deactivate Integrations — integration tracing levels and operational cautions.
- Oracle Integration 26.07 Release Notes — introduction of the AI Agent activity-stream and callback actions.
- Oracle Integration 26.10 Release Notes — September 2026 release baseline and current feature context.
- Known Issues for Agentic AI — Conversation ID limitation affecting AI Agents created before 26.04 when invoked through an API or AI Agent endpoint.
For additional conceptual context, see Oracle's ReAct vs Plan & Execute article. It is contextual material, not a substitute for the product documentation governing OIC behavior.
Finally — Summary
An OIC AI Agent execution should be explained as a sequence of observable events, not just by quoting its final answer. ReAct provides the action-and-observation pattern, while OIC exposes conversation activity and separate integration-instance records that help reconstruct what occurred. The Conversation ID, agent instance ID, and tool integration instance ID each serve a different correlation purpose.
The most important diagnostic distinction is between what was recorded and what the next model request actually received. A tracking entry is not automatically working context, and a visible assistant explanation is not access to private model reasoning. For asynchronous tools, verify the callback identifiers and the agent's resumption. For failures, identify whether the problem occurred in the model connection, tool dispatch, mapping, target system, callback, or state handling.
A trustworthy execution narrative states what the evidence proves, what it only suggests, and what remains unverified. That is the difference between describing an agent run and engineering a reliable diagnosis.

Comments
Post a Comment