Skip to main content

OIC AI Agents: Expose a Secured Agent Service to Applications

Calculating read time…

Imagine a procurement portal that lets an employee ask whether a purchase order has shipped. An Oracle Integration Project AI Agent can interpret the question and use an order-status integration to obtain current business information. The application still needs a dependable interface contract: which endpoint should it call, what must it send, how does it authenticate, and how can it continue a conversation without accessing another user's information?

A callable agent is not, by itself, a complete application service. A consumer-facing API needs deliberate boundaries between the application request, agent execution, and business-system permissions. A conversation identifier is not an identity, an HTTP success response does not prove that the business result is correct, and an agent's natural-language answer is not an authorization decision. This tutorial develops a secured REST-wrapper pattern for a Project AI Agent, focusing on request mapping, identity and conversation ownership, completion contracts, and evidence that can be independently verified.

The examples are design examples, not a report of a completed deployment. Product-specific statements are linked to Oracle documentation. Endpoint names, response schemas, error mappings, SQL objects, and session policies shown here are proposed implementation choices that must be tested in the target Oracle Integration instance.

1. What You Will Build

The outcome is a versioned, application-facing Procurement Agent API. It accepts an order-status request, authenticates the caller, validates business inputs, invokes an active Project AI Agent, and returns a controlled response. Where multi-turn conversations are required, a server-managed session registry associates an external conversation reference with the authenticated owner and the internal Oracle Integration conversation ID.

Illustrative consumer request

{
  "clientRequestId": "req-20261024-001",
  "orderNumber": "PO-100245",
  "question": "Has this order shipped?"
}

Illustrative completed response

{
  "clientRequestId": "req-20261024-001",
  "status": "SUCCEEDED",
  "conversationRef": "server-issued-reference",
  "result": {
    "answer": "The order-status tool reports that the order has shipped."
  }
}

These are proposed consumer-contract examples, not captured OIC responses. The wrapper must map the actual action output into this format and set the status only when execution evidence supports that outcome.

The reference use case is read-only. It does not authorize purchase-order changes, approvals, or payments. The minimum synchronous API can be built without a background-job platform. Durable asynchronous processing and user-specific multi-turn sessions require additional persistence and identity capabilities described later.

2. In This Post

  1. Before You Begin
  2. Agent Runtime Access Options
  3. Consumer REST API Design
  4. Agent Invocation Mapping
  5. Session and Conversation Ownership
  6. Synchronous and Asynchronous Completion
  7. Consumer Authentication and Authorization
  8. Build the Application-Facing API
  9. Consumer Testing and Evidence
  10. Troubleshooting and Recovery
  11. Enterprise Considerations
  12. Completion Checklist and Next Steps
  13. Five Useful FAQs
  14. References
  15. Finally — Summary

3. Before You Begin

This article uses Oracle Integration 3 release 26.10 as its documentation target. Feature availability, generated mapper fields, security choices, and exact runtime behavior can vary by environment and by the way an integration is configured. Confirm them in the target instance before publishing the service.

  • A Project AI Agent that can be activated and invoked. Its pattern, associated tools, and model configuration must fit the intended task.
  • An order-status integration with a documented JSON request and response. Use synthetic order data for the lab.
  • Permission to create and activate a REST-triggered integration and configure the supported OAuth client/security setup. Identity-domain administration may be required.
  • Postman or another approved HTTP client, plus the actual runtime endpoint and test credentials.
  • For multi-turn sessions, a durable session registry and a trustworthy source for the authenticated owner identity. These are additional design dependencies, not automatic results of activating an agent.

If the Project AI Agent has not been built, create or import that asset first. This article does not assume that a prior example agent, tool integration, identity configuration, or database has already been deployed.

4. Agent Runtime Access Options

4.1 Choose the invocation boundary first

Oracle Integration provides different ways to work with AI Agents. They solve different problems: testing an agent during design, invoking an agent from an integration, calling an agent endpoint directly where supported, or exposing integrations as tools to an MCP client.

Kid-friendly analogy

A school has a teacher's office for supervised practice, an internal phone for staff, and a public reception desk for visitors. They all provide access to the school, but visitors should not use a staff-only route simply because it exists.

In the agent, this means: The Test Agent screen, an AI Agent action, a direct agent endpoint, and a Project MCP server are distinct access mechanisms with different contracts and security boundaries.

Access mechanismPurposeEngineering decision
Test Agent interfaceRun an agent during design and inspect its behavior.Useful for diagnosis; it is not a consumer REST contract.
AI Agent action in an integrationStart an active Project AI Agent from an integration. Inputs include a prompt or a prompt-template identifier and payload; a conversation ID is optional.The preferred building block for this wrapper pattern.
Direct AI Agent endpointInvoke an agent through its endpoint where the runtime and security configuration support that access path.Obtain the actual endpoint and validate its authentication, request, response, and conversation behavior before exposing it as an application API.
Project MCP serverExpose registered integrations as MCP tools discoverable by compatible MCP clients.Use when an external agent needs those tools. Do not treat the Project MCP endpoint as the application-facing REST endpoint for invoking a Project AI Agent.
Consumer REST wrapperProvide a stable API contract in front of agent execution.Recommended when the application needs validation, controlled errors, authorization, session ownership, or a consumer schema independent of agent internals.

Oracle documents the AI Agent action for starting an active agent from an integration. Its mapping supports the project and agent selection, optional conversation ID, and either a prompt or a prompt-template identifier with payload. The payload for a template is stringified JSON. See Invoke an AI Agent from an Integration.

A direct REST endpoint is another possible route, but its exact generated path and security configuration must be obtained from the actual environment. Oracle's Agentic AI known-issues page documents a form under /ic/api/integration/v2/flows/rest/aiagent/project/ and warns that an incorrect URL can create conversation and agent-instance records even when invocation fails. This is a caution, not a complete endpoint specification for every configuration.

4.2 Keep the responsibilities separate

The agent runtime executes its configured behavior, chooses among available tools, and reasons over the information returned. The REST wrapper owns the application contract: accepting inputs, validating them, enforcing access rules, passing approved values to the agent, and returning a response the client understands.

A Project MCP server has a different job. Oracle's Project MCP documentation describes tool discovery and invocation through MCP operations such as tools/list and tools/call; it exposes registered integrations as tools. That does not turn the MCP server into an agent-invocation API. See FAQs for Projects as MCP Servers.

For this tutorial, put the agent invocation behind an OIC integration with a REST trigger. The public contract can then evolve independently of the internal agent, as long as the wrapper continues to honor the published schema and regression tests.

5. Consumer REST API Design

5.1 Design the API around a business task

An application-facing endpoint should describe a business operation, not expose the agent's internal implementation. For the reference use case, publish a path such as:

POST /procurement/agent/v1/requests
Content-Type: application/json
Authorization: Bearer <access-token>

This path is a proposed application contract, not an Oracle-mandated URL. Configure the REST trigger resource path using the capabilities shown in the target OIC design-time interface. The consumer API version is separate from the agent's version and the integration's version.

Kid-friendly analogy

A school lunch counter asks for a meal choice and a student number. It does not ask the student to explain the kitchen's internal workflow or select which cook handles the order.

In the agent, this means: The consumer sends business inputs such as an order number and a question, while the wrapper owns the agent identifier, prompt template, permitted operations, and response format.

5.2 Specify the fields and validation rules

FieldContract rulePurpose
clientRequestIdRequired correlation identifier, unique within an agreed caller scope.Correlates logs and tests. It does not enforce idempotency unless the service stores and checks it.
orderNumberRequired string. Validate its format against the real procurement contract.Identifies the business record to retrieve.
questionRequired string, or supply a documented server-side default; enforce a length limit.States the informational request without letting the consumer configure the agent itself.
conversationRefOptional server-issued reference for an existing conversation.Allows continuation only after the wrapper verifies ownership. Omit it to start a new conversation.

These rules are proposed for the tutorial. A team might choose a maximum question length of 500 characters, but that is an application design choice—not a claim about an Oracle AI Agent limit. Define and enforce limits at the wrapper, then test boundary values.

Do not accept arbitrary project identifiers, agent identifiers, prompt-template IDs, tool names, provider settings, or raw internal conversation IDs from the consumer. Those are implementation details the server should control unless a separately secured use case explicitly requires them.

5.3 Define success and error responses

Separate execution outcome from the natural-language answer. An agent can successfully run and report that an order was not found; that can be a successful execution with a business result of “not found.” A transport failure, authorization failure, or tool execution fault is different.

Illustrative application-level error body:

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "orderNumber is required",
    "correlationId": "req-20261024-001"
  }
}
Proposed HTTP statusExample condition
400Malformed JSON, missing field, or invalid request structure.
401Missing or invalid authentication credentials.
403Authenticated caller lacks permission for the operation.
404A conversation reference cannot be accessed. Returning the same result for unknown and non-owned references can reduce enumeration risk.
409A duplicate or concurrent request conflicts with the documented processing policy.
500Unexpected internal failure, without exposing sensitive diagnostics.

These statuses describe the proposed API behavior; they are not automatic OIC defaults. Configure and test the supported REST-trigger response and fault-handling behavior in the target instance. If OIC cannot produce the required public status/body contract for a case, revise the design or use an API facade. Do not claim an HTTP status works until it has been observed in a test.

6. Agent Invocation Mapping

6.1 Direct prompt versus prompt template

Oracle documents two choices for the AI Agent action: provide a direct prompt, or provide a prompt-template identifier and payload. Prompt templates use Liquid syntax to combine a defined prompt with variable data. See Send Dynamic Data to the AI Agent with Prompt Templates.

Kid-friendly analogy

A teacher uses the same worksheet for every student, filling in each student's name and exercise number. The instructions stay consistent while the supplied values change.

In the agent, this means: A prompt template preserves a reusable instruction structure and receives changing business values through a JSON payload, while a direct prompt constructs the full prompt for an individual request.

For the procurement API, prefer a server-managed template because the task instructions and permitted use are defined by the solution, not by each consumer. A suitable illustrative template is:

Check the current status of purchase order {{ orderNumber }}.

Answer the user's question: {{ question }}

Use the authorized order-status tool for current business facts.
If the tool reports that the order cannot be found, explain that result.
Do not invent an order status or take write actions.

The placeholder names correspond to fields in the template payload. The agent's Role and Guidelines should also define the intended behavior, evidence requirements, and tool-use constraints. Prompt templates and agent instructions are not substitutes for backend authorization or deterministic business validation.

6.2 Map the consumer payload to the action

A consumer might submit:

{
  "clientRequestId": "req-20261024-001",
  "orderNumber": "PO-100245",
  "question": "Has this order shipped?"
}

After validation, map the business values into the prompt-template payload:

{
  "orderNumber": "PO-100245",
  "question": "Has this order shipped?"
}

The Oracle AI Agent action documentation specifies that payload is stringified JSON and that the prompt-template identifier includes a version, with a documented example such as USER_PROMPT_TEMPLATE|01.00.0000. Use the identifier and version from your project. In the mapper, construct or map the payload according to the generated action schema; do not accidentally pass an object where the action expects a string.

ValueMapping decision
Project and agentSelect the intended active agent at design time; do not accept caller-supplied identifiers.
Prompt-template IDUse the approved template identifier and version recorded in the project.
PayloadMap validated business values into the template's defined JSON fields, serialized as required by the action.
Conversation IDFor a new session, either let Oracle generate the ID and capture it through a verified runtime path, or generate an ID server-side and pass that exact ID to the action. For this tutorial's registry pattern, use the latter so the mapping and stored identifier are explicit.
Agent responseUse fields actually exposed by the action's generated mapper. Normalize them into the public response schema.

Do not invent an agent response field name. Oracle documents the invocation inputs, but the exact response fields and final-answer mapping must be confirmed from the generated action schema and a real invocation in the target release.

6.3 Validate before invoking

Perform deterministic checks before starting the agent. Reject an empty order number, malformed JSON, unsupported identifier format, overlong question, or a conversation reference that fails ownership verification. If the requester cannot access a purchase order, deny the request in the authorization/business layer rather than asking the agent to decide access using natural-language instructions.

The checkpoint is an invocation whose inputs match the validated request, whose agent and template are server-controlled, and whose response can be correlated with the request. Verify the mapping and tool execution through OIC runtime evidence instead of treating the model's final text as proof that a tool ran successfully.

7. Session and Conversation Ownership

7.1 A conversation ID preserves context; it does not establish identity

Oracle documents that an AI Agent conversation ID is generated automatically by default unless a value is specified. A supplied ID can associate multiple runs with one conversation. Oracle also documents restrictions when a conversation is already in progress or waiting for a tool, and instance-level data retention applies. See Run an AI Agent with Knowledge of Previous Runs.

Kid-friendly analogy

A library keeps a folder of notes for each reading group. Knowing a folder number does not prove that a person belongs to that group; the librarian must check who is asking before opening it.

In the agent, this means: A conversation ID links agent context, while a separately verified caller identity and ownership check determine whether the caller may continue that conversation.

Separate three values:

  • Authenticated owner: A trusted principal derived from validated credentials, not a value copied from the request body.
  • Public conversation reference: An opaque identifier returned to the application.
  • Internal OIC conversation ID: The ID mapped to the AI Agent action. It should not be accepted directly from an untrusted consumer.

Use a durable registry to associate these values. An approved database or persistent session service can support session creation, owner-checked retrieval, expiry, and a concurrency policy. The registry is an additional application component; it is not an automatic OIC conversation-owner table.

An illustrative record is:

{
  "conversationRef": "public-reference-generated-by-server",
  "agentConversationId": "server-generated-id-passed-to-the-agent",
  "ownerKey": "verified-owner-from-authentication-layer",
  "status": "ACTIVE",
  "createdAt": "2026-10-24T10:00:00Z",
  "expiresAt": "2026-10-25T10:00:00Z"
}

Identifiers and timestamps are illustrative. Choose expiry, storage fields, and cleanup rules according to the data policy. Prefer a stable opaque subject key over unnecessary personal data.

7.2 Create and resolve a conversation safely

For this tutorial's registry pattern, generate the internal conversation ID on the trusted server side, persist it with a newly generated public reference and the authenticated owner, and pass that exact internal ID into the AI Agent action's optional conversation-ID field. Oracle documents that a conversation ID can be supplied to the action. This avoids assuming that the wrapper can retrieve an automatically generated ID from an output field that may not be exposed by the selected mapper.

When a consumer omits conversationRef, create the registry row before invoking the agent and pass the stored internal ID. If the invocation fails, mark the session or attempt according to the recovery policy; do not leave it appearing healthy without recording the fault. When the consumer supplies an existing reference, resolve it using both the reference and authenticated owner before mapping the internal ID.

IF conversationRef is absent:
    generate a public reference and internal conversation ID
    persist both IDs with the authenticated owner
    pass the stored internal conversation ID to the agent action
ELSE:
    load the session using conversationRef AND authenticated owner
    reject if missing, expired, inactive, or owned by another caller
    pass the stored internal conversation ID to the agent action

invoke the approved agent action

This is application logic, not executable OIC syntax. Implement it using the selected persistence adapter or session service. Generate IDs with a suitable server-side mechanism; enforce uniqueness, and do not let the consumer choose either ID.

OAuth client credentials normally identifies the calling application, not each human using that application. If every employee sends requests through one backend using the same client credentials, OIC cannot infer separate employee identities merely because each request contains a different user ID.

For person-level isolation, use a supported user-aware identity flow whose validated identity is available to the wrapper, or place a trusted identity-aware gateway/backend in front of OIC. If that layer validates the end user's token and then invokes OIC with a service credential, do not trust a plain caller-supplied subject header. Ensure only the trusted layer can invoke the protected integration, or use a supported signed identity assertion that the receiving layer validates. Prevent callers from bypassing the identity-aware layer by calling the OIC endpoint directly.

If the selected endpoint cannot obtain or securely receive the verified owner identity required by the design, user-level session reuse is blocked until that identity handoff is implemented and tested. Do not downgrade it to trusting a request-body field.

8. Synchronous and Asynchronous Completion

8.1 Decide what a successful HTTP response means

A synchronous consumer API responds after its defined processing path has completed or failed. This is suitable for a read-only order-status request when the agent path finishes inside agreed client and integration timeouts and the wrapper can obtain and normalize the final agent result.

Kid-friendly analogy

At a school office, a quick question can be answered at the desk. A request needing another department's work should receive a tracking number so the student can check later rather than wait indefinitely.

In the agent, this means: Return a final result synchronously only when the invocation has completed; otherwise use a durable asynchronous operation contract with status and result retrieval.

Do not promise synchronous completion merely because the REST trigger is synchronous. A long-running agent, a human approval, or an asynchronous tool can change the completion path. Confirm the actual behavior of the selected AI Agent action in the generated mapper and runtime trace before publishing a latency or completion guarantee.

8.2 Distinguish an asynchronous tool callback from an asynchronous public API

Oracle documents a callback mechanism for an AI Agent that invokes an asynchronous integration registered as an agentic AI tool. The tool integration sends a response back to the agent when it completes, allowing the agent to resume. That is an internal agent/tool lifecycle; it does not, by itself, define what the public application endpoint returns. See Send a Response to an AI Agent with a Callback.

For an application-facing asynchronous API, design a separate operation contract. The initial request should return an operation identifier only after the request has been durably recorded and processing has been accepted. For example:

{
  "operationId": "op-server-generated-id",
  "status": "ACCEPTED",
  "statusUrl": "/procurement/agent/v1/operations/op-server-generated-id"
}

The consumer can poll a status endpoint and retrieve the result when complete. Possible public states include ACCEPTED, RUNNING, SUCCEEDED, and FAILED. These are proposed wrapper states; map actual statuses to them through an explicit policy rather than assuming a one-to-one mapping.

Oracle provides an AI Agent action for retrieving the activity stream using a conversation ID. The response includes the agent status, so it can be one source of runtime evidence when designing status retrieval. See Get the Activity Stream for an AI Agent.

A durable asynchronous public API additionally needs persistent operation storage, a dispatch/worker mechanism, status transitions, failure persistence, authorization on status/result retrieval, and a recovery policy for the case where a request is accepted but the worker fails before the agent starts. These components are outside the minimum synchronous prototype.

9. Consumer Authentication and Authorization

9.1 Authenticate the caller before starting the agent

For the wrapper, protect the inbound REST trigger using a security policy supported by that REST trigger. Oracle documents OAuth grant options for protecting an integration's REST endpoint, including client credentials, authorization code, and JWT user assertion; Resource Owner Password Credentials is not recommended. The exact choice depends on whether the caller is an application acting for itself or a user-aware client. See Protect an Integration's REST Endpoint with OAuth.

Kid-friendly analogy

The school receptionist checks a visitor's pass before allowing entry. A valid pass does not mean the visitor can enter every locked room or approve school expenses.

In the agent, this means: Authentication establishes a caller identity; authorization determines which operation and business data that identity may access.

Choose the caller model deliberately:

  • Server-to-server application: Use a confidential client and the approved OAuth flow, commonly client credentials where the integration acts for the application itself. Keep the client secret on the server.
  • Application acting for an end user: Use a supported user-aware flow, such as an approved authorization-code or JWT-user-assertion design where applicable, or an identity-aware backend/gateway. Establish the user's verified identity before owner checks.
  • Browser or mobile client: Never embed a confidential client secret in downloadable client code. Use the organization's approved user-authentication and backend architecture.

Oracle's ServiceInvoker role is intended for callers that invoke integration endpoints without using the Developer APIs. Developer API roles and scopes must not be copied blindly into a consumer integration endpoint. See Invoke Oracle Integration Developer APIs from an External Client and the specific REST endpoint OAuth guidance linked above.

9.2 Enforce authorization at deterministic control points

The wrapper should enforce permission to invoke the business operation. The order-status integration or underlying business service should independently enforce which orders the verified subject may read. The agent may interpret returned information, but its instructions or final answer are not authorization controls.

  • Allow only the approved agent and intended tool set.
  • Validate order identifiers and enforce business permissions outside the model.
  • Check session ownership before mapping a stored conversation ID into the action.
  • Return sanitized client errors; keep sensitive diagnostics in protected operational logs.
  • Apply rate and request-size limits at the endpoint or approved gateway as required.

The Oracle Integration MCP Gateway introduced in 26.10 is a governed path for MCP clients to access Oracle Integration and approved third-party MCP servers. It should not be treated as a general-purpose REST API gateway or as a replacement for protecting this consumer REST endpoint. Secure each actual access path according to its own role.

10. Build the Application-Facing Procurement Agent API

The sequence below defines the prototype in dependency order. Standard integration work is concise; the focus is on agent inputs, consumer contracts, caller identity, session behavior, and evidence needed to prove completion.

Step 1 — Confirm the agent's callable business capability

Identify the active Project AI Agent and the order-status tool it is permitted to use. The tool should return deterministic business data, such as an order number, current status, last-update timestamp, and any approved shipment reference.

Contract elementIllustrative value
Request{"orderNumber":"PO-100245"}
Successful tool response{"orderNumber":"PO-100245","status":"SHIPPED","lastUpdated":"2026-10-24T09:15:00Z"}
Not-found responseA deterministic not-found result in the tool's agreed contract.

These values are synthetic examples; status vocabulary, timestamp format, and response fields must match the real tool contract. If the agent uses an integration as an agentic AI tool, follow that capability's registration prerequisites. Do not confuse registering an integration as a tool with publishing the application-facing agent API.

Checkpoint: Identify the active agent, intended tool, and deterministic tool-response schema. Do not assume a prior sample agent exists or has passed testing.

Step 2 — Define the REST trigger and public contract

Create a project integration named PROCUREMENT_AGENT_API. Add a REST trigger and define a POST request/response contract. The name is an example, not a reserved Oracle identifier.

Configuration itemDecision
Resource path/procurement/agent/v1/requests
HTTP methodPOST
Content typeapplication/json
AuthenticationThe approved OAuth policy and caller model for the REST trigger.
Request schemaThe public request contract documented in section 5.
Response schemaA normalized result/error contract independent of the action's generated schema.

The endpoint can be hosted directly by OIC if its authentication model meets the use case. If a trusted gateway is required to validate end-user tokens or establish a verified owner identity, configure access so callers cannot bypass that trust boundary and invoke the internal integration directly.

Checkpoint: The request and response schemas are saved; endpoint authentication, scopes, and invocation role are documented; and the deployed endpoint URL is taken from the actual instance.

Step 3 — Add validation and session resolution

Validate request fields and resolve the caller's authorized session before executing the AI Agent action. Keep deterministic checks ahead of the model call so malformed or unauthorized requests do not consume an agent invocation unnecessarily.

For multi-turn support, the wrapper or trusted session service needs these operations:

  • Create session: Generate a public conversation reference and an internal conversation ID server-side, persist their association with the authenticated owner, and pass the internal ID into the action.
  • Resolve session: Retrieve the internal ID only when the reference belongs to the current verified owner and is active.
  • Handle conflicts: Reject or serialize concurrent turns for the same conversation.
  • Expire session: Enforce application session expiry separately from OIC's instance-level data retention.

An Oracle Database table or an approved persistent service can implement the registry. This starter DDL is for an Oracle Database-backed implementation; it is not an OIC-generated schema.

CREATE TABLE AI_AGENT_CONVERSATION_ACCESS (
    CONVERSATION_REF       VARCHAR2(64)  PRIMARY KEY,
    AGENT_CONVERSATION_ID  VARCHAR2(64)  NOT NULL UNIQUE,
    OWNER_KEY              VARCHAR2(512) NOT NULL,
    CREATED_AT             TIMESTAMP     DEFAULT SYSTIMESTAMP NOT NULL,
    EXPIRES_AT             TIMESTAMP     NOT NULL,
    STATUS                 VARCHAR2(20)  DEFAULT 'ACTIVE' NOT NULL,
    CONSTRAINT AI_AGENT_CONV_STATUS_CK
      CHECK (STATUS IN ('ACTIVE', 'CLOSED', 'EXPIRED', 'BUSY'))
);

CREATE INDEX AI_AGENT_CONV_OWNER_IX
    ON AI_AGENT_CONVERSATION_ACCESS (OWNER_KEY, CREATED_AT);

The session service must generate both identifiers, persist the owner mapping, and pass the stored AGENT_CONVERSATION_ID to the AI Agent action. The database table alone does not implement authorization or concurrency control. Use transactions or equivalent atomic operations for creation, status transitions, and locking/lease behavior.

For an existing reference, the logical lookup predicate is:

conversation_ref = requested_ref
AND owner_key = verified_owner
AND status = 'ACTIVE'
AND expires_at > SYSTIMESTAMP

If the identity layer cannot supply a trustworthy owner key, do not enable cross-request conversation reuse. Treat it as blocked until the trusted identity handoff is implemented and tested.

Step 4 — Add the AI Agent action and map its inputs

In the integration canvas, add the AI Agent action, select the intended active project and agent, and configure the start-agent operation. Oracle documents that the agent must be active and that a mapper is created for the action parameters.

Map these values according to the actual generated action schema:

  • Conversation ID: The new server-generated internal ID for a new session, or the stored ID from an ownership-validated lookup.
  • Prompt-template ID: The approved template identifier and version configured for the agent.
  • Payload: Stringified JSON containing the validated orderNumber and question.
  • Response: Map the action's actual output fields to the wrapper's public result schema. Inspect the generated mapper rather than assuming output field names.

If using direct prompts instead of templates, ensure only validated business fields are incorporated and that the consumer cannot replace the server-managed instruction set. A prompt template is useful for consistency, but it does not guarantee protection against prompt injection or malicious business inputs.

Checkpoint: A controlled test invocation shows the expected order number in the tool call, a legitimate tool response, and the agent's final answer in runtime evidence. Record the actual output mapping and any differences from the proposed contract.

Step 5 — Normalize the result and handle faults

Map observed successful action output into the public response. Return the caller's correlation ID and public conversation reference where applicable. Set the public execution status only from a confirmed completion path.

Distinguish at least three failure classes: request validation or authorization errors before agent invocation; faults from the OIC integration or agent/tool execution; and business outcomes such as an order not being found. Define stable error codes and sanitized messages. Do not return raw prompts, access tokens, exception stacks, provider responses, or internal tool diagnostics to the consumer.

If the action does not expose the final answer in the required shape, inspect its output schema and runtime activity stream. Do not manufacture a result from the fact that an agent instance was created or from an HTTP 200 response alone.

Checkpoint: The public response schema is populated from observed action output, and an injected tool/agent failure produces the documented error contract instead of a fabricated success message.

Step 6 — Decide how clients retrieve status and results

For the synchronous path, return a final answer only after the execution is confirmed complete. For multi-turn sessions, accept a public conversation reference and resolve it through the owner check before passing the internal ID to the agent.

If the agent requires asynchronous tools or can wait for a human response, add the separate asynchronous operation model before presenting the service as an asynchronous API. This requires durable operation state, a dispatch path, status retrieval, result persistence, and failure recovery. The OIC activity-stream action can provide agent status evidence, but an application-facing operation store is still needed when the API promises durable tracking independent of a long-running HTTP connection.

Checkpoint: Document which completion contract the deployed service actually implements. Mark asynchronous acceptance and result retrieval as not implemented until the operation store and dispatch path exist and have been tested.

11. Consumer Testing and Evidence

11.1 Send a valid authenticated request

In Postman, configure authentication for the endpoint and caller model. Use the actual runtime integration URL. Do not paste credentials or tokens into the article, screenshots, or shared logs.

POST <actual-runtime-url>/procurement/agent/v1/requests

Content-Type: application/json
Authorization: Bearer <valid-test-token>

{
  "clientRequestId": "req-20261024-001",
  "orderNumber": "PO-100245",
  "question": "Has this order shipped?"
}

Expected behavior: validate the request, invoke the intended agent, and return a normalized response if synchronous completion has been implemented. Confirm the response against the order-status tool output and agent activity trace. The answer text alone is insufficient proof of successful tool execution.

11.2 Verify negative cases and ownership controls

Record the actual HTTP status, response body, correlation ID, and relevant integration/agent evidence for each test. The table describes expected results only; it does not claim that these tests have been executed.

Test caseExpected behaviorEvidence to inspect
Valid request and authorized callerThe correct agent runs and the normalized response reflects the business tool result.HTTP response, wrapper integration instance, agent activity stream, and tool input/output.
Missing order number or malformed JSONA controlled client error is returned; no agent invocation should occur when validation is before the action.HTTP status, error schema, and absence of a new agent run for that request.
Missing or invalid tokenThe request is rejected at the authentication boundary.HTTP response and security evidence; no authorized business operation should begin.
Authenticated caller without permissionThe request is denied before the protected operation occurs.Authorization decision and absence of unauthorized tool execution.
Caller B submits caller A's conversation referenceThe owner check rejects the request and does not disclose caller A's conversation data.Session lookup, owner identity, response body, and absence of an agent continuation.
Conversation reference expired or unknownThe wrapper rejects reuse and applies the documented expiry behavior.Registry state, error contract, and no continuation of an expired session.
Order-status tool failsThe result is reported as a controlled execution failure; no invented status is presented as fact.Tool integration fault, agent trace, wrapper fault mapping, and public response.
Concurrent requests for one conversationRequests follow the documented serialization or conflict policy; context is not mixed unintentionally.Registry locking/state, agent status, and both responses.

11.3 Prove completion at more than one layer

Use the wrapper's HTTP response to test the public contract, the OIC integration instance to inspect mapping and fault handling, the AI Agent activity stream to inspect agent status and tool interaction, and the session registry to verify ownership. These observations establish different facts; none substitutes for the others.

For asynchronous execution, inspect status at multiple points rather than assuming that an accepted request has completed. Verify that the status endpoint exposes a final result only after the worker/agent has completed according to the chosen contract.

Mark every case Not executed until the test has actually run and its evidence has been captured. The expected results in this article are a test specification, not a report of successful tenant execution.

12. Troubleshooting and Recovery

SymptomLikely causeTargeted correction
401 or 403 on the consumer endpointInvalid token, incorrect scope/role, or endpoint policy mismatch.Verify the trigger's actual security policy, token audience/scope, identity-domain configuration, and required invocation role.
404 for a direct agent URLIncorrect path, project/agent code, version, or endpoint.Verify the generated endpoint and published path. Oracle warns that an incorrect agent URL can leave conversation and instance records despite a failed invocation.
Agent receives empty or malformed template dataIncorrect payload field names, object/string mismatch, or template-placeholder mismatch.Compare the request, mapped stringified JSON, template placeholders, and action schema. Retry with a minimal known payload.
Conversation continuation failsWrong ID, expired session, owner mismatch, conversation still in progress, or an older-agent issue.Verify the registry mapping, owner, expiry, and agent status. Review Oracle's known-issues guidance, especially for agents created before 26.04.
HTTP success with an incorrect business answerTool not selected, tool failure obscured, stale data, or response-mapping defect.Inspect the tool call and returned data, then correct agent/tool behavior or wrapper mapping. HTTP 200 alone does not prove correctness.
Request waits too long or times outSlow tool, extended reasoning path, callback wait, or inconsistent timeout settings.Inspect duration and agent status. Reduce unnecessary work or implement durable asynchronous completion instead of increasing timeouts without evidence.
Error response exposes internalsRaw adapter fault, model response, or stack trace returned directly.Normalize the public error and retain detailed diagnostics only in protected operational logs.

After troubleshooting, preserve the public contract and rerun the affected positive and negative cases. Remove synthetic sessions/test records according to the lab's data-retention policy, but do not delete records required to investigate an unresolved execution.

13. Enterprise Considerations

Before promoting the wrapper beyond a lab, close the design decisions that affect identity, conversation behavior, retry safety, and operations:

  • Identity: Decide whether permissions are per application or per human. Shared client credentials do not distinguish the people using the application.
  • Conversation retention: Set session expiry, registry cleanup, and OIC instance retention to meet data-handling requirements.
  • Idempotency: If clients may retry after a timeout, store request outcomes against a documented idempotency key. The clientRequestId can serve that role only if the contract explicitly defines its uniqueness scope and the service persists/checks outcomes; a correlation ID alone does not prevent duplicate processing.
  • Concurrency: Prevent simultaneous requests from unexpectedly continuing the same conversation. Oracle documents that a conversation in progress or waiting for a tool cannot necessarily be started again with the same ID.
  • Information exposure: Log correlation IDs, status, duration, and approved business identifiers. Avoid bearer tokens, secrets, unnecessary personal data, or full sensitive prompts.
  • Change management: Version the consumer API independently from the agent and integration. Regression-test contract compatibility when changing prompt templates, agent behavior, or action mappings.
  • Human approval and writes: If a later version changes orders or initiates approvals, add deterministic authorization, approval-state management, idempotency, and recovery for uncertain outcomes. A read-only prototype does not establish those controls.

Implement controls in the API, identity, storage, integration, and business-system layers that own them. Do not delegate security decisions to prompt wording alone.

14. Completion Checklist and Next Steps

Use this checklist to record evidence from the actual tenant:

  • The consumer REST contract and actual deployed endpoint URL are documented.
  • Authentication rejects missing or invalid credentials.
  • Malformed and invalid business requests are rejected before agent invocation.
  • The intended agent receives the correct template payload and conversation ID.
  • The public response is mapped from observed action output, not inferred from HTTP success alone.
  • The wrapper and agent evidence can be correlated through a request identifier.
  • Cross-owner conversation reuse is rejected, or multi-turn support stays disabled until trusted identity and session storage are available.
  • Synchronous completion is demonstrated by an actual test, or asynchronous acceptance and result retrieval are explicitly marked as not yet implemented.

Minimum evidence for the synchronous prototype is a valid consumer request, its OIC execution, the agent/tool result, and the normalized response. Conversation ownership additionally requires evidence for identity handoff, registry creation, and a cross-owner rejection test.

A natural next module is to operationalize the service: add durable asynchronous request tracking where needed, measurable agent/tool evaluations, and production monitoring without exposing internal agent details to callers.

15. Five Useful FAQs

1. Can an application call a Project AI Agent directly without an OIC wrapper?

A direct agent endpoint is a documented invocation route, but the exact path, authentication, and request/response contract must be confirmed in the target instance. A wrapper is preferable when the consumer needs stable schemas, validation, authorization, consistent errors, session ownership, or a contract that can remain stable as the internal agent evolves.

2. Is enabling MCP for a project the same as exposing an agent API?

No. A Project MCP server makes registered integrations discoverable as MCP tools. An application-facing REST wrapper invokes the Project AI Agent and defines the application's request/response contract. The capabilities can coexist, but they are not interchangeable.

3. Should a consumer pass its own conversation ID?

Normally, the application should receive an opaque server-issued conversation reference. The wrapper resolves it against the authenticated owner and obtains the internal OIC conversation ID from trusted server-side state. Knowing a conversation ID is not proof of authorization to reuse it.

4. Does an HTTP 200 response prove that the agent answered correctly?

No. It confirms only what the endpoint's HTTP contract says it confirms. Verify the wrapper execution path, agent activity stream, actual tool request/response, and business data behind the answer. Normalize technical failures and business-level not-found outcomes separately.

5. Can client-credentials OAuth isolate conversations between employees?

Not by itself when all employees share the same application identity. Client credentials authenticates the application, not each individual user. Person-level isolation needs a supported user-aware identity flow or a trusted identity-aware backend/gateway, plus owner checks in the conversation registry.

16. Additional References

The consumer REST contract, error mapping, registry schema, and sample outputs are proposed implementation choices rather than Oracle-defined artifacts.

  1. September 2026 (26.10) — Oracle Integration release notes. Release context, including the MCP Gateway announcement.
  2. Invoke an AI Agent from an Integration. Active-agent prerequisite, action configuration, conversation ID, prompt, template identifier, and payload.
  3. Send Dynamic Data to the AI Agent with Prompt Templates. Liquid syntax and template/payload behavior.
  4. Run an AI Agent with Knowledge of Previous Runs. Conversation association, default ID generation, and retention considerations.
  5. Get the Activity Stream for an AI Agent. Retrieving agent status through an integration action.
  6. Send a Response to an AI Agent with a Callback. Internal asynchronous agent/tool callback behavior.
  7. FAQs for Projects as MCP Servers. Project MCP boundaries, registered tools, and supported operations.
  8. Agentic AI Issues. Published endpoint and conversation-ID caveats.
  9. Protect an Integration's REST Endpoint with OAuth. OAuth options for securing REST-triggered integrations.
  10. Invoke Oracle Integration Developer APIs from an External Client. Developer API grant/role distinctions, used here as a security reference—not as a claim that the consumer agent endpoint is itself a Developer API.

17. Finally — Summary

A secured agent service is more than an endpoint that accepts a prompt. It is a controlled contract between an application, the OIC integration layer, and the Project AI Agent.

The main engineering decisions are to expose a business-focused REST contract, map only validated fields into the approved agent and template, and separate conversation context from caller identity. Multi-turn support requires a trusted owner identity and durable session state. An opaque conversation reference alone does not establish ownership.

For session creation, either use Oracle's generated conversation ID and capture it through a verified runtime path, or explicitly generate an internal ID on the trusted server side and pass that same value to the AI Agent action. This tutorial uses the second pattern so the registry mapping is clear. Test conversation reuse and concurrency against the target release, including the published caveats for agents created before 26.04.

Promise synchronous completion only after an actual invocation confirms how the selected agent finishes and how its response is mapped. Asynchronous execution requires explicit acceptance, status, result retrieval, and recovery behavior; internal agent callbacks do not automatically create an asynchronous consumer API.

The practical milestone is evidence: an authenticated request, the expected tool execution, a normalized response, and negative tests proving that malformed requests and unauthorized conversation reuse are rejected. This article defines a verification path; it does not claim the prototype has already been executed in an OIC tenant.

A logical next step is to build the durable asynchronous operation path and monitoring strategy required by agents that wait for tools, external processes, or human approval.

Comments