Documented compatible frameworks don't work out of the box

[fede-kamel]

Problem

The OCI Enterprise AI Agents documentation states:

Compatible agent frameworks include: OpenAI Agents SDK, OpenAI Codex SDK, Microsoft Agent Framework, LangChain, LangGraph, CrewAI, AutoGen, LlamaIndex, Pydantic

None of these frameworks (besides the raw OpenAI SDK) work out of the box with the /openai/v1 endpoint. Two issues compound:

1. OpenAI-Project header is mandatory but non-standard

The /openai/v1 endpoint requires an OpenAI-Project header with the GenAI Project OCID on every request. The raw OpenAI SDK supports this via project=. But ChatOpenAI (LangChain), Agent (PydanticAI), LLM (CrewAI), etc. have no project parameter. There is no way to set this header through their public API without workarounds.

2. OCI IAM signing requires custom HTTP client

OCI IAM auth requires a custom httpx.Auth handler to sign requests. Only frameworks that accept a custom http_client= parameter can use it. Frameworks that create their own HTTP clients internally (CrewAI, AutoGen) cannot.

Impact

A developer following Oracle's docs will write:

from langchain_openai import ChatOpenAI
llm = ChatOpenAI(
    model="openai.gpt-5.2",
    base_url="https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/openai/v1",
    api_key=os.getenv("OCI_GENAI_API_KEY"),
    # project=PROJECT_OCID  ← doesn't exist in ChatOpenAI
)

This fails. Every other cloud provider's OpenAI-compatible endpoint (Together AI, Groq, Fireworks, Azure) works with these frameworks by just swapping base_url and api_key. OCI is the only one that requires workarounds.

Workaround

Pass a pre-configured httpx.Client with the OpenAI-Project header and OCI signing:

http_client = httpx.Client(
    auth=OciUserPrincipalAuth(profile_name="DEFAULT"),
    headers={"OpenAI-Project": PROJECT_OCID},
)
llm = ChatOpenAI(model=..., http_client=http_client, api_key="not-used", ...)

This works for LangChain, PydanticAI, and OpenAI Agents SDK (which accept http_client). CrewAI, AutoGen, and LlamaIndex require additional framework-specific hacks.

Proposal

Add builder functions to oci-genai-auth that encapsulate the workaround for each framework. PR #11 implements this for the frameworks that support it cleanly (LangChain, PydanticAI, OpenAI Agents SDK).