From 14db6cbf4e1fa287e3ddc728eb74631dd219d223 Mon Sep 17 00:00:00 2001 From: siddharthsambharia-portkey Date: Mon, 1 Sep 2025 16:59:00 +0530 Subject: [PATCH 1/2] pydantic ai docs --- integrations/agents/pydantic-ai.mdx | 504 +++++++-------- .../administration/llm-access-api-guide.mdx | 583 ++++++++++++++++++ 2 files changed, 795 insertions(+), 292 deletions(-) create mode 100644 product/administration/llm-access-api-guide.mdx diff --git a/integrations/agents/pydantic-ai.mdx b/integrations/agents/pydantic-ai.mdx index aaa43bc8..52ea3e9b 100644 --- a/integrations/agents/pydantic-ai.mdx +++ b/integrations/agents/pydantic-ai.mdx @@ -14,7 +14,7 @@ Portkey enhances PydanticAI with production-readiness features, turning your exp - **Cost tracking and optimization** to manage your AI spend - **Access to 1600+ LLMs** through a single integration - **Guardrails** to keep agent behavior safe and compliant -- **Version-controlled prompts** for consistent agent performance +- **OpenTelemetry integration** for comprehensive monitoring Learn more about PydanticAI's core concepts and features @@ -25,45 +25,35 @@ Portkey enhances PydanticAI with production-readiness features, turning your exp ```bash -pip install -U pydantic-ai portkey-ai +pip install -U pydantic-ai openai ``` - -Create a Portkey API key with optional budget/rate limits from the [Portkey dashboard](https://app.portkey.ai/). You can attach configurations for reliability, caching, and more to this key. - - -For a simple setup, first configure the Portkey client that will be used with PydanticAI: +Since Portkey is OpenAI SDK compatible, you can use the standard OpenAI client with Portkey's gateway URL: ```python -from portkey_ai import AsyncPortkey +from openai import AsyncOpenAI +from pydantic_ai import Agent +from pydantic_ai.models.openai import OpenAIModel +from pydantic_ai.providers.openai import OpenAIProvider -# Set up Portkey client with appropriate metadata for tracking -portkey_client = AsyncPortkey( +# Set up Portkey client using OpenAI SDK +portkey_client = AsyncOpenAI( api_key="YOUR_PORTKEY_API_KEY", - provider="@YOUR_PROVIDER", - trace_id="unique-trace-id", # Optional, for request tracing - metadata={ # Optional, for request segmentation - "app_env": "production", - "_user": "user_123" # Special _user field for user analytics - } + base_url="https://api.portkey.ai/v1" ) ``` -After setting up your Portkey client, you can integrate it with PydanticAI by connecting it to a model provider: +After setting up your Portkey client, integrate it with PydanticAI: ```python -from pydantic_ai import Agent -from pydantic_ai.models.openai import OpenAIModel -from pydantic_ai.providers.openai import OpenAIProvider - -# Connect Portkey client to a PydanticAI model via provider +# Connect Portkey client to a PydanticAI model agent = Agent( model=OpenAIModel( - model_name="gpt-4o", + model_name="@openai-team-1/gpt-4o", # Use Portkey's model format provider=OpenAIProvider(openai_client=portkey_client), ), system_prompt="You are a helpful assistant." @@ -77,18 +67,16 @@ agent = Agent( Let's create a simple structured output agent with PydanticAI and Portkey. This agent will respond to a query about Formula 1 and return structured data: ```python -from portkey_ai import AsyncPortkey +from openai import AsyncOpenAI from pydantic import BaseModel, Field from pydantic_ai import Agent from pydantic_ai.models.openai import OpenAIModel from pydantic_ai.providers.openai import OpenAIProvider -# Set up Portkey client with tracing and metadata -portkey_client = AsyncPortkey( +# Set up Portkey client +portkey_client = AsyncOpenAI( api_key="YOUR_PORTKEY_API_KEY", - provider="@YOUR_OPENAI_PROVIDER", - trace_id="f1-data-request", - metadata={"app_env": "production", "_user": "user_123"} + base_url="https://api.portkey.ai/v1" ) # Define structured output using Pydantic @@ -101,7 +89,7 @@ class F1GrandPrix(BaseModel): # Create the agent with structured output type f1_gp_agent = Agent[None, F1GrandPrix]( model=OpenAIModel( - model_name="gpt-4o", + model_name="@openai-team-1/gpt-4o", provider=OpenAIProvider(openai_client=portkey_client), ), output_type=F1GrandPrix, @@ -136,28 +124,58 @@ print(result.output) ## Advanced Features +### Using Portkey Headers for Enhanced Features + +When you need additional Portkey features like tracing, metadata, or configs, you can add headers to your client: + +```python +from openai import AsyncOpenAI +from pydantic_ai import Agent +from pydantic_ai.models.openai import OpenAIModel +from pydantic_ai.providers.openai import OpenAIProvider + +# Set up Portkey client with additional features +portkey_client = AsyncOpenAI( + api_key="YOUR_PORTKEY_API_KEY", + base_url="https://api.portkey.ai/v1", + default_headers={ + "x-portkey-trace-id": "f1-data-request", + "x-portkey-metadata": '{"app_env": "production", "_user": "user_123"}', + "x-portkey-config": "your-config-id" + } +) + +# Create agent with enhanced Portkey features +agent = Agent( + model=OpenAIModel( + model_name="@openai-team-1/gpt-4o", + provider=OpenAIProvider(openai_client=portkey_client), + ), + system_prompt="You are a helpful assistant." +) +``` + ### Working with Images PydanticAI supports multimodal inputs including images. Here's how to use Portkey with a vision model: ```python -from portkey_ai import AsyncPortkey +from openai import AsyncOpenAI from pydantic_ai import Agent, ImageUrl from pydantic_ai.models.openai import OpenAIModel from pydantic_ai.providers.openai import OpenAIProvider # Set up Portkey client -portkey_client = AsyncPortkey( +portkey_client = AsyncOpenAI( api_key="YOUR_PORTKEY_API_KEY", - provider="@YOUR_OPENAI_PROVIDER", - trace_id="vision-request", - metadata={"request_type": "image_analysis"} + base_url="https://api.portkey.ai/v1", + default_headers={"x-portkey-trace-id": "vision-request"} ) # Create a vision-capable agent vision_agent = Agent( model=OpenAIModel( - model_name="gpt-4o", # Vision-capable model + model_name="@openai-team-1/gpt-4o", # Vision-capable model provider=OpenAIProvider(openai_client=portkey_client), ), system_prompt="Analyze images and provide detailed descriptions." @@ -179,23 +197,22 @@ PydanticAI provides a powerful tools system that integrates seamlessly with Port ```python import random -from portkey_ai import AsyncPortkey +from openai import AsyncOpenAI from pydantic_ai import Agent, RunContext from pydantic_ai.models.openai import OpenAIModel from pydantic_ai.providers.openai import OpenAIProvider # Set up Portkey client -portkey_client = AsyncPortkey( +portkey_client = AsyncOpenAI( api_key="YOUR_PORTKEY_API_KEY", - provider="@YOUR_OPENAI_PROVIDER", - trace_id="dice-game-session", - metadata={"game_type": "dice"} + base_url="https://api.portkey.ai/v1", + default_headers={"x-portkey-trace-id": "dice-game-session"} ) # Create an agent with dependency injection (player name) dice_agent = Agent( model=OpenAIModel( - model_name="gpt-4o", + model_name="@openai-team-1/gpt-4o", provider=OpenAIProvider(openai_client=portkey_client), ), deps_type=str, # Dependency type (player name as string) @@ -272,14 +289,13 @@ from rich.prompt import Prompt from pydantic_ai import Agent, ModelRetry, RunContext from pydantic_ai.messages import ModelMessage from pydantic_ai.usage import Usage, UsageLimits -from portkey_ai import AsyncPortkey +from openai import AsyncOpenAI # Set up Portkey clients with shared trace ID for connected tracing -portkey_client = AsyncPortkey( +portkey_client = AsyncOpenAI( api_key="YOUR_PORTKEY_API_KEY", - provider="@YOUR_OPENAI_PROVIDER", - trace_id="flight-booking-session", - metadata={"app_type": "flight_booking"} + base_url="https://api.portkey.ai/v1", + default_headers={"x-portkey-trace-id": "flight-booking-session"} ) # Define structured output types @@ -315,7 +331,7 @@ from pydantic_ai.providers.openai import OpenAIProvider search_agent = Agent[Deps, FlightDetails | NoFlightFound]( model=OpenAIModel( - model_name="gpt-4o", + model_name="@openai-team-1/gpt-4o", provider=OpenAIProvider(openai_client=portkey_client), ), output_type=FlightDetails | NoFlightFound, # type: ignore @@ -329,7 +345,7 @@ search_agent = Agent[Deps, FlightDetails | NoFlightFound]( # This agent is responsible for extracting flight details from web page text extraction_agent = Agent( model=OpenAIModel( - model_name="gpt-4o", + model_name="@openai-team-1/gpt-4o", provider=OpenAIProvider(openai_client=portkey_client), ), output_type=list[FlightDetails], @@ -339,7 +355,7 @@ extraction_agent = Agent( # This agent is responsible for extracting the user's seat selection seat_preference_agent = Agent[None, SeatPreference | Failed]( model=OpenAIModel( - model_name="gpt-4o", + model_name="@openai-team-1/gpt-4o", provider=OpenAIProvider(openai_client=portkey_client), ), output_type=SeatPreference | Failed, # type: ignore @@ -481,11 +497,10 @@ Traces provide a hierarchical view of your agent's execution, showing the sequen ```python # Add trace_id to enable hierarchical tracing in Portkey -portkey_client = AsyncPortkey( +portkey_client = AsyncOpenAI( api_key="YOUR_PORTKEY_API_KEY", - provider="@YOUR_LLM_PROVIDER", - trace_id="unique-session-id", # Add unique trace ID - metadata={"request_type": "user_query"} + base_url="https://api.portkey.ai/v1", + default_headers={"x-portkey-trace-id": "unique-session-id"} ) ``` @@ -528,14 +543,11 @@ You can filter and segment all metrics by custom metadata to analyze specific ag Add custom metadata to your PydanticAI agent calls to enable powerful filtering and segmentation: ```python -portkey_client = AsyncPortkey( +portkey_client = AsyncOpenAI( api_key="YOUR_PORTKEY_API_KEY", - provider="@YOUR_LLM_PROVIDER", - metadata={ - "agent_type": "weather_agent", - "environment": "production", - "_user": "user_123", # Special _user field for user analytics - "request_source": "mobile_app" + base_url="https://api.portkey.ai/v1", + default_headers={ + "x-portkey-metadata": '{"agent_type": "weather_agent", "environment": "production", "_user": "user_123", "request_source": "mobile_app"}' } ) ``` @@ -544,34 +556,60 @@ This metadata can be used to filter logs, traces, and metrics on the Portkey das -### 2. Reliability - Keep Your Agents Running Smoothly +### 2. OpenTelemetry Integration + +For comprehensive monitoring and observability, Portkey supports OpenTelemetry integration through various libraries: + +```python +import openlit + +# Initialize OpenLit with Portkey's OTEL endpoint +openlit.init( + otlp_endpoint="https://api.portkey.ai/v1/otel", + otlp_headers={ + "x-portkey-api-key": "YOUR_PORTKEY_API_KEY" + } +) + +# Your PydanticAI agents will now send telemetry data to Portkey +from openai import AsyncOpenAI +from pydantic_ai import Agent +from pydantic_ai.models.openai import OpenAIModel +from pydantic_ai.providers.openai import OpenAIProvider + +portkey_client = AsyncOpenAI( + api_key="YOUR_PORTKEY_API_KEY", + base_url="https://api.portkey.ai/v1" +) + +agent = Agent( + model=OpenAIModel( + model_name="@openai-team-1/gpt-4o", + provider=OpenAIProvider(openai_client=portkey_client), + ), + system_prompt="You are a helpful assistant." +) +``` + + + Learn more about Portkey's OpenTelemetry integration and supported libraries + + +### 3. Reliability - Keep Your Agents Running Smoothly When running agents in production, things can go wrong - API rate limits, network issues, or provider outages. Portkey's reliability features ensure your agents keep running smoothly even when problems occur. It's simple to enable fallback in your PydanticAI agents by using a Portkey Config: ```python -from portkey_ai import AsyncPortkey +from openai import AsyncOpenAI # Create Portkey client with fallback config -portkey_client = AsyncPortkey( +portkey_client = AsyncOpenAI( api_key="YOUR_PORTKEY_API_KEY", - config={ - "strategy": { - "mode": "fallback" - }, - "targets": [ - { - "provider": "openai", - "api_key": "YOUR_OPENAI_API_KEY", - "override_params": {"model": "gpt-4o"} - }, - { - "provider": "anthropic", - "api_key": "YOUR_ANTHROPIC_API_KEY", - "override_params": {"model": "claude-3-opus-20240229"} - } - ] + base_url="https://api.portkey.ai/v1", + default_headers={ + "x-portkey-config": "your-fallback-config-id" } ) ``` @@ -596,110 +634,6 @@ This configuration will automatically try Claude if the GPT-4o request fails, en -### 3. Prompting in PydanticAI - -Portkey's Prompt Engineering Studio helps you create, manage, and optimize the prompts used in your PydanticAI agents. Instead of hardcoding prompts or instructions, use Portkey's prompt rendering API to dynamically fetch and apply your versioned prompts. - - -![Prompt Playground Interface](/images/product/ai-gateway/ai-20.webp) - - - - -Prompt Playground is a place to compare, test and deploy perfect prompts for your AI application. It's where you experiment with different models, test variables, compare outputs, and refine your prompt engineering strategy before deploying to production. It allows you to: - -1. Iteratively develop prompts before using them in your agents -2. Test prompts with different variables and models -3. Compare outputs between different prompt versions -4. Collaborate with team members on prompt development - -This visual environment makes it easier to craft effective prompts for each step in your PydanticAI agent's workflow. - - - -The Prompt Render API retrieves your prompt templates with all parameters configured: - -```python -from portkey_ai import Portkey, AsyncPortkey -from pydantic_ai import Agent -from pydantic_ai.models.openai import OpenAIModel -from pydantic_ai.providers.openai import OpenAIProvider - -# Initialize Portkey clients -portkey_admin = Portkey(api_key="YOUR_PORTKEY_API_KEY") -portkey_client = AsyncPortkey(api_key="YOUR_PORTKEY_API_KEY", provider="@YOUR_OPENAI_PROVIDER") - -# Retrieve prompt using the render API -prompt_data = portkey_admin.prompts.render( - prompt_id="YOUR_PROMPT_ID", - variables={ - "user_input": "Tell me about artificial intelligence" - } -) - -# Use the rendered prompt in your PydanticAI agent -agent = Agent( - model=OpenAIModel( - model_name="gpt-4o", - provider=OpenAIProvider(openai_client=portkey_client), - ), - system_prompt=prompt_data.data.messages[0]["content"] # Use the rendered prompt -) - -result = agent.run_sync("Tell me about artificial intelligence") -print(result.output) -``` - - - -You can: -- Create multiple versions of the same prompt -- Compare performance between versions -- Roll back to previous versions if needed -- Specify which version to use in your code: - -```python -# Use a specific prompt version -prompt_data = portkey_admin.prompts.render( - prompt_id="YOUR_PROMPT_ID@version_number", - variables={ - "user_input": "Tell me about quantum computing" - } -) -``` - - - -Portkey prompts use Mustache-style templating for easy variable substitution: - -``` -You are an AI assistant helping with {{task_type}}. - -User question: {{user_input}} - -Please respond in a {{tone}} tone and include {{required_elements}}. -``` - -When rendering, simply pass the variables: - -```python -prompt_data = portkey_admin.prompts.render( - prompt_id="YOUR_PROMPT_ID", - variables={ - "task_type": "research", - "user_input": "Tell me about quantum computing", - "tone": "professional", - "required_elements": "recent academic references" - } -) -``` - - - - - Learn more about Portkey's prompt management features - - ### 4. Guardrails for Safe Agents Guardrails ensure your PydanticAI agents operate safely and respond appropriately in all situations. @@ -717,25 +651,24 @@ While PydanticAI provides type safety for outputs, Portkey's guardrails add addi **Implementing Guardrails** ```python -from portkey_ai import AsyncPortkey +from openai import AsyncOpenAI from pydantic_ai import Agent from pydantic_ai.models.openai import OpenAIModel from pydantic_ai.providers.openai import OpenAIProvider # Create Portkey client with guardrails -portkey_client = AsyncPortkey( +portkey_client = AsyncOpenAI( api_key="YOUR_PORTKEY_API_KEY", - provider="@YOUR_OPENAI_PROVIDER", - config={ - "input_guardrails": ["guardrails-id-xxx", "guardrails-id-yyy"], - "output_guardrails": ["guardrails-id-zzz"] + base_url="https://api.portkey.ai/v1", + default_headers={ + "x-portkey-config": "your-guardrails-config-id" } ) # Create agent with Portkey-enabled client agent = Agent( model=OpenAIModel( - model_name="gpt-4o", + model_name="@openai-team-1/gpt-4o", provider=OpenAIProvider(openai_client=portkey_client), ), system_prompt="You are a helpful assistant." @@ -762,27 +695,24 @@ Track individual users through your PydanticAI agents using Portkey's metadata s Metadata allows you to associate custom data with each request, enabling filtering, segmentation, and analytics. The special `_user` field is specifically designed for user tracking. ```python -from portkey_ai import AsyncPortkey +from openai import AsyncOpenAI from pydantic_ai import Agent from pydantic_ai.models.openai import OpenAIModel from pydantic_ai.providers.openai import OpenAIProvider # Configure client with user tracking -portkey_client = AsyncPortkey( +portkey_client = AsyncOpenAI( api_key="YOUR_PORTKEY_API_KEY", - provider="@YOUR_OPENAI_PROVIDER", - metadata={ - "_user": "user_123", # Special _user field for user analytics - "user_tier": "premium", - "user_company": "Acme Corp", - "session_id": "abc-123" + base_url="https://api.portkey.ai/v1", + default_headers={ + "x-portkey-metadata": '{"_user": "user_123", "user_tier": "premium", "user_company": "Acme Corp", "session_id": "abc-123"}' } ) # Create agent with Portkey client agent = Agent( model=OpenAIModel( - model_name="gpt-4o", + model_name="@openai-team-1/gpt-4o", provider=OpenAIProvider(openai_client=portkey_client), ), system_prompt="You are a helpful assistant." @@ -814,26 +744,24 @@ Implement caching to make your PydanticAI agents more efficient and cost-effecti ```python -from portkey_ai import AsyncPortkey +from openai import AsyncOpenAI from pydantic_ai import Agent from pydantic_ai.models.openai import OpenAIModel from pydantic_ai.providers.openai import OpenAIProvider # Configure Portkey client with simple caching -portkey_client = AsyncPortkey( +portkey_client = AsyncOpenAI( api_key="YOUR_PORTKEY_API_KEY", - provider="@YOUR_OPENAI_PROVIDER", - config={ - "cache": { - "mode": "simple" - } + base_url="https://api.portkey.ai/v1", + default_headers={ + "x-portkey-config": "your-simple-cache-config-id" } ) # Create agent with cached LLM calls agent = Agent( model=OpenAIModel( - model_name="gpt-4o", + model_name="@openai-team-1/gpt-4o", provider=OpenAIProvider(openai_client=portkey_client), ), system_prompt="You are a helpful assistant." @@ -845,26 +773,24 @@ Simple caching performs exact matches on input prompts, caching identical reques ```python -from portkey_ai import AsyncPortkey +from openai import AsyncOpenAI from pydantic_ai import Agent from pydantic_ai.models.openai import OpenAIModel from pydantic_ai.providers.openai import OpenAIProvider # Configure Portkey client with semantic caching -portkey_client = AsyncPortkey( +portkey_client = AsyncOpenAI( api_key="YOUR_PORTKEY_API_KEY", - provider="@YOUR_OPENAI_PROVIDER", - config={ - "cache": { - "mode": "semantic" - } + base_url="https://api.portkey.ai/v1", + default_headers={ + "x-portkey-config": "your-semantic-cache-config-id" } ) # Create agent with semantically cached LLM calls agent = Agent( model=OpenAIModel( - model_name="gpt-4o", + model_name="@openai-team-1/gpt-4o", provider=OpenAIProvider(openai_client=portkey_client), ), system_prompt="You are a helpful assistant." @@ -880,27 +806,27 @@ Semantic caching considers the contextual similarity between input requests, cac PydanticAI supports multiple LLM providers, and Portkey extends this capability by providing access to over 200 LLMs through a unified interface. You can easily switch between different models without changing your core agent logic: ```python -from portkey_ai import AsyncPortkey +from openai import AsyncOpenAI from pydantic_ai import Agent from pydantic_ai.models.openai import OpenAIModel from pydantic_ai.providers.openai import OpenAIProvider # OpenAI with Portkey -portkey_openai = AsyncPortkey( +portkey_openai = AsyncOpenAI( api_key="YOUR_PORTKEY_API_KEY", - provider="@YOUR_OPENAI_PROVIDER" + base_url="https://api.portkey.ai/v1" ) # Anthropic with Portkey -portkey_anthropic = AsyncPortkey( +portkey_anthropic = AsyncOpenAI( api_key="YOUR_PORTKEY_API_KEY", - provider="@YOUR_ANTHROPIC_PROVIDER" + base_url="https://api.portkey.ai/v1" ) # Create agents with different models openai_agent = Agent( model=OpenAIModel( - model_name="gpt-4o", + model_name="@openai-team-1/gpt-4o", provider=OpenAIProvider(openai_client=portkey_openai), ), system_prompt="You are a helpful assistant." @@ -908,8 +834,8 @@ openai_agent = Agent( anthropic_agent = Agent( model=OpenAIModel( - model_name="claude-3-opus-20240229", - provider=OpenAIProvider(anthropic_client=portkey_anthropic), + model_name="@anthropic-team-1/claude-3-5-sonnet-20241022", + provider=OpenAIProvider(openai_client=portkey_anthropic), ), system_prompt="You are a helpful assistant." ) @@ -948,75 +874,68 @@ If you are using PydanticAI inside your organization, you need to consider sever Portkey adds a comprehensive governance layer to address these enterprise needs. Let's implement these controls step by step. - -Virtual Keys are Portkey's secure way to manage your LLM provider API keys. They provide essential controls like: -- Budget limits for API usage -- Rate limiting capabilities -- Secure API key storage + +Since Portkey now uses the model format like `@team-name/model-name`, you can specify your team and model directly without needing virtual keys. Create a Portkey API key with an attached config: -To create a virtual key: -Go to [Virtual Keys](https://app.portkey.ai/virtual-keys) in the Portkey App. Save and copy the virtual key ID +1. Go to [API Keys](https://app.portkey.ai/api-keys) in Portkey and Create new API key +2. Optionally attach a config for advanced routing, fallbacks, and reliability features +3. Generate and save your API key - + - - -Save your virtual key ID - you'll need it for the next step. - - -Configs in Portkey define how your requests are routed, with features like advanced routing, fallbacks, and retries. - -To create your config: -1. Go to [Configs](https://app.portkey.ai/configs) in Portkey dashboard -2. Create new config with: - ```json - { - "provider":"@YOUR_PROVIDER_FROM_STEP1", - "override_params": { - "model": "gpt-4o" // Your preferred model name - } - } - ``` -3. Save and note the Config name for the next step - - - - - + +Use Portkey's model naming format to specify which team/provider can access which models: - -Now create a Portkey API key and attach the config you created in Step 2: +```python +from openai import AsyncOpenAI +from pydantic_ai import Agent +from pydantic_ai.models.openai import OpenAIModel +from pydantic_ai.providers.openai import OpenAIProvider -1. Go to [API Keys](https://app.portkey.ai/api-keys) in Portkey and Create new API key -2. Select your config from `Step 2` -3. Generate and save your API key +# Configure Portkey client with team-specific model access +portkey_client = AsyncOpenAI( + api_key="YOUR_PORTKEY_API_KEY", + base_url="https://api.portkey.ai/v1" +) - - - +# Create agent with team-specific model +agent = Agent( + model=OpenAIModel( + model_name="@engineering-team/gpt-4o", # Team-specific model access + provider=OpenAIProvider(openai_client=portkey_client), + ), + system_prompt="You are a helpful assistant." +) +``` - -After setting up your Portkey API key with the attached config, connect it to your PydanticAI agents: + +For additional governance features like tracing, metadata, and configs, add headers as needed: ```python -from portkey_ai import AsyncPortkey +from openai import AsyncOpenAI from pydantic_ai import Agent from pydantic_ai.models.openai import OpenAIModel from pydantic_ai.providers.openai import OpenAIProvider -# Configure Portkey client with your API key -portkey_client = AsyncPortkey( - api_key="YOUR_PORTKEY_API_KEY" # The API key with attached config from step 3 +# Configure Portkey client with governance features +portkey_client = AsyncOpenAI( + api_key="YOUR_PORTKEY_API_KEY", + base_url="https://api.portkey.ai/v1", + default_headers={ + "x-portkey-trace-id": "engineering-session", + "x-portkey-metadata": '{"department": "engineering", "environment": "production"}', + "x-portkey-config": "your-governance-config-id" + } ) -# Create agent with Portkey client +# Create agent with governance controls agent = Agent( model=OpenAIModel( - model_name="gpt-4o", + model_name="@engineering-team/gpt-4o", provider=OpenAIProvider(openai_client=portkey_client), ), system_prompt="You are a helpful assistant." @@ -1029,33 +948,33 @@ agent = Agent( ### Step 1: Implement Budget Controls & Rate Limits -Virtual Keys enable granular control over LLM access at the team/department level. This helps you: -- Set up [budget limits](/product/ai-gateway/virtual-keys/budget-limits) -- Prevent unexpected usage spikes using Rate limits +Create configs that enable granular control over LLM access at the team/department level. This helps you: +- Set up budget limits through usage tracking +- Prevent unexpected usage spikes using rate limits - Track departmental spending #### Setting Up Department-Specific Controls: -1. Navigate to [Virtual Keys](https://app.portkey.ai/virtual-keys) in Portkey dashboard -2. Create new Virtual Key for each department with budget limits and rate limits -3. Configure department-specific limits +1. Navigate to [Configs](https://app.portkey.ai/configs) in Portkey dashboard +2. Create new config for each department with appropriate controls +3. Configure department-specific limits and routing - + ### Step 2: Define Model Access Rules -As your AI usage scales, controlling which teams can access specific models becomes crucial. Portkey Configs provide this control layer with features like: +As your AI usage scales, controlling which teams can access specific models becomes crucial. Portkey's model naming format and configs provide this control layer with features like: #### Access Control Features: -- **Model Restrictions**: Limit access to specific models +- **Model Restrictions**: Limit access to specific models using team prefixes - **Data Protection**: Implement guardrails for sensitive data - **Reliability Controls**: Add fallbacks and retry logic #### Example Configuration: -Here's a basic configuration to route requests to OpenAI, specifically using GPT-4o: +Here's a basic configuration to route requests to OpenAI, specifically using GPT-4o for the engineering team: ```json { @@ -1064,7 +983,8 @@ Here's a basic configuration to route requests to OpenAI, specifically using GPT }, "targets": [ { - "provider":"@YOUR_OPENAI_PROVIDER", + "provider": "openai", + "api_key": "YOUR_OPENAI_API_KEY", "override_params": { "model": "gpt-4o" } @@ -1083,8 +1003,8 @@ Here's a basic configuration to route requests to OpenAI, specifically using GPT ### Step 3: Implement Access Controls - Create User-specific API keys that automatically: - - Track usage per user/team with the help of metadata + Create team-specific API keys that automatically: + - Track usage per user/team with metadata - Apply appropriate configs to route requests - Collect relevant metadata to filter logs - Enforce access permissions @@ -1119,7 +1039,7 @@ Here's a basic configuration to route requests to OpenAI, specifically using GPT ### Step 4: Deploy & Monitor - After distributing API keys to your team members, your enterprise-ready PydanticAI setup is ready to go. Each team member can now use their designated API keys with appropriate access levels and budget controls. + After distributing API keys to your team members, your enterprise-ready PydanticAI setup is ready to go. Each team member can now use their designated API keys with appropriate access levels and governance controls. Monitor usage in Portkey dashboard: - Cost tracking by department @@ -1133,9 +1053,9 @@ Here's a basic configuration to route requests to OpenAI, specifically using GPT ### Enterprise Features Now Available **Your PydanticAI integration now has:** -- Departmental budget controls -- Model access governance +- Team-based model access controls - Usage tracking & attribution +- Governance through configs - Security guardrails - Reliability features @@ -1148,7 +1068,7 @@ Here's a basic configuration to route requests to OpenAI, specifically using GPT - Yes! Portkey integrates seamlessly with existing PydanticAI applications. You just need to replace your client initialization code with the Portkey-enabled version. The rest of your agent code remains unchanged and continues to benefit from PydanticAI's strong typing. + Yes! Portkey integrates seamlessly with existing PydanticAI applications. You just need to replace your OpenAI client initialization with the Portkey-enabled version using our gateway URL. The rest of your agent code remains unchanged and continues to benefit from PydanticAI's strong typing. @@ -1156,15 +1076,15 @@ Here's a basic configuration to route requests to OpenAI, specifically using GPT - Yes, Portkey allows you to use a consistent `trace_id` across multiple agents and requests to track the entire workflow. This is especially useful for multi-agent systems where you want to understand the full execution path. + Yes, Portkey allows you to use a consistent `x-portkey-trace-id` header across multiple agents and requests to track the entire workflow. This is especially useful for multi-agent systems where you want to understand the full execution path. - Portkey allows you to add custom metadata to your agent runs, which you can then use for filtering. Add fields like `agent_name`, `agent_type`, or `session_id` to easily find and analyze specific agent executions. + Portkey allows you to add custom metadata through the `x-portkey-metadata` header to your agent runs, which you can then use for filtering. Add fields like `agent_name`, `agent_type`, or `session_id` to easily find and analyze specific agent executions. - Yes! Portkey uses your own API keys for the various LLM providers. It securely stores them, allowing you to easily manage and rotate keys without changing your code. + Yes! Portkey uses your own API keys for the various LLM providers. You can configure them through configs and virtual keys, allowing you to easily manage and rotate keys without changing your code. diff --git a/product/administration/llm-access-api-guide.mdx b/product/administration/llm-access-api-guide.mdx new file mode 100644 index 00000000..e6e26bfa --- /dev/null +++ b/product/administration/llm-access-api-guide.mdx @@ -0,0 +1,583 @@ +--- +title: "Enterprise API Guide: Model Catalog Management" +description: "Complete guide for enterprises to programmatically manage AI integrations, workspace provisioning, and model access using Portkey's Admin APIs" +--- + + +This guide is designed for **enterprise administrators and DevOps teams** who need to programmatically manage AI provider integrations across their organization. For UI-based management, see the [Model Catalog](/product/model-catalog) documentation. + + +Enterprise teams often need to programmatically manage their AI infrastructure at scale. This guide walks you through using Portkey's Admin APIs to automate the complete setup process - from creating integrations to provisioning workspace access and managing model availability. + +## Why Use APIs Instead of UI? + +**Automation & Scale**: Set up hundreds of integrations and workspace configurations instantly +**Infrastructure as Code**: Version control your AI infrastructure configurations +**CI/CD Integration**: Automate integration setup as part of your deployment pipeline +**Governance at Scale**: Apply consistent policies across multiple environments +**Audit & Compliance**: Track all configuration changes through your existing logging systems + +--- + +## Prerequisites + +Before starting, ensure you have: + +1. **Admin API Access**: Your Portkey organization admin API key +2. **Organization Structure**: List of workspaces that need AI access +3. **Provider Credentials**: API keys for your AI providers (OpenAI, Anthropic, etc.) +4. **Governance Policies**: Budget limits, rate limits, and model access policies defined + + + Contact your Portkey admin or visit the Portkey dashboard to generate an admin API key with the necessary permissions. + + +--- + +## Step 1: Create Integration + +An Integration securely stores your AI provider credentials and serves as the foundation for all AI access in your organization. + + +```python Python SDK +from portkey_ai import Portkey + +# Initialize Portkey client with admin API key +portkey = Portkey( + api_key="YOUR_ADMIN_API_KEY", + base_url="https://albus.portkey.ai/v2" # Admin API base URL +) + +# Create an OpenAI integration +openai_integration = portkey.integrations.create( + name="OpenAI Production", + description="Production OpenAI integration for all teams", + key="your-openai-api-key-here", + ai_provider_id="openai", + slug="openai-prod", + organisation_id="your-org-id", + note="Created via API for production environment", + configuration={ + "base_url": "https://api.openai.com/v1", + "api_version": "2024-01-01" + } +) + +print(f"Created integration: {openai_integration.slug}") +``` + +```python AWS Bedrock Example +# Create an AWS Bedrock integration +bedrock_integration = portkey.integrations.create( + name="AWS Bedrock Production", + description="Production Bedrock integration with enterprise AWS account", + key="your-aws-access-key", + ai_provider_id="bedrock", + slug="bedrock-prod", + configuration={ + "aws_secret_access_key": "your-secret-key", + "aws_region": "us-east-1", + "aws_access_key_id": "your-access-key-id" + } +) +``` + + + + View complete integration management API documentation + + +### Common AI Providers + +| Provider | AI Provider ID | Required Configuration | +|----------|----------------|------------------------| +| OpenAI | `openai` | `api_key` | +| Anthropic | `anthropic` | `api_key` | +| AWS Bedrock | `bedrock` | `aws_access_key`, `aws_secret_access_key`, `aws_region` | +| Azure OpenAI | `azure-openai` | `api_key`, `api_base`, `api_version` | +| Google Vertex AI | `vertex-ai` | Service account credentials | + +--- + +## Step 2: Configure Workspace Provisioning + +Workspace provisioning determines which teams can access your AI integrations. This step controls the security boundary of your AI infrastructure. + +```python +# List available workspaces first +workspaces = portkey.integrations.workspaces.list( + slug="openai-prod" +) + +print("Available workspaces:", workspaces) + +# Provision integration to specific workspaces +provisioning_result = portkey.integrations.workspaces.update( + slug="openai-prod", + workspaces=[ + { + "id": "ws-engineering-team", + "enabled": True + }, + { + "id": "ws-data-science-team", + "enabled": True + }, + { + "id": "ws-qa-testing", + "enabled": True + } + ] +) + +print("Workspace provisioning updated:", provisioning_result) +``` + + + View workspace provisioning API documentation + + +### Provisioning Strategies + +**Selective Access**: Provision only to workspaces that need specific AI capabilities +**Environment-Based**: Create separate integrations for dev/staging/production environments +**Team-Based**: Provision based on team responsibilities and access requirements + +--- + +## Step 3: Set Budget & Rate Limits + +Configure financial and usage guardrails to prevent runaway costs and ensure fair resource distribution. + + + Budget and Rate Limit Configuration + + +```python +# Update workspace with budget and rate limits +workspace_limits = portkey.integrations.workspaces.update( + slug="openai-prod", + workspaces=[ + { + "id": "ws-engineering-team", + "enabled": True, + "budget_limit": { + "type": "cost", # or "token" + "value": 1000, # $1000 USD + "period": "monthly", # "weekly", "monthly", or "none" + "alert_threshold": 800 # Alert at $800 + }, + "rate_limit": { + "type": "request", # or "token" + "value": 10000, # 10k requests + "period": "hour" # "minute", "hour", or "day" + } + }, + { + "id": "ws-data-science-team", + "enabled": True, + "budget_limit": { + "type": "cost", + "value": 5000, # Higher budget for data science + "period": "monthly" + }, + "rate_limit": { + "type": "token", + "value": 1000000, # 1M tokens per hour + "period": "hour" + } + } + ] +) +``` + +### Budget Limit Options + +**Cost-Based Limits**: Set maximum spending in USD (minimum $1) +**Token-Based Limits**: Set maximum token consumption (minimum 100 tokens) +**Periodic Reset**: Automatically reset limits weekly or monthly +**Alert Thresholds**: Get notified before limits are reached + +### Rate Limit Options + +**Request-Based**: Limit API calls per time window +**Token-Based**: Limit token consumption rate +**Time Windows**: Per minute, hour, or day intervals + +--- + +## Step 4: Configure Model Provisioning + +Control which AI models are available through your integration. This ensures teams only access approved, cost-effective models. + +```python +# List all available models for the integration +available_models = portkey.integrations.models.list( + slug="openai-prod" +) + +print("Available models:", available_models) + +# Enable specific models (allowlist approach) +model_provisioning = portkey.integrations.models.update( + slug="openai-prod", + models=[ + { + "slug": "gpt-4o-mini", + "enabled": True + }, + { + "slug": "gpt-4o", + "enabled": True + }, + { + "slug": "gpt-3.5-turbo", + "enabled": True + }, + { + "slug": "text-embedding-3-small", + "enabled": True + } + ] +) + +print("Model provisioning updated:", model_provisioning) +``` + + + View model provisioning API documentation + + +### Model Selection Strategies + +**Cost-Optimized**: Enable only the most cost-effective models for each use case +**Performance-Tiered**: Provide different model tiers for different teams +**Compliance-First**: Only enable models that meet your governance requirements + +--- + +## Step 5: Create Workspace API Keys + +Generate API keys for your teams to access the provisioned AI resources. These keys inherit all the limits and model access you've configured. + +```python +# Create API key for engineering team +engineering_api_key = portkey.api_keys.create( + name="Engineering Team Production Key", + type="organisation", + sub_type="service", + workspace_id="ws-engineering-team", + scopes=[ + "logs.list", + "logs.view", + "configs.create", + "configs.update", + "configs.read", + "configs.list", + "virtual_keys.create", + "virtual_keys.update", + "virtual_keys.read", + "virtual_keys.list" + ] +) + +# Create API key for data science team with broader permissions +data_science_api_key = portkey.api_keys.create( + name="Data Science Team API Key", + type="organisation", + sub_type="service", + workspace_id="ws-data-science-team", + scopes=[ + "logs.export", + "logs.list", + "logs.view", + "configs.create", + "configs.update", + "configs.delete", + "configs.read", + "configs.list", + "virtual_keys.create", + "virtual_keys.update", + "virtual_keys.delete", + "virtual_keys.read", + "virtual_keys.list" + ] +) + +print(f"Engineering API Key: {engineering_api_key.key}") +print(f"Data Science API Key: {data_science_api_key.key}") +``` + +### API Key Scopes Reference + +| Scope | Description | Recommended For | +|-------|-------------|-----------------| +| `logs.*` | Access to request logs and analytics | All teams | +| `configs.*` | Manage AI configurations | Development teams | +| `virtual_keys.*` | Manage virtual keys for applications | Production teams | +| `*.export` | Export data capabilities | Data teams | +| `*.delete` | Deletion permissions | Admin teams only | + +--- + +## Step 6: List Available Models + +Your teams can now discover which models are available through their workspace API keys. + +```python +# Your teams can use their workspace API keys to list available models +from portkey_ai import Portkey + +# Initialize with workspace API key (not admin key) +user_client = Portkey( + api_key="WORKSPACE_API_KEY_FROM_STEP_5" +) + +# List available models (inherits integration's model provisioning) +available_models = user_client.models.list() + +print("Models available to this workspace:") +for model in available_models: + print(f"- {model.id} ({model.provider})") +``` + +Your teams can now make AI requests using these provisioned models: + +```python +# Make a request using a provisioned model +response = user_client.chat.completions.create( + model="gpt-4o-mini", + messages=[ + {"role": "user", "content": "Hello, world!"} + ] +) + +print(response.choices[0].message.content) +``` + +--- + +## Complete Example Workflow + +Here's a complete script that sets up an enterprise AI infrastructure: + + +```python Complete Setup Script +from portkey_ai import Portkey +import json + +class PortkeyEnterpriseSetup: + def __init__(self, admin_api_key, org_id): + self.portkey = Portkey( + api_key=admin_api_key, + base_url="https://albus.portkey.ai/v2" + ) + self.org_id = org_id + + def create_integration(self, name, provider, credentials, slug): + """Create a new AI provider integration""" + integration = self.portkey.integrations.create( + name=name, + ai_provider_id=provider, + slug=slug, + organisation_id=self.org_id, + **credentials + ) + print(f"โœ… Created integration: {integration.slug}") + return integration + + def setup_workspace_provisioning(self, integration_slug, workspace_configs): + """Configure workspace access with limits""" + workspaces = [] + for config in workspace_configs: + workspace = { + "id": config["workspace_id"], + "enabled": True + } + + # Add budget limits if specified + if "budget_limit" in config: + workspace["budget_limit"] = config["budget_limit"] + + # Add rate limits if specified + if "rate_limit" in config: + workspace["rate_limit"] = config["rate_limit"] + + workspaces.append(workspace) + + result = self.portkey.integrations.workspaces.update( + slug=integration_slug, + workspaces=workspaces + ) + print(f"โœ… Configured workspace provisioning for {integration_slug}") + return result + + def setup_model_provisioning(self, integration_slug, enabled_models): + """Configure which models are available""" + models = [{"slug": model, "enabled": True} for model in enabled_models] + + result = self.portkey.integrations.models.update( + slug=integration_slug, + models=models + ) + print(f"โœ… Configured model provisioning for {integration_slug}") + return result + + def create_workspace_api_keys(self, workspace_configs): + """Create API keys for each workspace""" + api_keys = {} + + for config in workspace_configs: + api_key = self.portkey.api_keys.create( + name=f"{config['name']} API Key", + type="organisation", + sub_type="service", + workspace_id=config["workspace_id"], + scopes=config.get("scopes", [ + "logs.list", "logs.view", "configs.create", + "configs.read", "virtual_keys.create", "virtual_keys.read" + ]) + ) + api_keys[config["workspace_id"]] = api_key.key + print(f"โœ… Created API key for {config['name']}") + + return api_keys + +# Usage example +setup = PortkeyEnterpriseSetup( + admin_api_key="YOUR_ADMIN_API_KEY", + org_id="YOUR_ORG_ID" +) + +# Step 1: Create integrations +openai_integration = setup.create_integration( + name="OpenAI Production", + provider="openai", + credentials={"key": "your-openai-key"}, + slug="openai-prod" +) + +# Step 2 & 3: Setup workspace provisioning with limits +workspace_configs = [ + { + "workspace_id": "ws-engineering", + "name": "Engineering Team", + "budget_limit": {"type": "cost", "value": 1000, "period": "monthly"}, + "rate_limit": {"type": "request", "value": 10000, "period": "hour"}, + "scopes": ["logs.list", "configs.create", "virtual_keys.create"] + }, + { + "workspace_id": "ws-data-science", + "name": "Data Science Team", + "budget_limit": {"type": "cost", "value": 5000, "period": "monthly"}, + "rate_limit": {"type": "token", "value": 1000000, "period": "hour"}, + "scopes": ["logs.export", "configs.create", "virtual_keys.create"] + } +] + +setup.setup_workspace_provisioning("openai-prod", workspace_configs) + +# Step 4: Configure model access +enabled_models = ["gpt-4o-mini", "gpt-4o", "text-embedding-3-small"] +setup.setup_model_provisioning("openai-prod", enabled_models) + +# Step 5: Create workspace API keys +api_keys = setup.create_workspace_api_keys(workspace_configs) + +print("\n๐ŸŽ‰ Setup complete!") +print("API Keys for your teams:") +for workspace_id, api_key in api_keys.items(): + print(f" {workspace_id}: {api_key}") +``` + + +--- + +## Best Practices + +### Security + +**๐Ÿ”’ API Key Management**: Store admin API keys securely (environment variables, secret managers) +**๐Ÿ‘ฅ Principle of Least Privilege**: Give workspaces only the scopes they need +**๐Ÿ”„ Regular Rotation**: Rotate API keys periodically +**๐Ÿ“ Audit Logging**: Track all API configuration changes + +### Cost Control + +**๐Ÿ’ฐ Start Conservative**: Begin with lower budget limits and increase as needed +**๐Ÿ“Š Monitor Usage**: Set up alerts at 80% of budget limits +**๐ŸŽฏ Model Optimization**: Enable cost-effective models first, add premium models selectively +**๐Ÿ“ˆ Regular Reviews**: Review and adjust limits based on actual usage patterns + +### Operational Excellence + +**๐Ÿ“‹ Infrastructure as Code**: Version control your setup scripts +**๐Ÿงช Test in Staging**: Test integration setup in non-production environments first +**๐Ÿ“š Documentation**: Document your integration patterns and governance policies +**๐Ÿš€ Gradual Rollout**: Start with a few workspaces, then expand + +### Model Management + +**๐ŸŽจ Curated Catalogs**: Create different model sets for different use cases +**โšก Performance Tiers**: Provide fast models for real-time use, powerful models for batch processing +**๐Ÿ” Regular Updates**: Review and update model availability as new models are released +**๐Ÿ“Š Usage Analytics**: Monitor which models are most used to optimize provisioning + +--- + +## Troubleshooting + +### Common Issues + +**Integration Creation Fails** +- Verify your AI provider credentials are correct +- Check that the AI provider ID matches exactly (case-sensitive) +- Ensure your admin API key has sufficient permissions + +**Workspace Provisioning Errors** +- Confirm workspace IDs exist and are accessible +- Verify budget/rate limit values meet minimum requirements +- Check that your organization plan supports the requested features + +**Model Provisioning Issues** +- Ensure model slugs match exactly with provider's model names +- Verify your AI provider account has access to the requested models +- Check that model provisioning is supported for your integration type + +**API Key Creation Fails** +- Confirm the workspace ID exists and is provisioned +- Verify the requested scopes are valid and available +- Check that you haven't exceeded API key limits for the workspace + +### Getting Help + +If you encounter issues: +1. Check the [API Reference documentation](/api-reference/admin-api/control-plane/integrations/list-integrations) +2. Review your API key permissions and scopes +3. Contact Portkey support with specific error messages and request IDs + +--- + +## What's Next? + +After completing this setup: + +1. **Deploy Applications**: Your teams can now build AI applications using their workspace API keys +2. **Monitor Usage**: Track costs and usage through the Portkey dashboard +3. **Scale Up**: Add more integrations, workspaces, and models as needed +4. **Optimize**: Adjust limits and model access based on actual usage patterns + + + + Create application-specific keys with custom configurations + + + Monitor and analyze your AI infrastructure performance + + + Manage fallbacks, retries, and routing configurations + + + Explore advanced enterprise capabilities + + \ No newline at end of file From 7640122de60cea3ecaee2bb2a51618d59b49e852 Mon Sep 17 00:00:00 2001 From: siddharthsambharia-portkey Date: Wed, 3 Sep 2025 17:36:46 +0530 Subject: [PATCH 2/2] remove doc --- .../administration/llm-access-api-guide.mdx | 583 ------------------ 1 file changed, 583 deletions(-) delete mode 100644 product/administration/llm-access-api-guide.mdx diff --git a/product/administration/llm-access-api-guide.mdx b/product/administration/llm-access-api-guide.mdx deleted file mode 100644 index e6e26bfa..00000000 --- a/product/administration/llm-access-api-guide.mdx +++ /dev/null @@ -1,583 +0,0 @@ ---- -title: "Enterprise API Guide: Model Catalog Management" -description: "Complete guide for enterprises to programmatically manage AI integrations, workspace provisioning, and model access using Portkey's Admin APIs" ---- - - -This guide is designed for **enterprise administrators and DevOps teams** who need to programmatically manage AI provider integrations across their organization. For UI-based management, see the [Model Catalog](/product/model-catalog) documentation. - - -Enterprise teams often need to programmatically manage their AI infrastructure at scale. This guide walks you through using Portkey's Admin APIs to automate the complete setup process - from creating integrations to provisioning workspace access and managing model availability. - -## Why Use APIs Instead of UI? - -**Automation & Scale**: Set up hundreds of integrations and workspace configurations instantly -**Infrastructure as Code**: Version control your AI infrastructure configurations -**CI/CD Integration**: Automate integration setup as part of your deployment pipeline -**Governance at Scale**: Apply consistent policies across multiple environments -**Audit & Compliance**: Track all configuration changes through your existing logging systems - ---- - -## Prerequisites - -Before starting, ensure you have: - -1. **Admin API Access**: Your Portkey organization admin API key -2. **Organization Structure**: List of workspaces that need AI access -3. **Provider Credentials**: API keys for your AI providers (OpenAI, Anthropic, etc.) -4. **Governance Policies**: Budget limits, rate limits, and model access policies defined - - - Contact your Portkey admin or visit the Portkey dashboard to generate an admin API key with the necessary permissions. - - ---- - -## Step 1: Create Integration - -An Integration securely stores your AI provider credentials and serves as the foundation for all AI access in your organization. - - -```python Python SDK -from portkey_ai import Portkey - -# Initialize Portkey client with admin API key -portkey = Portkey( - api_key="YOUR_ADMIN_API_KEY", - base_url="https://albus.portkey.ai/v2" # Admin API base URL -) - -# Create an OpenAI integration -openai_integration = portkey.integrations.create( - name="OpenAI Production", - description="Production OpenAI integration for all teams", - key="your-openai-api-key-here", - ai_provider_id="openai", - slug="openai-prod", - organisation_id="your-org-id", - note="Created via API for production environment", - configuration={ - "base_url": "https://api.openai.com/v1", - "api_version": "2024-01-01" - } -) - -print(f"Created integration: {openai_integration.slug}") -``` - -```python AWS Bedrock Example -# Create an AWS Bedrock integration -bedrock_integration = portkey.integrations.create( - name="AWS Bedrock Production", - description="Production Bedrock integration with enterprise AWS account", - key="your-aws-access-key", - ai_provider_id="bedrock", - slug="bedrock-prod", - configuration={ - "aws_secret_access_key": "your-secret-key", - "aws_region": "us-east-1", - "aws_access_key_id": "your-access-key-id" - } -) -``` - - - - View complete integration management API documentation - - -### Common AI Providers - -| Provider | AI Provider ID | Required Configuration | -|----------|----------------|------------------------| -| OpenAI | `openai` | `api_key` | -| Anthropic | `anthropic` | `api_key` | -| AWS Bedrock | `bedrock` | `aws_access_key`, `aws_secret_access_key`, `aws_region` | -| Azure OpenAI | `azure-openai` | `api_key`, `api_base`, `api_version` | -| Google Vertex AI | `vertex-ai` | Service account credentials | - ---- - -## Step 2: Configure Workspace Provisioning - -Workspace provisioning determines which teams can access your AI integrations. This step controls the security boundary of your AI infrastructure. - -```python -# List available workspaces first -workspaces = portkey.integrations.workspaces.list( - slug="openai-prod" -) - -print("Available workspaces:", workspaces) - -# Provision integration to specific workspaces -provisioning_result = portkey.integrations.workspaces.update( - slug="openai-prod", - workspaces=[ - { - "id": "ws-engineering-team", - "enabled": True - }, - { - "id": "ws-data-science-team", - "enabled": True - }, - { - "id": "ws-qa-testing", - "enabled": True - } - ] -) - -print("Workspace provisioning updated:", provisioning_result) -``` - - - View workspace provisioning API documentation - - -### Provisioning Strategies - -**Selective Access**: Provision only to workspaces that need specific AI capabilities -**Environment-Based**: Create separate integrations for dev/staging/production environments -**Team-Based**: Provision based on team responsibilities and access requirements - ---- - -## Step 3: Set Budget & Rate Limits - -Configure financial and usage guardrails to prevent runaway costs and ensure fair resource distribution. - - - Budget and Rate Limit Configuration - - -```python -# Update workspace with budget and rate limits -workspace_limits = portkey.integrations.workspaces.update( - slug="openai-prod", - workspaces=[ - { - "id": "ws-engineering-team", - "enabled": True, - "budget_limit": { - "type": "cost", # or "token" - "value": 1000, # $1000 USD - "period": "monthly", # "weekly", "monthly", or "none" - "alert_threshold": 800 # Alert at $800 - }, - "rate_limit": { - "type": "request", # or "token" - "value": 10000, # 10k requests - "period": "hour" # "minute", "hour", or "day" - } - }, - { - "id": "ws-data-science-team", - "enabled": True, - "budget_limit": { - "type": "cost", - "value": 5000, # Higher budget for data science - "period": "monthly" - }, - "rate_limit": { - "type": "token", - "value": 1000000, # 1M tokens per hour - "period": "hour" - } - } - ] -) -``` - -### Budget Limit Options - -**Cost-Based Limits**: Set maximum spending in USD (minimum $1) -**Token-Based Limits**: Set maximum token consumption (minimum 100 tokens) -**Periodic Reset**: Automatically reset limits weekly or monthly -**Alert Thresholds**: Get notified before limits are reached - -### Rate Limit Options - -**Request-Based**: Limit API calls per time window -**Token-Based**: Limit token consumption rate -**Time Windows**: Per minute, hour, or day intervals - ---- - -## Step 4: Configure Model Provisioning - -Control which AI models are available through your integration. This ensures teams only access approved, cost-effective models. - -```python -# List all available models for the integration -available_models = portkey.integrations.models.list( - slug="openai-prod" -) - -print("Available models:", available_models) - -# Enable specific models (allowlist approach) -model_provisioning = portkey.integrations.models.update( - slug="openai-prod", - models=[ - { - "slug": "gpt-4o-mini", - "enabled": True - }, - { - "slug": "gpt-4o", - "enabled": True - }, - { - "slug": "gpt-3.5-turbo", - "enabled": True - }, - { - "slug": "text-embedding-3-small", - "enabled": True - } - ] -) - -print("Model provisioning updated:", model_provisioning) -``` - - - View model provisioning API documentation - - -### Model Selection Strategies - -**Cost-Optimized**: Enable only the most cost-effective models for each use case -**Performance-Tiered**: Provide different model tiers for different teams -**Compliance-First**: Only enable models that meet your governance requirements - ---- - -## Step 5: Create Workspace API Keys - -Generate API keys for your teams to access the provisioned AI resources. These keys inherit all the limits and model access you've configured. - -```python -# Create API key for engineering team -engineering_api_key = portkey.api_keys.create( - name="Engineering Team Production Key", - type="organisation", - sub_type="service", - workspace_id="ws-engineering-team", - scopes=[ - "logs.list", - "logs.view", - "configs.create", - "configs.update", - "configs.read", - "configs.list", - "virtual_keys.create", - "virtual_keys.update", - "virtual_keys.read", - "virtual_keys.list" - ] -) - -# Create API key for data science team with broader permissions -data_science_api_key = portkey.api_keys.create( - name="Data Science Team API Key", - type="organisation", - sub_type="service", - workspace_id="ws-data-science-team", - scopes=[ - "logs.export", - "logs.list", - "logs.view", - "configs.create", - "configs.update", - "configs.delete", - "configs.read", - "configs.list", - "virtual_keys.create", - "virtual_keys.update", - "virtual_keys.delete", - "virtual_keys.read", - "virtual_keys.list" - ] -) - -print(f"Engineering API Key: {engineering_api_key.key}") -print(f"Data Science API Key: {data_science_api_key.key}") -``` - -### API Key Scopes Reference - -| Scope | Description | Recommended For | -|-------|-------------|-----------------| -| `logs.*` | Access to request logs and analytics | All teams | -| `configs.*` | Manage AI configurations | Development teams | -| `virtual_keys.*` | Manage virtual keys for applications | Production teams | -| `*.export` | Export data capabilities | Data teams | -| `*.delete` | Deletion permissions | Admin teams only | - ---- - -## Step 6: List Available Models - -Your teams can now discover which models are available through their workspace API keys. - -```python -# Your teams can use their workspace API keys to list available models -from portkey_ai import Portkey - -# Initialize with workspace API key (not admin key) -user_client = Portkey( - api_key="WORKSPACE_API_KEY_FROM_STEP_5" -) - -# List available models (inherits integration's model provisioning) -available_models = user_client.models.list() - -print("Models available to this workspace:") -for model in available_models: - print(f"- {model.id} ({model.provider})") -``` - -Your teams can now make AI requests using these provisioned models: - -```python -# Make a request using a provisioned model -response = user_client.chat.completions.create( - model="gpt-4o-mini", - messages=[ - {"role": "user", "content": "Hello, world!"} - ] -) - -print(response.choices[0].message.content) -``` - ---- - -## Complete Example Workflow - -Here's a complete script that sets up an enterprise AI infrastructure: - - -```python Complete Setup Script -from portkey_ai import Portkey -import json - -class PortkeyEnterpriseSetup: - def __init__(self, admin_api_key, org_id): - self.portkey = Portkey( - api_key=admin_api_key, - base_url="https://albus.portkey.ai/v2" - ) - self.org_id = org_id - - def create_integration(self, name, provider, credentials, slug): - """Create a new AI provider integration""" - integration = self.portkey.integrations.create( - name=name, - ai_provider_id=provider, - slug=slug, - organisation_id=self.org_id, - **credentials - ) - print(f"โœ… Created integration: {integration.slug}") - return integration - - def setup_workspace_provisioning(self, integration_slug, workspace_configs): - """Configure workspace access with limits""" - workspaces = [] - for config in workspace_configs: - workspace = { - "id": config["workspace_id"], - "enabled": True - } - - # Add budget limits if specified - if "budget_limit" in config: - workspace["budget_limit"] = config["budget_limit"] - - # Add rate limits if specified - if "rate_limit" in config: - workspace["rate_limit"] = config["rate_limit"] - - workspaces.append(workspace) - - result = self.portkey.integrations.workspaces.update( - slug=integration_slug, - workspaces=workspaces - ) - print(f"โœ… Configured workspace provisioning for {integration_slug}") - return result - - def setup_model_provisioning(self, integration_slug, enabled_models): - """Configure which models are available""" - models = [{"slug": model, "enabled": True} for model in enabled_models] - - result = self.portkey.integrations.models.update( - slug=integration_slug, - models=models - ) - print(f"โœ… Configured model provisioning for {integration_slug}") - return result - - def create_workspace_api_keys(self, workspace_configs): - """Create API keys for each workspace""" - api_keys = {} - - for config in workspace_configs: - api_key = self.portkey.api_keys.create( - name=f"{config['name']} API Key", - type="organisation", - sub_type="service", - workspace_id=config["workspace_id"], - scopes=config.get("scopes", [ - "logs.list", "logs.view", "configs.create", - "configs.read", "virtual_keys.create", "virtual_keys.read" - ]) - ) - api_keys[config["workspace_id"]] = api_key.key - print(f"โœ… Created API key for {config['name']}") - - return api_keys - -# Usage example -setup = PortkeyEnterpriseSetup( - admin_api_key="YOUR_ADMIN_API_KEY", - org_id="YOUR_ORG_ID" -) - -# Step 1: Create integrations -openai_integration = setup.create_integration( - name="OpenAI Production", - provider="openai", - credentials={"key": "your-openai-key"}, - slug="openai-prod" -) - -# Step 2 & 3: Setup workspace provisioning with limits -workspace_configs = [ - { - "workspace_id": "ws-engineering", - "name": "Engineering Team", - "budget_limit": {"type": "cost", "value": 1000, "period": "monthly"}, - "rate_limit": {"type": "request", "value": 10000, "period": "hour"}, - "scopes": ["logs.list", "configs.create", "virtual_keys.create"] - }, - { - "workspace_id": "ws-data-science", - "name": "Data Science Team", - "budget_limit": {"type": "cost", "value": 5000, "period": "monthly"}, - "rate_limit": {"type": "token", "value": 1000000, "period": "hour"}, - "scopes": ["logs.export", "configs.create", "virtual_keys.create"] - } -] - -setup.setup_workspace_provisioning("openai-prod", workspace_configs) - -# Step 4: Configure model access -enabled_models = ["gpt-4o-mini", "gpt-4o", "text-embedding-3-small"] -setup.setup_model_provisioning("openai-prod", enabled_models) - -# Step 5: Create workspace API keys -api_keys = setup.create_workspace_api_keys(workspace_configs) - -print("\n๐ŸŽ‰ Setup complete!") -print("API Keys for your teams:") -for workspace_id, api_key in api_keys.items(): - print(f" {workspace_id}: {api_key}") -``` - - ---- - -## Best Practices - -### Security - -**๐Ÿ”’ API Key Management**: Store admin API keys securely (environment variables, secret managers) -**๐Ÿ‘ฅ Principle of Least Privilege**: Give workspaces only the scopes they need -**๐Ÿ”„ Regular Rotation**: Rotate API keys periodically -**๐Ÿ“ Audit Logging**: Track all API configuration changes - -### Cost Control - -**๐Ÿ’ฐ Start Conservative**: Begin with lower budget limits and increase as needed -**๐Ÿ“Š Monitor Usage**: Set up alerts at 80% of budget limits -**๐ŸŽฏ Model Optimization**: Enable cost-effective models first, add premium models selectively -**๐Ÿ“ˆ Regular Reviews**: Review and adjust limits based on actual usage patterns - -### Operational Excellence - -**๐Ÿ“‹ Infrastructure as Code**: Version control your setup scripts -**๐Ÿงช Test in Staging**: Test integration setup in non-production environments first -**๐Ÿ“š Documentation**: Document your integration patterns and governance policies -**๐Ÿš€ Gradual Rollout**: Start with a few workspaces, then expand - -### Model Management - -**๐ŸŽจ Curated Catalogs**: Create different model sets for different use cases -**โšก Performance Tiers**: Provide fast models for real-time use, powerful models for batch processing -**๐Ÿ” Regular Updates**: Review and update model availability as new models are released -**๐Ÿ“Š Usage Analytics**: Monitor which models are most used to optimize provisioning - ---- - -## Troubleshooting - -### Common Issues - -**Integration Creation Fails** -- Verify your AI provider credentials are correct -- Check that the AI provider ID matches exactly (case-sensitive) -- Ensure your admin API key has sufficient permissions - -**Workspace Provisioning Errors** -- Confirm workspace IDs exist and are accessible -- Verify budget/rate limit values meet minimum requirements -- Check that your organization plan supports the requested features - -**Model Provisioning Issues** -- Ensure model slugs match exactly with provider's model names -- Verify your AI provider account has access to the requested models -- Check that model provisioning is supported for your integration type - -**API Key Creation Fails** -- Confirm the workspace ID exists and is provisioned -- Verify the requested scopes are valid and available -- Check that you haven't exceeded API key limits for the workspace - -### Getting Help - -If you encounter issues: -1. Check the [API Reference documentation](/api-reference/admin-api/control-plane/integrations/list-integrations) -2. Review your API key permissions and scopes -3. Contact Portkey support with specific error messages and request IDs - ---- - -## What's Next? - -After completing this setup: - -1. **Deploy Applications**: Your teams can now build AI applications using their workspace API keys -2. **Monitor Usage**: Track costs and usage through the Portkey dashboard -3. **Scale Up**: Add more integrations, workspaces, and models as needed -4. **Optimize**: Adjust limits and model access based on actual usage patterns - - - - Create application-specific keys with custom configurations - - - Monitor and analyze your AI infrastructure performance - - - Manage fallbacks, retries, and routing configurations - - - Explore advanced enterprise capabilities - - \ No newline at end of file