openapi: 3.2.0 info: description: 'OCI Generative AI Agents is a fully managed service that combines the power of large language models (LLMs) with an intelligent retrieval system to create contextually relevant answers by searching your knowledge base, making your AI applications smart and efficient. OCI Generative AI Agents supports several ways to onboard your data and then allows you and your customers to interact with your data using a chat interface or API. Use the Generative AI Agents Client API to create and manage client chat sessions. A session represents an interactive conversation initiated by a user through an API to engage with an agent. It involves a series of exchanges where the user sends queries or prompts, and the agent responds with relevant information, actions, or assistance based on the user''s input. The session persists for the duration of the interaction, maintaining context and continuity to provide coherent and meaningful responses throughout the conversation. For creating and managing agents, knowledge bases, data sources, endpoints, and data ingestion jobs see the [Generative AI Agents Management API](#/EN/generative-ai-agents/latest/). To learn more about the service, see the [Generative AI Agents documentation](/iaas/Content/generative-ai-agents/home.htm). ' title: Generative AI Agents Client Generative AI Agent Runtime API version: '20240531' x-provenance: method: harvested first_party: true publisher: Oracle source: https://docs.oracle.com/en-us/iaas/api/specs/bf4b7af77dfd39c9c34297d12be8df00a34a5208317a36ad856d1fe0ce6e969d.yaml harvested: '2026-08-04' note: Published by Oracle as the contract for the Generative AI Agents Client API OCI service and stored verbatim; API Evangelist added only this provenance block. x-evidence: - url: https://docs.oracle.com/en-us/iaas/api/specs/index.json what: Oracle's own index of every OCI service specification - url: https://docs.oracle.com/en-us/iaas/api/specs/bf4b7af77dfd39c9c34297d12be8df00a34a5208317a36ad856d1fe0ce6e969d.yaml what: the harvested document for Generative AI Agents Client API servers: - url: http://127.0.0.1/20240531 - url: https://127.0.0.1/20240531 tags: - name: generativeAiAgentRuntime paths: /agentEndpoints/{agentEndpointId}/actions/chat: post: description: 'Chat on endpoint with provided messages. ' operationId: Chat parameters: - $ref: '#/components/parameters/AgentEndpointIdentifierPathParam' - $ref: '#/components/parameters/RequestIdHeader' - $ref: '#/components/parameters/IfMatchHeader' - $ref: '#/components/parameters/RetryTokenHeader' responses: 200: description: The chat response was successfully generated. headers: opc-request-id: description: 'Unique Oracle-assigned identifier for the request. If you need to contact Oracle about a particular request, please provide the request ID. ' schema: type: string content: application/json: schema: $ref: '#/components/schemas/ChatResult' text/event-stream: schema: $ref: '#/components/schemas/ChatResult' 400: $ref: '#/components/responses/400' 401: $ref: '#/components/responses/401' 404: $ref: '#/components/responses/404' 409: $ref: '#/components/responses/409' 412: $ref: '#/components/responses/412' 429: $ref: '#/components/responses/429' 500: $ref: '#/components/responses/500' default: $ref: '#/components/responses/default' summary: Chat with endpoint tags: - generativeAiAgentRuntime x-related-resource: '#/definitions/AgentEndpoint' requestBody: content: application/json: schema: $ref: '#/components/schemas/ChatDetails' description: Input for chat. required: true /agentEndpoints/{agentEndpointId}/sessions: post: description: 'A session represents an interactive conversation initiated by a user through an API to engage with an agent. It involves a series of exchanges where the user sends queries or prompts, and the agent responds with relevant information, actions, or assistance based on the user''s input. The session persists for the duration of the interaction, maintaining context and continuity to provide coherent and meaningful responses throughout the conversation.Creates an agent session. Use this API to create an agent session. ' operationId: CreateSession parameters: - $ref: '#/components/parameters/AgentEndpointIdentifierPathParam' - $ref: '#/components/parameters/RetryTokenHeader' - $ref: '#/components/parameters/RequestIdHeader' responses: 200: description: The session was created. headers: etag: description: 'For optimistic concurrency control. See `if-match`. ' schema: type: string opc-request-id: description: 'Unique Oracle-assigned identifier for the request. If you need to contact Oracle about a particular request, please provide the request ID. ' schema: type: string content: application/json: schema: $ref: '#/components/schemas/Session' 400: $ref: '#/components/responses/400' 401: $ref: '#/components/responses/401' 404: $ref: '#/components/responses/404' 409: $ref: '#/components/responses/409' 429: $ref: '#/components/responses/429' 500: $ref: '#/components/responses/500' default: $ref: '#/components/responses/default' summary: Creates an agent Session. tags: - generativeAiAgentRuntime x-related-resource: '#/definitions/Session' requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateSessionDetails' description: Details for the new agent session. required: true /agentEndpoints/{agentEndpointId}/sessions/{sessionId}: delete: description: 'Delete a session and all its associated information. ' operationId: DeleteSession parameters: - $ref: '#/components/parameters/AgentEndpointIdentifierPathParam' - $ref: '#/components/parameters/SessionIdentifierPathParam' - $ref: '#/components/parameters/IfMatchHeader' - $ref: '#/components/parameters/RequestIdHeader' responses: 204: description: The session was deleted. headers: opc-request-id: description: 'Unique Oracle-assigned identifier for the request. If you need to contact Oracle about a particular request, please provide the request ID. ' schema: type: string 400: $ref: '#/components/responses/400' 401: $ref: '#/components/responses/401' 404: $ref: '#/components/responses/404' 412: $ref: '#/components/responses/412' 429: $ref: '#/components/responses/429' 500: $ref: '#/components/responses/500' default: $ref: '#/components/responses/default' summary: Delete a session and all associated information. tags: - generativeAiAgentRuntime x-related-resource: '#/definitions/Session' get: description: 'Return the session resource identified by the session ID. ' operationId: GetSession parameters: - $ref: '#/components/parameters/AgentEndpointIdentifierPathParam' - $ref: '#/components/parameters/SessionIdentifierPathParam' - $ref: '#/components/parameters/RequestIdHeader' responses: 200: description: The session was retrieved. headers: etag: description: 'For optimistic concurrency control. See `if-match`. ' schema: type: string opc-request-id: description: 'Unique Oracle-assigned identifier for the request. If you need to contact Oracle about a particular request, please provide the request ID. ' schema: type: string content: application/json: schema: $ref: '#/components/schemas/Session' 400: $ref: '#/components/responses/400' 401: $ref: '#/components/responses/401' 404: $ref: '#/components/responses/404' 429: $ref: '#/components/responses/429' 500: $ref: '#/components/responses/500' default: $ref: '#/components/responses/default' summary: Return the session resource identified by the session ID. tags: - generativeAiAgentRuntime put: description: 'Update session metadata, including but not limited to description, tags. ' operationId: UpdateSession parameters: - $ref: '#/components/parameters/AgentEndpointIdentifierPathParam' - $ref: '#/components/parameters/SessionIdentifierPathParam' - $ref: '#/components/parameters/IfMatchHeader' - $ref: '#/components/parameters/RequestIdHeader' responses: 200: description: The session was updated. headers: etag: description: 'For optimistic concurrency control. See `if-match`. ' schema: type: string opc-request-id: description: 'Unique Oracle-assigned identifier for the request. If you need to contact Oracle about a particular request, please provide the request ID. ' schema: type: string content: application/json: schema: $ref: '#/components/schemas/Session' 400: $ref: '#/components/responses/400' 401: $ref: '#/components/responses/401' 404: $ref: '#/components/responses/404' 412: $ref: '#/components/responses/412' 429: $ref: '#/components/responses/429' 500: $ref: '#/components/responses/500' default: $ref: '#/components/responses/default' summary: Update session metadata, including but not limited to description, tags. tags: - generativeAiAgentRuntime x-related-resource: '#/definitions/Session' requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateSessionDetails' description: Details to update an agent session. required: true /knowledgeBases/{knowledgeBaseId}/actions/retrieveMetadata: post: description: 'Returns metadata of provided knowledgeBase. Return available metadata with information of field names, their types, supported operations, and possible values. ' operationId: RetrieveMetadata parameters: - $ref: '#/components/parameters/KnowledgeBaseIdentifierPathParam' - $ref: '#/components/parameters/RequestIdHeader' - $ref: '#/components/parameters/IfMatchHeader' - $ref: '#/components/parameters/RetryTokenHeader' responses: 200: description: Successfully retrieved metadata headers: etag: description: 'For optimistic concurrency control. See `if-match`. ' schema: type: string opc-request-id: description: 'Unique Oracle-assigned identifier for the request. If you need to contact Oracle about a particular request, please provide the request ID. ' schema: type: string content: application/json: schema: description: List of metadata available in the knowledge base items: $ref: '#/components/schemas/KnowledgeBaseMetadataSummary' type: array 400: $ref: '#/components/responses/400' 401: $ref: '#/components/responses/401' 404: $ref: '#/components/responses/404' 409: $ref: '#/components/responses/409' 412: $ref: '#/components/responses/412' 429: $ref: '#/components/responses/429' 500: $ref: '#/components/responses/500' default: $ref: '#/components/responses/default' summary: Retrieve Metadata of knowledge base tags: - generativeAiAgentRuntime x-related-resource: '#/definitions/KnowledgeBaseMetadataSummary' requestBody: content: application/json: schema: $ref: '#/components/schemas/RetrieveMetadataDetails' description: Input for retrieve metadata. required: true components: schemas: Session: description: 'A session represents an interactive conversation initiated by a user through an API to engage with an agent. It involves a series of exchanges where the user sends queries or prompts, and the agent responds with relevant information, actions, or assistance based on the user''s input. The session persists for the duration of the interaction, maintaining context and continuity to provide coherent and meaningful responses throughout the conversation. ' properties: description: description: A description of the session. type: string displayName: description: A user-friendly name. Does not have to be unique, and it's changeable. Avoid entering confidential information. maxLength: 255 minLength: 1 type: string id: description: A unique ID for the session. This ID is immutable on creation. type: string timeCreated: description: The date and time that the session started in the format of an RFC3339 datetime string. format: date-time type: string timeUpdated: description: The date and time that the session was last updated in the format of an RFC3339 datetime string. format: date-time type: string welcomeMessage: description: A greeting message that the you receive when you start of a session. type: string required: - id - timeCreated type: object MetadataFilter: description: 'Filter for retrieving specific metadata ' properties: fieldName: description: The name of the field to filter on type: string value: description: The value to filter for in the specified field type: string required: - fieldName - value type: object Paragraph: description: 'The paragraph of the generated message that contains a citation. ' properties: end: description: Where the text with a citation ends in the generated message. type: integer start: description: Where the text with a citation starts in the generated message. type: integer text: description: The part of the generated message that contains a citation. type: string required: - text - start - end type: object SourceDetails: description: 'The details of source of the event. ' properties: key: description: Id of the source of the event. type: string name: description: Name of the source of the event. type: string type: object Error: description: 'The error message information. ' properties: code: description: A short error code that defines the error and is used for programmatic parsing. type: string message: description: A human-readable message. type: string required: - code - message CreateSessionDetails: description: 'Information about the new session. ' properties: description: description: An optional description of the session. type: string displayName: description: The name of the session. A session names doesn't have to be unique and you can change the session name later. maxLength: 255 minLength: 1 type: string type: object ChatDetails: description: 'Chat details for managing user interactions and tool executions. ' properties: performedActions: description: A list of actions that have been performed based on prior required actions. items: $ref: '#/components/schemas/PerformedAction' maxItems: 128 type: array sessionId: description: Optional sessionId. If not provided, will chat without any prior context. type: string shouldStream: default: false description: Whether to stream the response. type: boolean toolInputs: description: 'Array of tool input objects, each specifying a tool''s ID, type, and corresponding input parameters required for execution. ' items: $ref: '#/components/schemas/ToolInput' maxItems: 128 type: array toolParameters: additionalProperties: type: string description: A map where each key is a toolId and the value contains tool type and additional dynamic parameters. This field is deprecated and will be removed after July 02 2026. type: object userMessage: description: The input user message content for the chat. type: string type: object ParagraphCitation: description: 'The source of information for the paragraph of agent''s response. ' properties: citations: description: A list of citations for the paragraph of the generated message. items: $ref: '#/components/schemas/Citation' type: array paragraph: $ref: '#/components/schemas/Paragraph' required: - paragraph type: object Message: description: 'The Message resource generated by the agent. ' properties: content: $ref: '#/components/schemas/MessageContent' role: description: The role of the sender of this message. enum: - USER - AGENT type: string timeCreated: description: The date and time that the message was created in the format of an RFC3339 datetime string. format: date-time type: string required: - role - content type: object RetrieveMetadataDetails: description: 'Details to retrieve metadata ' properties: filters: description: List of metadata filters to narrow down the retrieved metadata items: $ref: '#/components/schemas/MetadataFilter' type: array type: object ToolOutput: description: 'Base schema for tool outputs. Identified by `toolOutputType`, which determines the format of the output content. ' discriminator: propertyName: toolOutputType properties: toolId: description: Specifies the unique OCID of the tool. maxLength: 255 type: string toolName: description: Specifies the display name of the tool. maxLength: 255 type: string toolOutputType: description: Specifies the type of tool output (e.g., GENERIC_TOOL_OUTPUT, SQL_TOOL_OUTPUT). enum: - GENERIC_TOOL_OUTPUT - SQL_TOOL_OUTPUT - RAG_TOOL_OUTPUT type: string required: - toolId - toolOutputType type: object Citation: description: 'The source of information for the agent''s response. ' properties: docId: description: The id of the retrieved document, if available. type: string metadata: additionalProperties: type: object description: The metadata of the retrieved document, if available. type: object pageNumbers: description: The page numbers on the retrieved document, if available. items: type: integer type: array sourceLocation: $ref: '#/components/schemas/SourceLocation' sourceText: description: The text that's the source for the agent's response. type: string title: description: The title of the source text, if available. type: string type: object KnowledgeBaseMetadataSummary: description: 'Represents metadata about a field including its name, type, supported operations, and possible values. ' properties: definedTags: additionalProperties: additionalProperties: type: object type: object description: 'Defined tags for this resource. Each key is predefined and scoped to a namespace. Example: `{"foo-namespace": {"bar-key": "value"}}` ' type: object freeformTags: additionalProperties: type: string description: 'Simple key-value pair that is applied without any predefined name, type or scope. Exists for cross-compatibility only. Example: `{"bar-key": "value"}` ' type: object name: description: The name of the field type: string operations: description: List of supported operations for this field (e.g., "equals", "in", "contains") items: type: string type: array systemTags: additionalProperties: additionalProperties: type: object type: object description: 'System tags for this resource. Each key is predefined and scoped to a namespace. Example: `{"orcl-cloud": {"free-tier-retained": "true"}}` ' type: object type: description: The data type of the field (e.g., "array", "number", "string") type: string values: description: List of metadata values available in the knowledge base along with the matching documents count. items: $ref: '#/components/schemas/KnowledgeBaseMetadataValue' type: array required: - name - type - operations - values type: object ToolInput: description: 'Base object for tool input parameters. The ''toolInputType'' discriminator determines the specific input structure to be used. ' discriminator: propertyName: toolInputType properties: toolId: description: Unique OCID of the tool. maxLength: 255 type: string toolInputType: description: Specifies the type of tool input (e.g., GENERIC_TOOL_INPUT). enum: - GENERIC_TOOL_INPUT type: string required: - toolId - toolInputType type: object MessageContent: description: 'The content of the message. ' properties: citations: description: Citations to data sources used for generating an agent's message. items: $ref: '#/components/schemas/Citation' type: array paragraphCitations: description: A list of citations used to generate the paragraphs of the agent message. items: $ref: '#/components/schemas/ParagraphCitation' type: array text: description: The content of the message. type: string required: - text type: object RequiredAction: description: 'Represents an action that needs to be performed by the user or client. ' discriminator: propertyName: requiredActionType properties: actionId: description: The unique identifier for the action to be performed. type: string requiredActionType: description: Specifies the type of action. Used for determining the action subtype. enum: - HUMAN_APPROVAL_REQUIRED_ACTION - FUNCTION_CALLING_REQUIRED_ACTION type: string required: - actionId - requiredActionType type: object KnowledgeBaseMetadataValue: description: 'Represents a metadata value and the number of appearances in knowledge base. ' properties: count: description: Number of documents where this value exists format: int64 type: integer value: description: The value of the metadata type: string required: - value - count type: object ChatResult: description: 'The response of a chat request. ' properties: guardrailResult: description: Captures the result of guardrail evaluations as JSON string performed on either the input to the agent or the output generated by the agent. type: string message: $ref: '#/components/schemas/Message' requiredActions: description: 'A list of actions the agent requires the user or agent client to perform. ' items: $ref: '#/components/schemas/RequiredAction' maxItems: 128 type: array toolOutputs: description: "Array of tool outputs in execution order. Each item includes the tool OCID, output type, \nand corresponding content. The result structure is defined by the `toolOutputType` discriminator.\n" items: $ref: '#/components/schemas/ToolOutput' maxItems: 128 type: array toolResults: additionalProperties: type: string description: A map where each key is a toolId and the value contains tool type and additional dynamic results. This field is deprecated and will be removed after July 02 2026. type: object traces: description: The trace that displays the internal progression, such as reasoning and actions during an execution. items: $ref: '#/components/schemas/Trace' type: array type: object Trace: description: 'The trace that displays the internal progression, such as reasoning and actions during an execution. ' discriminator: propertyName: traceType properties: key: description: Unique identifier for the event (UUID). type: string parentKey: description: Identifier of the parent event, if applicable (UUID). type: string source: $ref: '#/components/schemas/SourceDetails' timeCreated: description: The date and time that the trace was created in the format of an RFC3339 datetime string. format: date-time type: string timeFinished: description: Timestamp for when the event ended (In RFC 3339). format: date-time type: string traceType: description: The type of the trace. enum: - ERROR_TRACE - RETRIEVAL_TRACE - GENERATION_TRACE - TOOL_INVOCATION_TRACE - PLANNING_TRACE - EXECUTION_TRACE type: string required: - traceType type: object PerformedAction: description: 'The base structure for an action that has already been performed. ' discriminator: propertyName: performedActionType properties: actionId: description: The unique identifier for the action that has been performed. type: string performedActionType: description: Specifies the type of the performed action. enum: - HUMAN_APPROVAL_PERFORMED_ACTION - FUNCTION_CALLING_PERFORMED_ACTION type: string required: - actionId - performedActionType type: object SourceLocation: description: 'The location of the data files that the agent will use. ' discriminator: propertyName: sourceLocationType properties: sourceLocationType: description: The type of the data source that contains data files for the agent. enum: - OCI_OBJECT_STORAGE - OCI_OPEN_SEARCH - OCI_DATABASE type: string required: - sourceLocationType UpdateSessionDetails: description: 'Information about the updated session. ' properties: description: description: A description of the session. type: string displayName: description: The name of the session. A session names doesn't have to be unique and you can change the session name later. maxLength: 255 minLength: 1 type: string type: object responses: default: description: Unknown Error headers: opc-request-id: description: 'Unique Oracle-assigned identifier for the request. If you need to contact Oracle about a particular request, please provide the request ID. ' schema: type: string content: application/json: schema: $ref: '#/components/schemas/Error' parameters: AgentEndpointIdentifierPathParam: description: A unique ID for the endpoint. in: path name: agentEndpointId required: true schema: type: string IfMatchHeader: description: 'For optimistic concurrency control. In the PUT or DELETE call for a resource, set the `if-match` parameter to the value of the etag from a previous GET or POST response for that resource. The resource will be updated or deleted only if the etag you provide matches the resource''s current etag value. ' in: header name: if-match required: false schema: type: string KnowledgeBaseIdentifierPathParam: description: A unique ID for the Knowledge Base. in: path name: knowledgeBaseId required: true schema: type: string SessionIdentifierPathParam: description: A unique ID for the session. in: path name: sessionId required: true schema: type: string RetryTokenHeader: description: 'A token that uniquely identifies a request so it can be retried in case of a timeout or server error without risk of executing that same action again. Retry tokens expire after 24 hours, but can be invalidated before then due to conflicting operations. For example, if a resource has been deleted and purged from the system, then a retry of the original creation request might be rejected. ' in: header name: opc-retry-token required: false schema: type: string maxLength: 64 minLength: 1 RequestIdHeader: description: The client request ID for tracing. in: header name: opc-request-id schema: type: string x-anchors: x-headers: etag: description: 'For optimistic concurrency control. See `if-match`. ' type: string opc-next-page: description: 'For pagination of a list of items. When paging through a list, if this header appears in the response, then a partial list might have been returned. Include this value as the `page` parameter for the subsequent GET request to get the next batch of items. ' type: string opc-request-id: description: 'Unique Oracle-assigned identifier for the request. If you need to contact Oracle about a particular request, please provide the request ID. ' type: string opc-work-request-id: description: 'The [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the asynchronous work request. Use GetWorkRequest with this ID to track the status of the request. ' type: string x-properties: definedTags: additionalProperties: additionalProperties: type: object type: object description: 'Defined tags for this resource. Each key is predefined and scoped to a namespace. Example: `{"foo-namespace": {"bar-key": "value"}}` ' type: object freeformTags: additionalProperties: type: string description: 'Simple key-value pair that is applied without any predefined name, type or scope. Exists for cross-compatibility only. Example: `{"bar-key": "value"}` ' type: object systemTags: additionalProperties: additionalProperties: type: object type: object description: 'System tags for this resource. Each key is predefined and scoped to a namespace. Example: `{"orcl-cloud": {"free-tier-retained": "true"}}` ' type: object x-obmcs-client-retries-enabled: true x-oracle-package: com.oracle.oci.ocas.agent.runtime