Skip to main content

AI Agent Runtime: How OIC Executes Tool Calls and Returns Business Results

Calculating read time…

Imagine a procurement employee asking an AI agent for the status of purchase order PO-10482. The language model can request an order-status tool and propose an order number. That request does not retrieve a record. In the Oracle Integration 3 (OIC Gen3) project-agent architecture discussed here, an integration performs the business operation and supplies the result.

This article follows that boundary: tool identity, arguments, integration execution, returned data, correlation, and failures. It separates general agent concepts from Oracle-documented configuration and from implementation details that require tenant evidence.

1. What You Will Build

Worked scenario: Ask “What is the current status of order PO-10482?” The illustrative tool Identifier is get-order-status, backed by an integration named Get Order Status. Its read-only business operation accepts the JSON below. POST is the tutorial’s interface choice; the HTTP verb alone does not make an operation read-only.

{
  "orderId": "PO-10482"
}

The integration’s tutorial-defined successful response is:

{
  "orderId": "PO-10482",
  "found": true,
  "outcome": "FOUND",
  "status": "SHIPPED",
  "shipmentId": "SHP-7715",
  "lastUpdated": "2026-11-06T14:20:00Z",
  "message": "Order record retrieved."
}

2. In This Post

3. Before You Begin — Understanding the OIC Components

3.1 What is an agentic AI tool in OIC?

A tool is a callable capability outside a language model, such as retrieving an order. LLM means large language model. The model proposes a tool request; a surrounding runtime executes the capability. That distinction is a general agent fundamental. OIC’s specific implementation here exposes an integration as the tool.

Kid-friendly analogy

Imagine a school library where students cannot enter the locked storage room themselves. They can ask the librarian for a particular book, and the librarian's assistant retrieves it using the library's approved process.

In this OCI AI integration, this means: The agent requests a registered tool, while the OIC integration performs the actual enterprise operation using its configured connections and orchestration.

A REST trigger is the integration’s inbound HTTP interface. A contract defines its accepted request and returned response. Mapping transforms or assigns values between those structures and application messages. OAuth is the token-based authorization mechanism required for this tool-registration path; it does not itself decide which purchase orders an employee may read.

Before following the trace, have an authorized project environment, an active integration eligible for tool registration, a configured and tested model connection, an active thinking pattern, and an agent associated with the tool. Confirm downstream connectivity and test-data access separately. These are readiness checks, not a claim that the example has been provisioned.

3.2 Understand the four important OIC components

ComponentResponsibility
IntegrationImplements the operation, input validation, mappings, and application connectivity.
Agentic AI toolConnects a model-facing capability and its metadata to an integration.
AI agentHolds the role, guidelines, thinking-pattern association, and available tools.
Agent patternImplements the approach for coordinating model decisions and tool observations.

ReAct combines reasoning and acting: request an action, observe the result, and decide what to do next. Plan and Execute separates planning from execution. These are general approaches; section 7 explains Oracle’s documented arrangement.

Official source: Agentic AI in OIC – Overview and Introduction.

3.3 What happens when a ReAct pattern is created?

Oracle lists provider-specific recipes: ReAct for OCI GenAI and Plan GenAI for OCI Generative AI, and ReAct and Plan for other providers. Use the compatible recipe and its connection configuration; do not apply API-key instructions from a non-OCI example to OCI Generative AI without checking that provider’s setup.

The documented ReAct walkthrough creates and automatically activates ReAct Pattern Intg after the LLM connection is saved. The pattern itself must also be Active for agent selection. Oracle describes that integration as system-generated and required; leave it unmodified. Max iterations limits reasoning/action steps, not duplicate business effects.

Official source: Configure the Agentic AI Thinking Pattern.

Official sources: What's New for Oracle Integration 3; September 2026 (26.10); Verify Updates and Feature Availability; Check Whether Your Instance Has Been Updated.

4. Model Tool Selection Versus Actual OIC Execution

4.1 What is a model-generated tool request?

Given an appropriate tool definition, the model may propose an action with orderId set to PO-10482. It may instead ask for missing information or answer without a tool. Tool availability does not guarantee tool selection, correct arguments, or an accurate final answer.

Kid-friendly analogy

Imagine asking a friend to find your lost football. Your friend can say, "I should ask the sports teacher." That decision is not the same as actually visiting the teacher and returning with the football.

In this OCI AI integration, this means: The model's tool selection is the request; OIC must execute the registered integration before the requested business information becomes available.

4.2 The execution boundary

StageMeaningEvidence needed
Model requestA proposed capability and its arguments.Actual structured request or supported activity evidence.
Tool resolution and dispatchThe runtime connects that request to the configured capability.Tool metadata, integration association, and correlated instance.
Business executionThe integration validates input and performs the lookup.Integration request, target response, and mapped result.
Agent observationThe result becomes available for a subsequent answer or action.Tool response and subsequent agent activity.

This is a conceptual architecture, not an asserted list of Oracle internal runtime services. A natural-language statement such as “I checked the order” is not execution evidence.

5. How OIC Resolves the Tool Identifier and Forwards Arguments

5.1 Tool name versus tool identifier

Oracle distinguishes Name from Identifier: Name defaults from the integration name and is not sent to the model; Identifier is project-unique model metadata. Both are locked after creation. In this example, Name is Get Order Status and Identifier is get-order-status. Record the actual saved values.

Kid-friendly analogy

Imagine a school has a room called the Science Room, but its electronic attendance system identifies it using the code SCIENCE-01. The room's name is easy for people to read, while the code identifies the room unambiguously.

In this OCI AI integration, this means: The tool Name helps people recognize the capability, while the unique Identifier is the important model-facing identity used to describe the available tool.

5.2 How are the arguments defined?

Input metadata comes from the integration. For this example, expose orderId as a required string with a clear business description; use no constant, default, or enum. Visible exposes a parameter; Required tells the model to supply it; Constant fixes a value; a default supplies a fallback; enums list alternatives. None replaces integration-side validation.

5.3 Configure the OIC tool for the example

The following is a compact setup path for an existing eligible integration, not a complete adapter or model-provisioning tutorial. Oracle requires project membership, Active status, and a REST Adapter trigger using OAuth and JSON. Supported verbs include GET, POST, PUT, DELETE, and PATCH.

  1. Open Projects, select your project, and find the active integration in Integrations.
  2. Choose Actions → Create agentic AI tool. Review Name, Identifier, and Description; click Create.
  3. On the tool-details page, configure the input metadata described above and click Save.

Official source: Register an Integration as an Agentic AI Tool.

Suggested original description: “Retrieve the latest recorded fulfillment status for one exact purchase order number; this operation performs no business updates.” Suggested guideline: “Ask for a missing order number, preserve the supplied identifier, and report only the returned result.” Guidelines influence the model; enforce these rules in the integration where applicable.

For an existing agent, open its configuration under the project’s AI Agents area. In Tools, click +, select the registered tool, and click Add. Save, return to the agents page, and activate through Actions → Activate. A new agent also requires its role, guidelines, and an Active thinking pattern; use the linked agent-configuration procedure rather than guessing fields.

Official source: Add and Configure the AI Agent.

5.4 Can we inspect the registered tool through REST?

Yes. The Developer API retrieves metadata; it does not execute the tool:

GET /ic/api/integration/v1/projects/{projectId}/ai/tools/{id}?integrationInstance={service-instance}

The path needs the project and Agent Tool identifiers; the design-host route needs the service-instance name. There is no request body. Use an authorized bearer token and your actual design host, not a hostname guessed from a region. URL-encode each substituted path/query value. The service-instance name is available in About.

curl --request GET \
  --header "Authorization: Bearer $OIC_ACCESS_TOKEN" \
  --header "Accept: application/json" \
  "https://<ACTUAL_DESIGN_HOST>/ic/api/integration/v1/projects/<ENCODED_PROJECT_ID>/ai/tools/<ENCODED_TOOL_ID>?integrationInstance=<ENCODED_SERVICE_INSTANCE>"

Replace every angle-bracket placeholder before running. The shell variable contains your authorized access token; token acquisition depends on your environment and is outside this trace.

The response includes separate id, name, code, integration association, and parameter metadata. Do not substitute a display name or presumed code for the resource ID without evidence. Documented responses include 200, 404, and 500; these describe this metadata request, not a business lookup.

Official sources: Retrieve an Agent Tool in a Project; Send Requests.

6. Practical Trace — Following PO-10482 Through Tool Execution

6.1 Start with the user’s request

Use “What is the current status of order PO-10482?” in a test environment. The word current expresses what the user wants; freshness depends on the source system, caching, and lookup time. A status-change timestamp alone does not prove a live read.

6.2 The model generates a tool request

This independently authored, provider-neutral envelope illustrates the concepts only:

{
  "callId": "call-01",
  "toolName": "get-order-status",
  "arguments": {
    "orderId": "PO-10482"
  }
}

Not a wire contract: callId, toolName, and arguments are teaching labels here. Actual fields, serialization, and correlation depend on the provider and pattern.

6.3 Resolve the requested tool

Compare the actual request identity with saved tool metadata and the integration association. The intended relationship is get-order-status → registered tool Get Order Status → integration Get Order Status. A similar display name is insufficient evidence. A request for an unavailable identifier must not be assumed to have reached the intended operation.

6.4 Forward the generated arguments

The intended business mapping is model argument orderId → REST request field orderId, with the exact value PO-10482. Verify both actual structures before configuring any mapping. The provider envelope is distinct from the business request:

{
  "orderId": "PO-10482"
}

For a deterministic fixture, define that request property as a string. Define every response field shown in section 1: found is boolean; the other fields are strings. Return every field in every normal business response. Use empty strings for inapplicable status, shipment, and timestamp values. This is a tutorial contract, not an Oracle application API.

6.5 Execute the integration

A reproducible fixture can use these application-defined branches. They describe required business logic; they are not invented OIC canvas navigation:

  1. Validate the identifier against ^PO-[0-9]{5}$. Reject missing, non-string, or malformed values before a downstream lookup. For an otherwise valid JSON request, the fixture may return outcome="INVALID_INPUT", found=false, empty data strings, and an explanatory message.
  2. For PO-10482, return the exact FOUND record in section 1 from a controlled fixture. In a real integration, replace that fixture with an authorized order-application lookup and explicit response mapping.
  3. For another well-formed identifier, return the NOT_FOUND record in section 8, substituting the requested identifier.
  4. Keep technical faults distinct from these normal outcomes. Validate and test the integration directly before registering it, then test the agent path separately.

Configure request/response JSON structures, target connectivity, and tracking using the adapters and controls available in your tenant. 

6.6 Return the tool result to the agent

Illustrative fixture result, not an executed run: PO-10482; SHIPPED; shipment SHP-7715; source record last updated November 6, 2026 at 14:20 UTC.

An appropriate illustrative answer is: “The returned record shows PO-10482 as SHIPPED, with shipment reference SHP-7715. Its last recorded update is November 6, 2026 at 14:20 UTC.” Do not call that timestamp the lookup time or claim that this static fixture proves the order’s present real-world state.

The logical trace is user request → proposed tool call → tool association → integration request → business result → agent observation → answer. Inspect each relevant boundary rather than treating the answer as proof of all prior steps.

6.7 Understand the different identifiers used in correlation

Kid-friendly analogy

Imagine a school trip. The trip has a trip number, each student has a student number, and every activity has its own activity number. The trip number identifies the whole trip, not an individual activity.

In this OCI AI integration, this means: The conversation, tool definition, individual tool invocation, and integration execution instance need to be identified separately when investigating a run.

IdentifierIdentifiesLimit
Tool IdentifierA registered capability.Not an execution ID.
Provider tool-call ID, when suppliedA request in a provider protocol.Its OIC mapping is not established here.
Conversation IDAn agent conversation.May span multiple instance IDs.
Agent instance IDAn agent execution.Not the tool integration instance.
Integration instance IDOne integration execution.For callbacks, use the tool execution’s ID, not the callback execution’s ID.

Timestamp proximity helps investigation but is not, by itself, a unique correlation key.

6.8 What about asynchronous tool execution?

An asynchronous tool returns its completed result later. Oracle documents a pause with status Waiting for tool to process, followed by resumption after callback. This path excludes Human in the Loop, whose callback is provided automatically.

In the asynchronous tool trigger, declare x-agentic-callback-uri; persist its runtime conversation ID and the tool’s runtime Instance ID from integration metadata. Carry those values securely to the completion workflow.

Add an AI Agent action in a callback integration. In Configure Basic Info, name the endpoint and choose Callback AI agent. Continue, select the current/shared project and Active agent in Configuration, then finish through Summary.

Mapper fieldValue
Conversation IDPersisted conversation ID.
Tool Flow IDOriginal asynchronous tool integration’s runtime Instance ID.
Tool Invoke Event IDThe same Instance ID; mandatory.
PayloadResult serialized as a JSON string; mandatory.

Validate, save, and activate. A callback is accepted only for a waiting conversation. The callback guide also lists toolFlowId, conversationId, toolInstanceId, and responsePayload; use the generated mapper rather than inventing a raw REST translation.

Official source: Send a Response to an AI Agent with a Callback.

The documented callback use case independently confirms using the original tool execution’s instance ID for both ID fields and shows a resumed agent with tool result and final answer. For your own test, capture the waiting state, completion callback, matching IDs, subsequent activity, and final result. Define authenticated callback delivery, durable correlation storage, failure alerting, and duplicate/late-response handling in the workflow; no retry or exactly-once guarantee is established by this article.

Official source: Use Case: Send a Callback to an AI Agent for an Asynchronous Tool.

Official source: New Adapters and Connectivity Enhancements in Oracle Integration 26.07.

7. Multiple Tool Calls and Sequential Execution

7.1 What happens when an agent needs more than one tool?

A user might ask for an order’s status and then shipment tracking. One run can involve several actions over time. That differs from one model response containing several requested calls.

7.2 ReAct: one action followed by observation

Oracle describes ReAct as choosing one action, observing its result, and then selecting the next step. In an illustrative sequence, the order tool supplies a shipment ID; a later shipment lookup uses it.

Kid-friendly analogy

Imagine making a sandwich. You must first get the bread before you can place the filling between the slices. The second step depends on having the first item ready.

In this OCI AI integration, this means: A subsequent tool may need an identifier or business result produced by an earlier integration, so the agent must receive and interpret the earlier result before making the dependent request.

7.3 Plan and Execute: ordered tool execution

Oracle’s documented arrangement uses two agents: a Planner with a Plan pattern and an Acting agent with ReAct. The planner defines ordered steps; the acting agent follows that sequence. This is more than selecting a Plan recipe on the original agent.

A conceptual plan might specify an order lookup, then shipment lookup using its returned ID, then a response. An executable plan must represent that dependency; never invent the shipment ID before it is known. Pattern ordering does not guarantee identical model outputs, correct business decisions, or exactly-once effects.

Official sources: Determine Which Agentic AI Pattern to Use; ReAct vs Plan & Execute: Choosing the Right Agent Thinking Pattern in Oracle Integration.

7.4 What if one model response contains several tool calls?

Some provider protocols can express multiple calls. That capability does not establish what an OIC-generated pattern accepts or how it schedules them.

  1. Inspect the returned collection and the flow that consumes it.
  2. Locate any iteration and invocation, including the article’s named action only if it actually exists.
  3. Inspect result association and the branch taken when an invocation fails.
  4. Compare with correlated runtime events; overlapping timestamps alone do not identify the dispatch mechanism.

Do not modify Oracle’s system-generated pattern to investigate. Inspect an exported copy where permitted; some behavior may remain platform-managed and require Oracle clarification even with an export.

7.5 Why execution order matters

Dependent operations require earlier results. Independent reads may be candidates for concurrency only where the supported implementation and target capacity allow it. Writes add ordering, conflicting-update, and duplicate-effect risks. Choose a supported business design; a list of calls proves neither sequential nor parallel execution.

8. Business Errors, Invocation Exceptions, and Enterprise Safeguards

8.1 A business error is not always a technical failure

An unknown order can be a normal business outcome. Use the same response shape and types as the successful fixture:

{
  "orderId": "PO-99999",
  "found": false,
  "outcome": "NOT_FOUND",
  "status": "",
  "shipmentId": "",
  "lastUpdated": "",
  "message": "No matching order was found."
}

This tutorial chooses a normal response for NOT_FOUND. It does not prescribe an Oracle application’s HTTP error contract. Authentication failures, unreachable targets, and unhandled integration faults require technical error handling. A timeout can leave completion uncertain, especially for a write. Never convert such a failure into “order not found” or an invented successful status.

Kid-friendly analogy

Imagine asking a shopkeeper for a red bicycle. If the shop has none, that is an understandable answer. If the shopkeeper cannot open the store because the electricity is down, the request has a completely different problem.

In this OCI AI integration, this means: Return meaningful business outcomes separately from technical invocation faults so the agent and downstream workflow can respond appropriately.

8.2 Where should input validation happen?

Treat model arguments and tool output as untrusted data. Validate input types, required values, format, and business scope within the integration or target. The five-digit rule above is specific to this fixture, not an Oracle limit. Treat text returned by a tool as business data, not as authority to override instructions or expand access.

8.3 Where should authorization and approval be enforced?

OAuth protects the invocation boundary; record-level authorization needs the relevant integration and target controls. Confirm which outbound identity is used. An employee’s prompt does not establish that their identity is propagated to the target. Validate an authorized business context rather than trusting an order number or identity asserted by the model.

For sensitive reads or writes, enforce required approval in the workflow before the protected operation. A Human in the Loop step can support approval, but the control path must actually block the action until an authorized decision is available. Descriptions and guidelines do not supply that enforcement.

8.4 Why repeating a tool call can be dangerous

Idempotency means repeating the same operation has the same intended business effect as performing it once. For a write, use a stable business-operation key and an atomic uniqueness or deduplication control, or the target’s supported idempotency mechanism. A separate “check then insert” without concurrency protection can still duplicate work.

If a purchase order was created but its response was lost, an unprotected retry may create another. Reconcile target state after uncertain completion. A fresh conversation or call ID may change on retry, so it is not automatically a suitable business idempotency key. No exactly-once execution guarantee follows from a pattern name or iteration limit.

9. Verify the Execution and Troubleshoot Problems

9.1 Inspect the agent activity

Oracle documents Projects → your project → AI Agents, then the agent’s Actions → Run. On Test Agent, submit the order-status question. Review System, User, Tool, and Assistant entries; Tool contains the tool response. Treat displayed assistant rationale as generated content, not proof of hidden model computation.

9.2 Inspect the integration execution

From Test Agent, return to the AI Agents page, select Observe, then inspect Integrations. Oracle’s sample includes the business flow, ReAct Pattern Intg, and Get Tool Data Intg; do not assume every run has exactly those names or counts. An Errored count leads to instances and View Details.

Official source: Run and Test the AI Agent.

Correlate the run to the tool integration’s actual request and response. Payload visibility depends on your monitoring access, tracing configuration, and retained evidence. If payloads are unavailable, record that gap and use approved test tracing; do not claim the mapping was verified. Protect tokens, callback context, and sensitive business data in evidence.

9.3 Retrieve the activity stream from an integration

Add an AI Agent action using the canvas Actions panel or the add control and AI search. In Configure Basic Info, name the endpoint and choose Get AI agent activity stream. Continue to Summary and finish. Map the conversation ID, save, and activate the integration. Oracle’s documented procedure has no additional agent-selection panel for this operation.

Read the returned status and activity; a successful retrieval does not mean the agent run succeeded. No response JSON schema or status enumeration beyond the documented waiting label is invented here.

Official source: Get the Activity Stream for an AI Agent.

9.4 Test the complete tool invocation

Execution status: not tested. The following are acceptance tests for the configured fixture and controls, not observed outcomes or platform guarantees.

CaseDesigned outcomeEvidence
PO-10482FOUND and SHIPPED from fixture.Exact input, tool instance, fixture output, Tool entry, faithful answer.
Missing or malformed IDClarification or validation rejection.Arguments, validation branch, no downstream lookup for invalid input.
PO-99999NOT_FOUND with empty status fields.Response shape and answer; no invented status.
Unavailable tool identityNo unrelated business operation.Controlled negative-test request, dispatch fault/activity, target records.
Authentication failureTechnical failure reported.Connection/fault evidence; no fabricated success.
TimeoutFailure or uncertain completion handled.Instance fault and target-state reconciliation.
Async completionWait, callback, resume.Original IDs, waiting state, callback instance, subsequent result.
Several requested callsBehavior determined from evidence.Provider response, supported flow structure, per-call results/faults.
Repeated write, separate from this read fixtureOne intended business effect.Stable operation key, atomic deduplication, target records.

For an invalid tool identity or provider-level multi-call test, use a supported isolated harness if available. Do not alter generated Oracle integrations or production metadata solely to force these cases.

9.5 Troubleshoot the common problems

SymptomTargeted check
No tool requestAssociation, active resources, model compatibility, description, and available arguments.
Wrong order reaches the toolActual arguments, trigger request, validation, and mapping.
Invocation failsFault details, trigger eligibility, token/connection setup, and target access.
Tool returns data but agent remains incompleteFollowing pattern events, missing callback context, run status, and iteration limit.
Duplicate business effectRepeated requests, retries, uncertain timeouts, and atomic idempotency controls.

Isolate the failing boundary before changing prompts. A final sentence alone cannot distinguish a metadata error, mapping error, expired credential, or downstream failure.

10. Completion Checklist and What Comes Next

  • Record the actual project, tool metadata, integration association, provider, pattern, and tenant version.
  • Keep the original request, actual arguments, correlation identifiers, tool integration instance, and returned data.
  • Compare the business result with the Tool entry and final answer, including timestamp meaning.
  • Separate expected fixture outcomes from observations; retain failures and uncertainty.
  • For asynchronous tools, preserve original callback context and verify resumption.
  • Keep validation, authorization, approval, and duplicate prevention in enforced controls.

11. Five Useful FAQs

1. Does the LLM directly call the business REST API?

In this OIC project-agent architecture, the model requests a tool. The registered integration performs the enterprise operation using its configured connectivity and mappings.

2. Is the tool Name the same as the tool Identifier?

They are separate fields. Oracle documents Name as human-facing and not sent to the LLM, while Identifier is model-facing metadata. Record the saved values rather than assuming equality.

3. Is a provider tool-call ID the same as the OIC Conversation ID?

Do not equate them. They identify different layers. An OIC conversation can span multiple instance IDs; the provider-to-OIC correlation mapping needs actual protocol and runtime evidence.

4. Does OIC execute several requested tools in parallel?

Verify the supported pattern and runtime evidence for the tenant rather than inferring concurrency from a list of calls.

5. Are agent guidelines enough to prevent unauthorized or duplicate operations?

No. Enforce authorization, validation, approval, and idempotency in the integration, workflow, and target system. Model instructions do not replace those controls.

12. Additional References

Official Documentation supports product instructions; product-team articles provide architectural and release context. Examples, analogies, and business contracts.

Oracle Integration documentation

  1. Register an Integration as an Agentic AI Tool
  2. Add and Configure the AI Agent
  3. Configure the Agentic AI Thinking Pattern
  4. Determine Which Agentic AI Pattern to Use
  5. Run and Test the AI Agent
  6. Get the Activity Stream for an AI Agent
  7. Send a Response to an AI Agent with a Callback
  8. Retrieve an Agent Tool in a Project
  9. What's New for Oracle Integration 3
  10. September 2026 (26.10)
  11. Verify Updates and Feature Availability
  12. Send Requests
  13. Check Whether Your Instance Has Been Updated
  14. Use Case: Send a Callback to an AI Agent for an Asynchronous Tool

13. Finally — Summary

When an OIC Project AI Agent requests a tool, the language model selects a capability and proposes arguments. The registered integration executes the business operation. Verify that the actual request reached the intended integration and that the returned business result supports the answer.

Keep the identifiers separate: the tool definition, provider request where available, agent conversation, agent execution, and integration execution identify different things. For the documented asynchronous callback, both tool ID mapper fields use the original tool integration’s runtime instance ID.

ReAct adapts after observations. Oracle’s Plan and Execute arrangement separates planning from ordered execution. Neither removes the need for enforced validation, authorization, approval, and idempotency.

The central engineering lesson is simple: a requested tool is not a completed business operation. Confirm execution, correlation, result meaning, and freshness before relying on the agent’s answer.

Comments