OIC AI Agents: Register Your First Tool, Configure the Pattern, and Create the Agent
1. What You Will Build
In this lab, you will build the Procurement Exception Assistant, a single-tool AI agent in Oracle Integration 3. It will accept a purchase-order status question, decide whether the request contains enough information, call a registered integration when appropriate, interpret the returned result, and provide an evidence-based answer.
The prototype uses a synthetic order-status integration rather than a real procurement application. This keeps the exercise focused on the new engineering concepts: tool registration, model-visible metadata, agent instructions, thinking-pattern association, runtime tool selection, and execution evidence.
Example interaction
User: Can you check the status of purchase order PO-1042?
Expected tool input: orderNumber = "PO-1042"
Illustrative tool result: orderStatus = "PENDING_APPROVAL"
Expected answer: Purchase order PO-1042 is pending approval, based on the order-status lookup.
When you complete the lab, you should be able to trace the requested order number from the agent's tool call to the integration's request and response, then compare that response with the agent's final answer. You will also test whether the agent asks for a missing order number instead of inventing one.
The lab is successful only when the evidence supports the answer. Creating and activating an agent does not prove that the agent selected the correct tool, supplied the correct argument, or interpreted the returned business data correctly.
2. In This Post
- Before You Begin
- Concepts That Affect This Build
- Build and Configure the Agent
- Test and Prove It
- Troubleshooting and Recovery
- Enterprise Considerations
- Completion Checklist and What Comes Next
- Five Useful FAQs
3. Before You Begin
The following prerequisites are specific to this lab. Familiar OIC development tasks, such as ordinary mapping, integration activation, and standard monitoring, are not explained from first principles.
- An Oracle Integration 3 project in which you can create and activate integrations and manage AI agent resources.
- An organization-approved LLM provider and model that can be configured and successfully tested through the AI agent thinking-pattern connection.
- Permission to configure the REST Adapter trigger with the required OAuth authentication and JSON payload.
- A way to inspect agent instances and integration executions in the project.
- The ability to create a synthetic order-status integration. No live procurement endpoint is required.
Oracle's documented agentic-tool prerequisites require an integration to belong to a project, be active, and use a REST Adapter trigger with OAuth authentication and a JSON payload. POST is used in this lab because the request carries an order number in its body. The documentation permits other supported REST verbs as well. See Register an Integration as an Agentic AI Tool.
Permissions note: The cited tool-registration procedure does not establish one universal IAM role name for every action involved in this lab. Use your tenancy administrator to confirm the least-privilege access required for project integration design, activation, agent-pattern management, and AI-agent management. Do not substitute role requirements for Fusion AI Agent Studio.
Dependency classification: Configuring or reusing an active thinking pattern is a prerequisite to creating the agent. Registering a project integration as a tool, creating the agent, and verifying its runtime are the core work. Real procurement connectivity, multi-tool orchestration, knowledge-base retrieval, human approval, and write operations are deferred.
4. Concepts That Affect This Build
An integration and an agentic tool are not the same thing
An ordinary OIC integration implements an executable business or technical flow. Registering that integration as an agentic AI tool makes it available for selection by an AI agent, together with a model-facing identifier, description, guidelines, and parameter metadata.
The integration remains the implementation that processes the request. The tool metadata helps the model understand what the integration does and when it should use it. The model's choice to call the tool is a separate event from the integration's execution and its business result.
Registration is not equivalent to enabling an integration for external MCP clients. MCP access is a separate capability with its own project configuration and security considerations. Oracle documents those capabilities separately in its 26.10 release notes.
Tool metadata influences selection; it does not enforce correctness
When an agent considers available tools, the LLM uses their identifiers, descriptions, relevant guidelines, and exposed parameter definitions to determine whether a tool is appropriate and what arguments to supply.
A description such as “Looks up the status of one synthetic purchase order using its exact order number” communicates both capability and intended usage. “Processes procurement requests” is too broad: it does not distinguish a read-only lookup from order creation, approval, or cancellation.
The metadata improves the model's decision context, but it is not an authorization mechanism. A prompt that says “never change orders” cannot replace backend authorization, validation, or target-system controls. This lab deliberately supplies only a read-only synthetic lookup.
Visible parameters define what the model can fill in
The registered tool lists input parameters derived from the integration. The Visible setting determines which fields are sent to the LLM. A field that is not visible is not available to the LLM as a parameter for constructing its tool call.
Expose the business inputs required for the task and keep internal or technical fields hidden. The model does not need database connection details, credentials, internal tracking values, or implementation-only fields to request an order-status lookup.
The parameter's Required setting tells the LLM that it must assign a value when calling the tool. That helps communicate the call contract, but it does not prove that the value is valid or that a user actually supplied it. The integration should validate the received request independently.
For this lab, orderNumber is the required business input when a tool call is made. The agent's instructions will require clarification before a call when the user has not supplied that identifier. The integration will also have explicit branches for missing and invalid input.
Agent instructions and pattern instructions have different jobs
The thinking pattern governs the broad interaction strategy. The agent Role and Guidelines define the assistant's job, allowed requests, evidence requirements, clarification behavior, and stopping conditions. The tool description and guidelines tell the LLM when and how the particular tool should be used.
Oracle documents the ReAct pattern as alternating between reasoning and action, using new information to guide subsequent decisions. Plan and Execute first generates a complete plan and then works through it. For this first agent, ReAct is the practical choice: the central behavior is to decide whether an order number is available, perform one lookup, inspect the result, and answer.
The pattern is not a guarantee that the model will always choose the correct action. The tool call, returned payload, integration status, and final answer must be checked independently.
What Max iterations does—
Max iterations limits the reasoning/action steps available before the agent provides a final answer or exits. The purpose is to prevent unbounded repeated activity. A limit that is too restrictive may prevent a legitimate task from finishing; a needlessly high limit can allow more repeated calls, increase latency and LLM usage, and make failure analysis harder.
Oracle's pattern guide describes the limit in terms of reasoning and action steps, but does not fully define the low-level accounting—for example, whether final-answer generation counts as an iteration or whether every tool call corresponds to exactly one iteration. Do not equate an iteration count with a fixed number of business-tool calls without evidence.
For this minimal prototype, retain the value supplied by the pattern configuration and record the value actually displayed in your tenant. The current documentation illustrates a ReAct screen with a value of 10, but the procedure tells readers to retain the default; do not assume that the illustration establishes a universal default for every pattern or tenant.
Calibrate the limit later using representative traces: identify the genuine decision cycles required by successful runs, inspect whether runs stop prematurely or repeat, and adjust only when the evidence justifies it. The setting limits execution; it does not make decisions correct or enforce business authorization.
For the official configuration procedure, see Configure the Agentic AI Thinking Pattern.
5. Build and Configure — Step by Step
Step 1: Define the synthetic order-status contract
Starting location: Projects → create or open your lab project → Design → Integrations.
Create a REST-triggered integration named Lookup Synthetic Order Status. The name is a tutorial-defined label, not a mandatory Oracle identifier.
Configure the trigger to use the REST Adapter, OAuth authentication, JSON input/output, and POST. The integration must belong to the project and be activated before it can be registered as a tool. Use your tenant's supported authentication configuration rather than weakening the trigger to make the lab easier.
The input contract should contain one business field:
{
"orderNumber": "PO-1042"
}
For this exercise, allow the request contract to reach the integration's explicit validation branch when the field is absent or blank. If your generated request schema makes the field mandatory at the schema boundary, adjust the lab schema so you can test that validation branch. The tool's Required metadata and the integration's request-schema requirement are separate configuration concerns.
Implement deterministic logic with a Switch, If, or equivalent routing structure using these tutorial-defined records:
| Input condition | Returned code | Returned status/result |
|---|---|---|
Exact order number PO-1042 |
OK | PENDING_APPROVAL |
Exact order number PO-2088 |
OK | APPROVED |
| Missing or blank order number | MISSING_ORDER_NUMBER | No status; explicit validation message |
| Any other order number, such as PO-9999 | ORDER_NOT_FOUND | No matching synthetic order |
| Test-only sentinel PO-5000 | LOOKUP_UNAVAILABLE | Simulated lookup-service problem |
The sentinel PO-5000 is a controlled application-level failure case for this lab, not a claim that the integration runtime itself failed. It lets you verify that the assistant distinguishes an unavailable lookup from a confirmed business status.
Use a consistent JSON response contract. The following is a complete example for PO-1042:
{
"found": true,
"orderNumber": "PO-1042",
"orderStatus": "PENDING_APPROVAL",
"code": "OK",
"message": "Purchase order PO-1042 is pending approval.",
"source": "SYNTHETIC_LAB"
}
The not-found branch should return found: false, the received order number, a null order status, the code ORDER_NOT_FOUND, an explanatory message, and the source marker SYNTHETIC_LAB. The missing-input branch should return MISSING_ORDER_NUMBER and no order status. The PO-5000 branch should return LOOKUP_UNAVAILABLE and no order status.
Map these fields into the REST response through the integration designer. The examples define the JSON body; configure HTTP response-status mapping separately according to the behavior supported by your trigger configuration. Do not assume the JSON field code automatically sets the HTTP status.
Checkpoint: Before continuing, confirm that the flow can return the appropriate synthetic result for PO-1042, PO-2088, PO-9999, and the two exceptional inputs. Test the integration through the supported OIC test path and OAuth configuration. Do not register an unverified integration and assume that the agent will compensate for a broken contract.
Step 2: Activate and register the integration as an agentic tool
Starting location: Projects → your lab project → Design → Integrations.
After saving and activating Lookup Synthetic Order Status, locate it in the project's Integrations section and select its Actions menu → Create agentic AI tool.
Oracle documents the registration prerequisites and metadata fields in Register an Integration as an Agentic AI Tool. Use the following values for the tutorial-defined tool:
| Field | Value or decision |
|---|---|
| Name | Lookup Synthetic Order Status |
| Identifier | lookup-synthetic-order-status |
| Description | Looks up the status of one synthetic purchase order using its exact order number. Use only after the user provides an order number. Returns the lookup result, status, code, and message. Does not change purchase orders. |
Two decisions deserve attention before clicking Create.
First, choose the identifier carefully. Oracle documents that the identifier is sent to the LLM as tool metadata and cannot be changed after the tool is created. The Name field is not sent to the LLM and also cannot be changed after creation. The Description is sent as part of the system prompt and helps the LLM decide when the tool is appropriate. Use clear, stable naming rather than accepting an ambiguous identifier without review.
Second, make the description specific to the intended task. The description should communicate the lookup's capability, its required input, and its read-only boundary. A general description such as “Handles purchase orders” leaves the model to guess whether the integration retrieves information or performs a transaction.
Click Create to open the tool details page. Review the tool's description, guidelines, and parameter configuration.
Step 3: Configure tool guidelines and parameters
The tool details page contains the fields that shape the LLM's understanding of the tool. Configure the tool-level Guidelines as follows:
Tool guidelines — copyable example
Use this tool only to look up the status of one specific synthetic purchase order.
Call it only when an exact order number has been supplied by the user.
Do not invent an order number or substitute an example identifier.
Use the returned fields as the source of truth.
This tool is read-only and must not be represented as creating,
approving, updating, or cancelling a purchase order.
These guidelines are sent to the LLM and influence its choices; they are not backend authorization rules. A request with an incorrect identifier must still be handled by the integration's deterministic validation and lookup logic.
Next, inspect the Parameters configuration. The parameter list is automatically populated from the integration's inputs. For this minimal prototype, configure the business parameter as shown below.
| Field | Lab setting | Reason |
|---|---|---|
| Parameter | orderNumber |
The exact business key used to look up the order. |
| Visible | Yes | The model must be able to supply the order number. |
| Type | Retain the type populated from the integration | The integration contract defines the parameter type. |
| Required | Yes | When calling the tool, the model should provide this required business input. |
| Constant | None | The order number varies by request and must not be hard-coded. |
| Default | None | A default order number could silently look up the wrong order when the user provides no identifier. |
| Enum values | None | Order numbers are identifiers, not a closed list of allowed status values. The synthetic lookup handles unknown identifiers. |
| Description | The exact synthetic purchase-order number supplied by the user, for example PO-1042. Do not invent or infer a missing identifier. | The model needs a precise interpretation of the parameter. |
The Required setting expresses a constraint for tool-call construction; it does not prove that the identifier exists or that it was genuinely provided by the user. That is why the agent instructions must ask for clarification and why the integration still validates its received input. The default field is deliberately empty: a default of PO-1042 would conceal a missing-input problem by making a valid-looking but unintended lookup.
Click Save to persist the tool metadata. Confirm that Lookup Synthetic Order Status appears in the project's AI Agents area under Tools. This confirms registration in the design configuration, not successful execution.
Step 4: Create or reuse an active ReAct thinking pattern
Starting location: Projects → your lab project → Design → AI Agents → Agent patterns.
If you already have an activated, suitable thinking pattern in the project, reuse it rather than creating a duplicate. Otherwise, create one using the documented pattern configuration procedure.
Use these tutorial-defined values in the Create pattern panel:
| Field | Value or decision |
|---|---|
| Name | Procurement ReAct Pattern |
| Identifier | PROCUREMENT_REACT_PATTERN |
| Pattern recipe | ReAct |
| Description | Reason-and-act pattern for the Procurement Exception Assistant prototype. |
ReAct is appropriate because this task has a short evidence loop: determine whether a usable order number is present, call the lookup, observe the response, and answer from that response. Plan and Execute is an alternative pattern, but generating a complete multi-step plan provides little value for this simple one-lookup task.
Configure the pattern and its LLM connection. Preserve the default pattern guidelines for the first lab unless you have a specific, tested reason to change them. If you do change them, keep the pattern-level instructions focused on the general reasoning/action process rather than moving all procurement business rules into the pattern.
The LLM connection includes the endpoint Base URL, model, and API-key-based authentication fields described in Oracle's pattern documentation. Use the connection details and model approved for your environment; do not treat an example model name from a screenshot as proof that the model is approved or supported in your own tenancy. Enter credentials only into the appropriate secure connection field, and never include them in prompts or tool descriptions.
Test the LLM connection using the documented Test action, save the connection, and confirm that the pattern configuration is saved. Oracle documents that creating a pattern creates a system-generated integration that implements the pattern. That integration is a runtime dependency, not an ordinary business integration to be repurposed for procurement logic.
Return to Agent patterns and activate Procurement ReAct Pattern. Oracle requires the pattern to be active before it can be selected for an agent. Confirm its displayed status is Active before proceeding.
Checkpoint: You should now have an active pattern and a tested LLM connection. If a suitable pattern was already available, record its name and actual configured limit so the lab's execution evidence refers to the pattern that was really used.
Step 5: Create the Procurement Exception Assistant
Starting location: Projects → your lab project → Design → AI Agents → Agents → Add.
Create the agent using the following tutorial-defined configuration:
| Field | Value or decision |
|---|---|
| Name | Procurement Exception Assistant |
| Identifier | Use the identifier generated by Oracle Integration from the name and confirm the result. |
| Description | Answers read-only questions about synthetic purchase-order status using a registered lookup tool. It does not change orders or approve exceptions. |
| Thinking pattern | Procurement ReAct Pattern, or the active suitable pattern you intentionally reused. |
The agent's Description is informational. It identifies the agent's purpose for people working with the project, but it is not a replacement for the Role or Guidelines that influence runtime behavior. Select the activated thinking pattern and click Create.
On the agent details page, configure the Role and Guidelines. These fields are sent to the LLM as part of the system prompt. The Role describes what the assistant is; the Guidelines define how it should handle requests and evidence.
Role — copyable example
You are the Procurement Exception Assistant.
You answer questions about synthetic purchase-order status
using the registered order-status lookup tool.
Your responsibility is to report the evidence returned by
the lookup, not to invent business status or approve orders.
Guidelines — copyable example
1. Handle only questions about the status of a purchase order
in the synthetic lab.
2. If the user has not supplied an exact order number, ask
for the purchase-order number before invoking the tool.
Do not invent or guess an identifier.
3. For an in-scope request with a supplied order number,
use the registered order-status lookup tool.
4. Treat the returned tool response as the business evidence.
Use the returned order number, code, message, and status
to formulate the answer.
5. If the result code is OK and found is true, report the
returned status. Do not change or reinterpret that status.
6. If the result code is ORDER_NOT_FOUND, explain that the
synthetic lookup found no matching order. Do not invent
a replacement order or status.
7. If the result code is MISSING_ORDER_NUMBER, ask the user
for the missing identifier.
8. If the result code is LOOKUP_UNAVAILABLE, explain that
the status could not be verified. Do not report the order
as approved, pending, or not found.
9. If the tool fails, returns no usable result, or produces
an unexpected response, say that the status could not be
verified. Never claim a successful lookup without evidence.
10. After receiving a sufficient result for one order, stop.
Do not repeat the same lookup without a clear reason.
11. If the user asks for an unrelated task, explain the
assistant's scope and do not invoke the order-status tool.
12. This assistant is read-only. It must not claim to create,
update, cancel, or approve purchase orders.
These instructions make the expected behavior explicit, including clarification, interpretation of failure codes, and stopping. They guide the LLM's decisions; they do not enforce authorization or guarantee that the agent will follow every instruction. The integration's contract and validation remain necessary.
Click Save before adding the tool.
Step 6: Associate the tool and activate the agent
On the agent details page, locate the Tools section and click the plus (+) control. Select Lookup Synthetic Order Status and click Add. Save the agent configuration.
At this stage, the model has an available lookup tool whose identifier and description explain its purpose, whose guidelines constrain intended use, and whose visible parameter tells it what order number to supply. The association does not itself demonstrate that a runtime call will be made.
Before activation, verify these dependencies:
- The REST-triggered lookup integration is Active and belongs to the project.
- The tool is registered, its description and guidelines are saved, and its parameter settings are correct.
- The selected thinking pattern is Active.
- The LLM connection was tested and its configuration saved.
- The agent's Role and Guidelines are saved, and the intended tool appears under its associated resources.
Return to the project's AI Agents page. In the Agents section, locate Procurement Exception Assistant, open its Actions menu, and select Activate. Confirm the displayed status is Active.
Activation means that the design-time lifecycle has reached an active state. It does not prove that the LLM can complete a request, that the model will select the right tool, or that the integration's result will be interpreted correctly. Those are runtime checks in the next step.
For the documented agent configuration and activation workflow, see Add and Configure the AI Agent.
Step 7: Run the first agent request
Starting location: Projects → your lab project → Design → AI Agents → Agents → Actions → Run.
The Test Agent page opens. Enter the following prompt and send it to the agent:
Prompt: Can you check the status of purchase order PO-1042?
The expected behavior is for the agent to recognize that the request is in scope and contains a usable order number, choose the order-status tool, submit PO-1042 as the orderNumber argument, receive the integration response, and answer from that response.
The Test Agent page presents agent activity. Oracle's documentation identifies the System, User, Tool, and Assistant activity types. System activity includes the agent Role and Guidelines and the pattern guidelines; User activity reflects the submitted prompt; Tool activity shows the tool response; and Assistant activity shows the agent's response or conclusion.
Inspect each relevant activity item rather than judging the run from the final conversational answer alone. Where the UI displays the tool arguments, compare the submitted order number with the prompt. If exact arguments are not displayed there, inspect the underlying integration execution and request payload using the project's Observe capabilities and the available tracing level.
The expected synthetic response is:
{
"found": true,
"orderNumber": "PO-1042",
"orderStatus": "PENDING_APPROVAL",
"code": "OK",
"message": "Purchase order PO-1042 is pending approval.",
"source": "SYNTHETIC_LAB"
}
An acceptable illustrative final answer would be:
Purchase order PO-1042 is currently pending approval, according to the synthetic order-status lookup.
This response is an expected example, not evidence that the run actually succeeded. Your execution must show the real tool input, actual integration response, and final answer before you mark the scenario as passed.
Step 8: Run the missing-input scenario
Start a new agent run so the clarification test is not confused with the previous interaction. Submit:
Prompt: Can you check the status of my purchase order?
The expected behavior is a concise clarification, such as “What is the purchase-order number?” The agent should not invent an order number, use PO-1042 merely because it appears in the lab examples, or call the lookup with an assumed identifier.
Inspect whether a tool call was made. For this specific request, the expected result is clarification before the lookup, so there should be no order-status integration execution for that request. If an integration execution exists, inspect its input payload to determine whether the model supplied an unsupported or fabricated identifier.
The clarification behavior is model-guided. Even with a Required parameter and explicit guidelines, it is not a deterministic guarantee. If the agent calls the tool with an invented identifier, treat that as a failed test: refine the parameter description and agent instructions, retain integration-side validation, and repeat the test.
Checkpoint: You should now have one valid-input run and one missing-input run to inspect. Do not mark either as passed until the actual activity and integration evidence are available.
6. Test and Prove It
A useful verification separates three questions: did the agent choose correctly, did the integration execute correctly, and did the final answer accurately report the business evidence?
| Test case | Expected behavior | Evidence to inspect |
|---|---|---|
| Valid: PO-1042 | Agent invokes the lookup with the supplied identifier and reports PENDING_APPROVAL. | Tool call, request payload, integration response, final answer. |
| Missing order number | Agent asks for the identifier without invoking the lookup. | Assistant clarification and absence of a corresponding lookup instance. |
| Unknown: PO-9999 | Lookup returns ORDER_NOT_FOUND. Agent reports no matching synthetic order. | Exact tool argument, response code, and final-answer consistency. |
| Simulated lookup issue: PO-5000 | Agent reports that status cannot be verified; it does not claim approval or nonexistence. | LOOKUP_UNAVAILABLE response and the agent's interpretation. |
| Out-of-scope request | Agent explains its limited scope and does not use the order-status tool. | Prompt, tool activity, and final answer. |
Inspect the agent run
In the Test Agent page, select the run and inspect the visible activity. Identify:
- The exact prompt submitted by the user.
- Whether the agent selected the registered lookup tool at the appropriate point.
- The order-number argument, wherever the UI or integration execution provides it.
- The actual tool response, including its status, code, and message.
- Whether the final answer agrees with that response and stops without an unnecessary repeated lookup.
The visible Assistant response is not a substitute for the Tool result. An agent can produce a confident but incorrect statement even when no successful tool result supports it. Conversely, an accurately returned business error such as ORDER_NOT_FOUND is not necessarily a failed integration execution.
Inspect the integration execution
From the project, select Observe and inspect the integration instances for the registered lookup. Oracle documents that you can view integration-instance status, open instance details, inspect the activity stream, and view message payloads where the configured tracing level makes them available. See Track Instances in a Project.
Locate the instance associated with the agent run and check the integration's request and response. If tracing does not expose the payload, follow your organization's approved tracing procedure; do not enable broader payload visibility in a production environment merely for convenience.
Confirm that the integration received PO-1042 when the user supplied PO-1042, returned PENDING_APPROVAL, and completed successfully. For PO-9999, confirm that the response identifies ORDER_NOT_FOUND. For PO-5000, confirm that the response contains LOOKUP_UNAVAILABLE and is not misrepresented as a successful business lookup.
Understand agent and integration identifiers
Oracle exposes several identifiers and monitoring records. They serve different purposes and should not be treated as interchangeable.
| Evidence or identifier | What it represents | Where to inspect it |
|---|---|---|
| Agent instance ID | Identifies the individual agent invocation/run. | The Test Agent activity, where displayed, or the project's Observe → AI Agents records. |
| Conversation ID | Associates runs with a conversation history. One conversation can span multiple agent-instance IDs. | The Test Agent activity or agent-instance monitoring details. |
| Integration instance ID | Identifies a particular integration execution, such as the run behind the lookup tool. | The project's Observe → Integrations → Instances records and instance details. |
| Integration execution status | Indicates whether that integration instance succeeded, errored, or ended in another runtime state. | Integration instance monitoring and details. |
The Conversation ID is not a unique identifier for one invocation: Oracle's conversation-history documentation describes reusing a Conversation ID across multiple agent runs. The conversation-history procedure also refers to obtaining the Conversation ID from the “Instance ID” column, while the Test Agent documentation separately identifies the Conversation ID in the activity area. This wording is potentially ambiguous. Verify the field labels displayed in your tenant and record the agent invocation ID and Conversation ID separately wherever both are available.
The project workspace documents the Agent instances view under Observe → AI Agents. See Tour of the Projects Workspace and Run an AI Agent with Knowledge of Previous Runs.
Record the minimum useful evidence
For each run, retain a compact evidence record containing:
- Test case name, timestamp, agent name, and exact user prompt.
- Agent instance ID, Conversation ID, and observed agent status.
- Tool selected, order-number argument received by the integration, and integration instance ID.
- The actual integration response and the final agent answer.
- The result of the comparison: consistent, inconsistent, or not verifiable from the available evidence.
For the valid test, a successful integration instance is necessary but not sufficient. The argument must match the requested identifier, the returned status must match the actual response payload, and the agent must communicate that result accurately. This is the first small example of agent evaluation: inspect both tool behavior and answer quality.
7. Troubleshooting and Recovery
| Symptom | Likely layer and targeted check | Correction and retest |
|---|---|---|
| The integration does not appear as a registrable tool. | Check project membership, integration activation, REST Adapter trigger, OAuth authentication, and JSON payload. | Correct the prerequisites and retry registration. |
| The agent cannot select the intended pattern. | Check whether the selected thinking pattern is Active and its configuration has been saved. | Activate the pattern after resolving dependencies, then return to agent configuration. |
| The agent fails before calling the lookup. | Inspect the pattern integration's error and the LLM connection configuration and test result. | Correct the LLM endpoint, model, or authentication configuration and rerun a small prompt. |
| The tool is not selected for PO-1042. | Review the tool identifier, description, tool guidelines, visible parameter, and agent-level instructions. | Make the lookup's capability and required input explicit; rerun the same prompt. |
| The tool receives an incorrect or fabricated order number. | Compare the exact request payload with the prompt and inspect the parameter description and clarification instructions. | Correct the metadata and instructions, retain backend validation, and repeat missing-input and valid-input tests. |
| The integration succeeds, but the final answer is incorrect. | Compare the actual tool response with the final answer; the defect may be in the agent's interpretation rather than the flow. | Strengthen the result-handling guidelines and retest both success and error codes. |
| The agent reports not found when the lookup was unavailable. | Inspect the returned code. Check whether LOOKUP_UNAVAILABLE is being treated as ORDER_NOT_FOUND. | Make the result-code precedence explicit and repeat the PO-5000 test. |
| The final response is missing or the run appears incomplete. | Inspect the agent status and the pattern, tool, and business-integration instance statuses. | Correct the failing layer and run the test again. Do not infer completion from the absence of an error message in the conversation. |
Oracle's agent-testing procedure also describes inspecting the project's Observe view to find executions and errors, opening instance details, and reviewing the LLM configuration when the pattern integration fails. See Run and Test the AI Agent.
For this module, leave the synthetic lookup, registered tool, and agent available for the next exercise. Do not delete system-generated pattern resources as a troubleshooting shortcut. Correct the failed configuration and preserve the test evidence needed to continue.
8. Enterprise Considerations
Prompt guidance is not authorization
The prototype is read-only, but a production lookup must still enforce the intended access boundary. The tool's description, its guidelines, and the agent's instructions help the model choose and use the tool. They do not decide which business records the authenticated caller is authorized to read.
Before connecting to a real procurement system, verify the identity under which the integration runs, the caller's permitted scope, the target system's authorization behavior, and what business data is allowed to reach the LLM. Apply access controls in the supported integration and target-system control planes.
Returned data is evidence, but not trusted instructions
The model should use the structured status and result code returned by the lookup as business evidence, while treating free-text messages as data rather than new instructions. In a production implementation, an order description or error message must not be allowed to override the assistant's defined scope or authorization controls.
Keep the response contract explicit. Distinguish confirmed status, not found, invalid input, and unavailable service. This prevents the model from collapsing different business and operational states into one confident answer.
Observe with data minimization
Capture enough evidence to diagnose the interaction: instance identifiers, tool-call inputs, tool results, and the final answer. Avoid unnecessary sensitive content in prompts or logs. Oracle documents tracing-level-dependent access to message payloads and audit logging when payloads are viewed. Follow your organization's approved tracing and retention policy rather than enabling unrestricted payload visibility in production.
Also distinguish the agent's conversational result from the execution status of the integration. Monitoring the two together is necessary to identify whether a failure occurred in model configuration, tool selection, request construction, integration processing, or final-answer interpretation.
Multi-tool orchestration, human approval, write operations, and retrieval-grounded assistance are outside this module. They should be introduced only after the single-tool contract, failure behavior, and evidence checks are reliable.
9. Completion Checklist and What Comes Next
Use this checklist against the actual project, not merely against the steps in the article.
- ☐ The synthetic order-status integration belongs to the project, uses the documented REST-trigger prerequisites, and is Active.
- ☐ The registered tool has a deliberate identifier, an accurate description, appropriate guidelines, and the intended visible parameter.
- ☐ The thinking pattern is Active and its LLM connection is successfully tested.
- ☐ The Procurement Exception Assistant exists, has its Role and Guidelines saved, and is associated with the intended pattern and tool.
- ☐ The agent is Active.
- ☐ The PO-1042 run's actual tool argument and response support the final answer.
- ☐ The missing-order-number request produces clarification without an invented lookup input.
- ☐ The PO-9999 and PO-5000 tests distinguish not found from unavailable.
- ☐ The relevant Agent instance ID, Conversation ID, integration instance ID, and runtime evidence have been recorded.
Completion evidence is not simply “the agent is Active.” The meaningful outcome is an observed order-status response supported by the actual tool execution, together with appropriate clarification when the identifier is absent and truthful handling when the lookup cannot establish a status.
What comes next: The natural next module is evaluating agent behavior across a controlled test set. Reuse the same synthetic integration and collect successful, missing-input, not-found, and unavailable results. You can then assess tool-selection accuracy, argument correctness, response-grounding quality, unnecessary repeated calls, and stopping behavior without expanding the prototype prematurely.
10. Five Useful FAQs
1. Does registering an integration as an agentic AI tool turn it into a different kind of integration?
No. The underlying integration implements the flow. Registration adds the tool metadata and parameter configuration that make the integration available for an AI agent to select and invoke. The integration still needs to meet the documented eligibility requirements.
2. If a parameter is marked Required, can I rely on the agent never supplying a wrong value?
No. Required metadata tells the LLM that it must provide a value when invoking the tool. It does not establish that the value is correct, that the order exists, or that the caller is authorized to access it. The integration must validate its received input and return a controlled result.
3. Why do I need both a Role and Guidelines?
The Role identifies the assistant's purpose. The Guidelines specify operational behavior, such as when to ask for clarification, which evidence to use, and how to respond to not-found or unavailable results. Both influence the LLM; neither replaces deterministic validation or authorization in the integration and target system.
4. Does an Active agent prove that its tool call works?
No. Activation is a lifecycle state. Runtime verification requires an actual run, evidence of appropriate tool selection and arguments, the integration's execution status and response, and a final answer consistent with that response.
5. Are an Agent instance ID, Conversation ID, and integration instance ID interchangeable?
No. The agent instance ID identifies an agent invocation; the Conversation ID can link multiple runs into a conversation; and the integration instance ID identifies a particular integration execution. Record the relevant identifiers together when diagnosing a run, and do not use the Conversation ID as though it uniquely identified one invocation.
11. Verified References
Use the current documentation displayed for your instance when a tenant's available features or UI differs.
- September 2026 (26.10) — Oracle Integration release notes. Release context, including the separately documented MCP Gateway capability.
- Register an Integration as an Agentic AI Tool. Integration eligibility, tool identifier, description, guidelines, and input-parameter metadata.
- Configure the Agentic AI Thinking Pattern. ReAct and Plan and Execute concepts, pattern lifecycle, Max iterations, and LLM connection configuration.
- Add and Configure the AI Agent. Agent description, pattern association, Role, Guidelines, tool association, and activation.
- Run and Test the AI Agent. Test Agent workflow, activity inspection, and project integration monitoring.
- Run an AI Agent with Knowledge of Previous Runs. Conversation IDs, instance relationship, and retrieval of conversation evidence.
- Tour of the Projects Workspace. Project design resources and Observe navigation.
- Track Instances in a Project. Integration instance status, activity streams, payload visibility, and logging considerations.

Comments
Post a Comment