fix: llm gateway completions api

Author: cosmyo

packages/uipath-openai-agents/samples/rag-assistant/AGENTS.md

@@ -1,230 +1,21 @@
-# OpenAI Agents SDK with UiPath Integration
+# Agent Code Patterns Reference
 
-This document provides patterns for building coded agents using the **OpenAI Agents SDK** with UiPath.
+This document provides practical code patterns for building UiPath coded agents using the UiPath Python SDK.
 
 ---
 
-## Quick Reference
+## Documentation Structure
 
-### Agent Pattern (OpenAI Agents SDK)
+This documentation is split into multiple files for efficient context loading. Load only the files you need:
 
-```python
-from agents import Agent, Runner
+1. **@.agent/REQUIRED_STRUCTURE.md** - Agent structure patterns and templates
+   - **When to load:** Creating a new agent or understanding required patterns
+   - **Contains:** Required Pydantic models (Input, Output), SDK initialization patterns, standard agent template
 
-# Define your agent
-my_agent = Agent(
-    name="my_agent",
-    instructions="You are a helpful assistant...",
-    model="gpt-4o",  # Optional: defaults to gpt-4o
-    tools=[],  # Optional: add tools for capabilities
-)
+2. **@.agent/SDK_REFERENCE.md** - Complete SDK API reference
+   - **When to load:** Calling UiPath SDK methods, working with services (actions, assets, jobs, etc.)
+   - **Contains:** All SDK services and methods with full signatures and type annotations
 
-# Register in openai_agents.json:
-# {
-#   "agents": {
-#     "agent": "main.py:my_agent"
-#   }
-# }
-```
-
-### Input Format
-
-OpenAI Agents use **simple message input**:
-
-```json
-{
-  "message": "Your question here"
-}
-```
-
-Or for conversation history:
-
-```json
-{
-  "messages": [
-    {"role": "user", "content": "First message"},
-    {"role": "assistant", "content": "Response"},
-    {"role": "user", "content": "Follow-up"}
-  ]
-}
-```
-
-**No Pydantic Input/Output models required** - the runtime handles conversion automatically!
-
----
-
-## Key Concepts
-
-### 1. Agent Definition
-
-```python
-from agents import Agent
-
-assistant = Agent(
-    name="assistant_agent",  # Used in logs and diagrams
-    instructions="Your system prompt here",
-    model="gpt-4o",  # Optional
-    tools=[tool1, tool2],  # Optional
-)
-```
-
-### 2. Running Agents
-
-**Via UiPath CLI** (recommended):
-```bash
-uipath run agent --file input.json
-```
-
-**Programmatically**:
-```python
-from agents import Runner
-
-result = await Runner.run(
-    starting_agent=assistant,
-    input="User message"  # or list of message dicts
-)
-```
-
-### 3. Tools (for RAG, APIs, etc.)
-
-```python
-from agents import tool
-
-@tool
-async def search_docs(query: str) -> str:
-    """Search documentation for relevant info."""
-    # Implementation here
-    return results
-
-# Add to agent:
-agent = Agent(
-    name="rag_agent",
-    tools=[search_docs],
-    instructions="Use search_docs to find information before answering."
-)
-```
-
-### 4. UiPath Integration
-
-The runtime **automatically injects UiPathChatOpenAI** client when credentials are available:
-
-```bash
-# Set these environment variables:
-export UIPATH_URL="https://your-tenant.uipath.com"
-export UIPATH_ORGANIZATION_ID="your-org-id"
-export UIPATH_TENANT_ID="your-tenant-id"
-export UIPATH_ACCESS_TOKEN="your-token"
-```
-
-All agents will use **UiPath LLM Gateway** instead of direct OpenAI!
-
----
-
-## Project Structure
-
-```
-my-agent/
-├── main.py              # Agent definition
-├── openai_agents.json   # Agent registration
-├── pyproject.toml       # Dependencies
-├── input.json           # Test input
-├── .env                 # Credentials (gitignored)
-└── uipath.json          # Runtime config (auto-generated)
-```
-
----
-
-## Common Patterns
-
-### Basic Q&A Agent
-
-```python
-from agents import Agent
-
-qa_agent = Agent(
-    name="qa_agent",
-    instructions="Answer questions concisely and accurately."
-)
-```
-
-### Agent with Tools (RAG)
-
-```python
-from agents import Agent, tool
-
-@tool
-async def retrieve_context(query: str) -> str:
-    """Retrieve relevant context from knowledge base."""
-    # Use UiPath Context Grounding or custom retriever
-    return context
-
-rag_agent = Agent(
-    name="rag_agent",
-    instructions="Use retrieve_context before answering questions.",
-    tools=[retrieve_context]
-)
-```
-
-### Multi-Agent (Handoffs)
-
-```python
-from agents import Agent
-
-specialist = Agent(
-    name="specialist",
-    instructions="You are a domain expert..."
-)
-
-coordinator = Agent(
-    name="coordinator",
-    instructions="Route requests to the specialist when needed.",
-    handoffs=[specialist]
-)
-```
-
----
-
-## Testing
-
-```bash
-# Initialize project
-uipath init
-
-# Run agent
-uipath run agent --file input.json
-
-# With inline input
-uipath run agent '{"message": "Hello!"}'
-
-# Debug mode
-uipath run agent --debug --file input.json
-```
-
----
-
-## Differences from LangGraph/LlamaIndex
-
-| Aspect | OpenAI Agents SDK | LangGraph/LlamaIndex |
-|--------|-------------------|----------------------|
-| **Input** | `{"message": "..."}` | Pydantic Input model required |
-| **Output** | Free-form response | Pydantic Output model required |
-| **Agent Type** | Agentic (LLM decides) | Workflow-based (fixed graph) |
-| **Tools** | `@tool` decorator | Custom tool classes |
-| **Registration** | `openai_agents.json` | `uipath.json` functions |
-
----
-
-## Resources
-
-- **OpenAI Agents SDK**: https://github.com/openai/openai-agents-python
-- **UiPath Python SDK**: https://uipath.github.io/uipath-python/
-- **Samples**: Check `samples/` directory for examples
-
----
-
-## Getting Help
-
-If you need assistance:
-- Check sample projects in `samples/`
-- Review OpenAI Agents SDK documentation
-- Open issues at https://github.com/anthropics/claude-code/issues
+3. **@.agent/CLI_REFERENCE.md** - CLI commands documentation
+   - **When to load:** Working with `uipath init`, `uipath run`, or `uipath eval` commands
+   - **Contains:** Command syntax, options, usage examples, and workflows

packages/uipath-openai-agents/samples/rag-assistant/entry-points.json

@@ -4,7 +4,7 @@
     "entryPoints": [
         {
             "filePath": "agent",
-            "uniqueId": "f3f04855-8064-46b5-a746-929568a6224d",
+            "uniqueId": "31b69d3d-4ae1-4caa-be64-b2fe368590a7",
             "type": "agent",
             "input": {
                 "type": "object",

packages/uipath-openai-agents/samples/rag-assistant/main.py

@@ -34,6 +34,7 @@ class Output(BaseModel):
 # Define the assistant agent
 assistant_agent = Agent(
     name="assistant_agent",
+    model="gpt-4o-2024-11-20",  # Use specific version supported by UiPath LLM Gateway
     instructions="""You are a helpful AI assistant that provides clear, concise answers.
 
 Your capabilities:

packages/uipath-openai-agents/src/uipath_openai_agents/chat/openai.py

@@ -11,10 +11,13 @@
 from .supported_models import OpenAIModels
 
 
-def _rewrite_openai_url(original_url: str, params: httpx.QueryParams) -> httpx.URL:
+def _rewrite_openai_url(
+    original_url: str, params: httpx.QueryParams
+) -> httpx.URL | None:
     """Rewrite OpenAI URLs to UiPath gateway completions endpoint.
 
-    Handles URL patterns from OpenAI SDK and rewrites them to .../completions
+    Handles URL patterns from OpenAI SDK and rewrites to /completions.
+    The X-UiPath-LlmGateway-ApiFlavor header determines API behavior.
 
     Args:
         original_url: Original URL from OpenAI SDK
@@ -23,12 +26,15 @@ def _rewrite_openai_url(original_url: str, params: httpx.QueryParams) -> httpx.U
     Returns:
         Rewritten URL pointing to UiPath completions endpoint
     """
-    if "/chat/completions" in original_url:
+    # Extract base URL before endpoint path
+    if "/responses" in original_url:
+        base_url = original_url.split("/responses")[0]
+    elif "/chat/completions" in original_url:
         base_url = original_url.split("/chat/completions")[0]
     elif "/completions" in original_url:
         base_url = original_url.split("/completions")[0]
     else:
-        # Handle base URL case
+        # Handle base URL case - strip query string
         base_url = original_url.split("?")[0]
 
     new_url_str = f"{base_url}/completions"
@@ -46,7 +52,8 @@ def __init__(self, verify: bool = True, **kwargs):
     async def handle_async_request(self, request: httpx.Request) -> httpx.Response:
         """Handle async request with URL rewriting."""
         new_url = _rewrite_openai_url(str(request.url), request.url.params)
-        request.url = new_url
+        if new_url:
+            request.url = new_url
         return await super().handle_async_request(request)
 
 
@@ -59,7 +66,8 @@ def __init__(self, verify: bool = True, **kwargs):
     def handle_request(self, request: httpx.Request) -> httpx.Response:
         """Handle sync request with URL rewriting."""
         new_url = _rewrite_openai_url(str(request.url), request.url.params)
-        request.url = new_url
+        if new_url:
+            request.url = new_url
         return super().handle_request(request)
 
 
@@ -95,25 +103,28 @@ class UiPathChatOpenAI:
     def __init__(
         self,
         token: Optional[str] = None,
-        model_name: str = OpenAIModels.gpt_4o,
+        model_name: str = OpenAIModels.gpt_4o_2024_11_20,
         api_version: str = "2024-12-01-preview",
         org_id: Optional[str] = None,
         tenant_id: Optional[str] = None,
         agenthub_config: Optional[str] = None,
         extra_headers: Optional[dict[str, str]] = None,
         byo_connection_id: Optional[str] = None,
+        api_flavor: str = "responses",
     ):
         """Initialize UiPath OpenAI client.
 
         Args:
             token: UiPath access token (defaults to UIPATH_ACCESS_TOKEN env var)
-            model_name: Model to use (e.g., "gpt-4o")
+            model_name: Model to use (e.g., "gpt-4o-2024-11-20")
             api_version: OpenAI API version
             org_id: UiPath organization ID (defaults to UIPATH_ORGANIZATION_ID env var)
             tenant_id: UiPath tenant ID (defaults to UIPATH_TENANT_ID env var)
             agenthub_config: Optional AgentHub configuration
             extra_headers: Additional headers to include in requests
             byo_connection_id: Bring-your-own connection ID
+            api_flavor: API flavor to use - "responses" (default, recommended for agents),
+                       "chat-completions" (traditional chat), or "auto" (let UiPath decide)
         """
         # Get credentials from env vars if not provided
         self._org_id = org_id or os.getenv("UIPATH_ORGANIZATION_ID")
@@ -140,6 +151,7 @@ def __init__(
         self._vendor = "openai"
         self._agenthub_config = agenthub_config
         self._byo_connection_id = byo_connection_id
+        self._api_flavor = api_flavor
         self._extra_headers = extra_headers or {}
 
         # Build base URL and headers
@@ -175,7 +187,7 @@ def __init__(
     def _build_headers(self) -> dict[str, str]:
         """Build headers for UiPath LLM Gateway."""
         headers = {
-            "X-UiPath-LlmGateway-ApiFlavor": "auto",
+            "X-UiPath-LlmGateway-ApiFlavor": self._api_flavor,
             "Authorization": f"Bearer {self._token}",
         }
 
@@ -195,17 +207,22 @@ def _build_headers(self) -> dict[str, str]:
 
     @property
     def endpoint(self) -> str:
-        """Get the UiPath endpoint for this model."""
+        """Get the UiPath endpoint for this model (without query parameters)."""
         vendor_endpoint = EndpointManager.get_vendor_endpoint()
         formatted_endpoint = vendor_endpoint.format(
             vendor=self._vendor,
             model=self._model_name,
         )
+        # Remove /completions suffix - will be added by URL rewriting
         base_endpoint = formatted_endpoint.replace("/completions", "")
-        return f"{base_endpoint}?api-version={self._api_version}"
+        return base_endpoint
 
     def _build_base_url(self) -> str:
-        """Build the base URL for OpenAI client."""
+        """Build the base URL for OpenAI client.
+
+        Note: Query parameters like api-version are added by the URL rewriting logic,
+        not in the base URL, to allow the SDK to append paths properly.
+        """
         env_uipath_url = os.getenv("UIPATH_URL")
 
         if env_uipath_url: