How to Integrate with OCI Generative AI Using Embabel Agent

Embabel Agent enables zero-configuration OCI Generative AI integration through Spring Boot auto-configuration that automatically registers Oracle Cloud Infrastructure client beans when the OCI SDK is present on the classpath.

Embabel Agent streamlines Oracle Cloud Infrastructure (OCI) Generative AI integration by providing dedicated auto-configuration modules that eliminate boilerplate setup. This guide demonstrates how to connect your Spring Boot applications to OCI LLMs and embedding models using the embabel/embabel-agent repository, requiring only dependency additions and minimal property configuration.

Prerequisites and Dependencies

To activate the OCI integration, add the OCI Generative AI auto-configuration module and the OCI SDK to your project dependencies.

Maven Configuration

<dependency>
    <groupId>com.embabel</groupId>
    <artifactId>embabel-agent-oci-genai-autoconfigure</artifactId>
    <version>0.12.0</version>
</dependency>

<dependency>
    <groupId>com.oracle.bmc</groupId>
    <artifactId>oci-generative-ai-inference</artifactId>
    <version>1.0.0</version>
</dependency>

The auto-configuration activates only when the com.oracle.bmc.generativeaiinference.GenerativeAiInference class is detected on the classpath.

Auto-Configuration Architecture

The integration relies on two core components that handle bean registration and default property injection.

AgentOciGenAiAutoConfiguration

Located at embabel-agent-autoconfigure/models/embabel-agent-oci-genai-autoconfigure/src/main/java/com/embabel/agent/autoconfigure/models/ocigenai/AgentOciGenAiAutoConfiguration.java, this Spring Boot auto-configuration class imports OciGenAiClientConfig and OciGenAiModelsConfig to expose the OCI client as a managed bean. It serves as the entry point that wires the OCI SDK into the Embabel Agent abstraction layer.

OciGenAiEnvironmentPostProcessor

The OciGenAiEnvironmentPostProcessor, found in the same package path, implements EnvironmentPostProcessor to inject default model identifiers when no user-defined values exist. According to the source code in OciGenAiEnvironmentPostProcessor.java, it automatically sets:

• embabel.models.default-llm to cohere.command-a-03-2025
• embabel.models.default-embedding-model to cohere.embed-v4.0

This ensures immediate functionality without manual configuration while allowing overrides through standard Spring Boot property files.

Configuration Properties

Override the default OCI models by specifying values in application.yml or application.properties:

embabel:
  models:
    default-llm: cohere.command-a-03-2025
    default-embedding-model: cohere.embed-v4.0

Because these property keys are standardized across all Embabel Agent providers, you can switch between OCI, OpenAI, and Anthropic models by changing values without modifying Java code.

Implementing LLM Services

Once the dependencies are present, inject the GenerativeAiInference bean to interact with OCI language models.

Text Generation

import com.oracle.bmc.generativeaiinference.GenerativeAiInference;
import com.oracle.bmc.generativeaiinference.model.GenerateTextDetails;
import com.oracle.bmc.generativeaiinference.responses.GenerateTextResponse;
import org.springframework.stereotype.Service;

@Service
public class OciGenAiService {

    private final GenerativeAiInference client;

    public OciGenAiService(GenerativeAiInference client) {
        this.client = client;
    }

    public String generate(String prompt) {
        GenerateTextDetails request = GenerateTextDetails.builder()
                .prompt(prompt)
                .modelId("cohere.command-a-03-2025")
                .build();

        GenerateTextResponse response = client.generateText(request);
        return response.getGeneratedText();
    }
}

Embedding Generation

import com.oracle.bmc.generativeaiinference.GenerativeAiInference;
import com.oracle.bmc.generativeaiinference.model.EmbedTextDetails;
import com.oracle.bmc.generativeaiinference.responses.EmbedTextResponse;
import org.springframework.stereotype.Service;

@Service
public class OciEmbeddingService {

    private final GenerativeAiInference client;

    public OciEmbeddingService(GenerativeAiInference client) {
        this.client = client;
    }

    public float[] embed(String text) {
        EmbedTextDetails request = EmbedTextDetails.builder()
                .text(text)
                .modelId("cohere.embed-v4.0")
                .build();

        EmbedTextResponse response = client.embedText(request);
        return response.getEmbedding();
    }
}

Multi-Provider Support

The architecture supports runtime provider switching through property changes alone. To migrate from OCI to OpenAI, update your configuration:

embabel:
  models:
    default-llm: gpt-4o-mini
    default-embedding-model: text-embedding-3-small

The same service classes function without modification because Embabel Agent abstracts provider-specific implementations behind standardized property keys.

Summary

• Auto-configuration triggers when com.oracle.bmc:oci-generative-ai-inference is on the classpath, specifically detecting the GenerativeAiInference class.
• Default models are automatically injected by OciGenAiEnvironmentPostProcessor using OCI-specific defaults (cohere.command-a-03-2025 for LLMs, cohere.embed-v4.0 for embeddings).
• Zero code changes are required to switch between OCI, OpenAI, and other providers—only property values in application.yml need adjustment.
• Source files implementing this integration include AgentOciGenAiAutoConfiguration.java and OciGenAiEnvironmentPostProcessor.java in the embabel-agent-oci-genai-autoconfigure module.

Frequently Asked Questions

What triggers the OCI Generative AI auto-configuration?

The AgentOciGenAiAutoConfiguration class activates only when the GenerativeAiInference class from the OCI SDK is present on the classpath. This conditional loading ensures that OCI beans are registered only when the required Oracle Cloud Infrastructure libraries are available, preventing startup failures in environments without OCI dependencies.

Can I override the default OCI model identifiers?

Yes. While the OciGenAiEnvironmentPostProcessor automatically supplies defaults (cohere.command-a-03-2025 for LLMs and cohere.embed-v4.0 for embeddings), you can override these by defining embabel.models.default-llm and embabel.models.default-embedding-model in your Spring Boot configuration files.

How do I switch from OCI to another provider like OpenAI?

Change the property values for embabel.models.default-llm and embabel.models.default-embedding-model to the desired provider's model identifiers (for example, gpt-4o-mini for OpenAI). The same Java service code works across providers because Embabel Agent uses standardized property keys and abstraction layers, as verified in OciGenAiEnvironmentPostProcessorTest.java.

Where are the OCI integration tests located?

Unit tests confirming the auto-configuration behavior and property injection logic reside in OciGenAiEnvironmentPostProcessorTest.java and AgentOciGenAiAutoConfigurationTest.java within the embabel-agent-autoconfigure/models/embabel-agent-oci-genai-autoconfigure/src/test/java directory. These tests demonstrate both default property loading and provider-override scenarios.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}