How to Use OCI Generative AI Agents#

OCI GenAI Agents is a service to create agents in the OCI console. These agents are defined remotely, including their tools, prompts, and optional documents for retrieval-augmented generation (RAG), and can be used for inference.

In this guide, you will learn how to use an OCI agent in Agent Spec using the OciAgent class from the pyagentspec package.

Basic usage#

To get started, first create your OCI GenAI Agent in the OCI Console. Consult the OCI documentation for detailed steps.

Next, create an OciClientConfig object to configure the connection to the OCI service. See the OCI LLM configuration for detailed instructions how to configure this object.

You will also need the agent_endpoint_id from the OCI Console. This ID points to the agent you want to connect to, while the client configuration is about connecting to the entire service.

Once these are in place, you can create your agent in a few lines:

from pyagentspec.llms.ociclientconfig import OciClientConfigWithApiKey
from pyagentspec.ociagent import OciAgent

# Typical service endpoint for OCI GenAI service inference
# <oci region> can be "us-chicago-1" and can also be found in your ~/.oci/config file
OCIGENAI_ENDPOINT = "https://inference.generativeai.<oci region>.oci.oraclecloud.com"

oci_config = OciClientConfigWithApiKey(
    name="oci_client_config",
    service_endpoint=OCIGENAI_ENDPOINT,
    auth_profile="DEFAULT",
    auth_file_location="~/.oci/config",
)

agent = OciAgent(
    name="oci_agent",
    agent_endpoint_id="AGENT_ENDPOINT",
    client_config=oci_config,
)

Note that the OciAgent is an extension of RemoteAgent in Agent Spec, which is considered an AgenticComponent. It follows that OCI agents can be used in AgentNodes inside Agent Spec flows.

Agent Spec Serialization#

You can export the agent configuration using AgentSpecSerializer.

from pyagentspec.serialization import AgentSpecSerializer

serialized_agent = AgentSpecSerializer().to_json(agent)

print(serialized_agent)

Here is what the Agent Spec representation will look like ↓

Click here to see the assistant configuration.
{
    "component_type": "OciAgent",
    "id": "0a1817a0-2ed0-4fed-9c7b-87b5547d35e4",
    "name": "oci_agent",
    "description": null,
    "metadata": {},
    "inputs": [],
    "outputs": [],
    "agent_endpoint_id": "AGENT_ENDPOINT",
    "client_config": {
        "component_type": "OciClientConfigWithApiKey",
        "id": "b7eb33c7-fecb-4f28-85bc-2d85f8baca5f",
        "name": "oci_client_config",
        "description": null,
        "metadata": {},
        "service_endpoint": "https://inference.generativeai.<oci region>.oci.oraclecloud.com",
        "auth_type": "API_KEY",
        "auth_profile": "DEFAULT",
        "auth_file_location": "~/.oci/config"
    },
    "agentspec_version": "25.4.1"
}

Recap#

This how-to guide covered how to define an OCI Generative AI Agent in Agent Spec.

Below is the complete code from this guide.
 1from pyagentspec.llms.ociclientconfig import OciClientConfigWithApiKey
 2from pyagentspec.ociagent import OciAgent
 3
 4# Typical service endpoint for OCI GenAI service inference
 5# <oci region> can be "us-chicago-1" and can also be found in your ~/.oci/config file
 6OCIGENAI_ENDPOINT = "https://inference.generativeai.<oci region>.oci.oraclecloud.com"
 7
 8oci_config = OciClientConfigWithApiKey(
 9    name="oci_client_config",
10    service_endpoint=OCIGENAI_ENDPOINT,
11    auth_profile="DEFAULT",
12    auth_file_location="~/.oci/config",
13)
14
15agent = OciAgent(
16    name="oci_agent",
17    agent_endpoint_id="AGENT_ENDPOINT",
18    client_config=oci_config,
19)

Next steps#

Now that you have learned how to use OCI agents in Agent Spec, you may proceed to How to Use Agents in Flows.