OpenAI Compatibility
Use your Vizra agents with any OpenAI-compatible tool or library! Drop-in replacement for OpenAI's Chat Completions API that opens up your agents to the entire OpenAI ecosystem.
🚀 Why OpenAI Compatibility?
The OpenAI Chat Completions API has become the de facto standard for AI applications. By implementing this same interface, Vizra ADK instantly becomes compatible with thousands of existing tools, libraries, and workflows without any code changes!
🛠️ Existing Tools
Use with LangChain, LlamaIndex, Vercel AI SDK, and countless other libraries
📱 Client Apps
Works with ChatGPT clients, mobile apps, browser extensions, and desktop tools
🔄 Zero Migration
Just change the base URL - everything else works exactly the same
📍 API Endpoint
Base URL
POST /api/vizra-adk/chat/completions
This endpoint accepts the exact same request format as OpenAI's Chat Completions API.
⚡ Quick Start
Ready to try it? Here are examples in different languages:
🔧 Using with Existing Libraries
Here are examples with popular AI libraries:
🔧 Configuration
Configure model-to-agent mapping to make your agents accessible via familiar OpenAI model names:
return [
// ... other config
/**
* OpenAI API Compatibility Configuration
* Maps OpenAI model names to your agent names
*/
'openai_model_mapping' => [
// Default mappings for OpenAI models
'gpt-4' => env('VIZRA_ADK_OPENAI_GPT4_AGENT', 'chat_agent'),
'gpt-4-turbo' => env('VIZRA_ADK_OPENAI_GPT4_TURBO_AGENT', 'chat_agent'),
'gpt-3.5-turbo' => env('VIZRA_ADK_OPENAI_GPT35_AGENT', 'chat_agent'),
'gpt-4o' => env('VIZRA_ADK_OPENAI_GPT4O_AGENT', 'chat_agent'),
'gpt-4o-mini' => env('VIZRA_ADK_OPENAI_GPT4O_MINI_AGENT', 'chat_agent'),
// Add your own custom mappings here
// 'my-custom-model' => 'my_specialized_agent',
// 'claude-3-opus' => 'advanced_reasoning_agent',
// 'gpt-4-vision' => 'image_analysis_agent',
],
/**
* Default agent when no mapping is found
* Used for unmapped OpenAI models (gpt-*)
*/
'default_chat_agent' => env('VIZRA_ADK_DEFAULT_CHAT_AGENT', 'chat_agent'),
];
💡 How Model Resolution Works:
- First checks for exact match in
openai_model_mapping
- If model starts with
gpt-
, usesdefault_chat_agent
- Otherwise, treats the model name as the agent name directly
This means you can use model: "your_agent_name"
directly without any mapping!
You can customize mappings via environment variables or by publishing the config file with php artisan vendor:publish --tag=vizra-adk-config
.
⚡ Streaming Support
Enable real-time streaming responses by setting "stream": true
in your request:
🎯 Supported Parameters
The OpenAI compatibility layer supports all major ChatGPT parameters:
Request Parameters
model
Agent name or mapped model name
messages
Array of conversation messages
stream
Enable streaming responses
temperature
Creativity level (0.0 - 2.0)
max_tokens
Maximum response length
top_p
Nucleus sampling parameter
user
User identifier for sessions
📊 Response Format
Responses match OpenAI's format exactly, ensuring perfect compatibility:
Standard Response
{
"id": "chatcmpl-AbCdEfGhIjKlMnOpQrStUvWxYz",
"object": "chat.completion",
"created": 1677858242,
"model": "your-agent-name",
"system_fingerprint": null,
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "Hello! I'm your Vizra agent, ready to help!"
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 12,
"completion_tokens": 15,
"total_tokens": 27
}
}
Streaming Response
data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677858242,"model":"your-agent","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}
data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677858242,"model":"your-agent","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}
data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677858242,"model":"your-agent","choices":[{"index":0,"delta":{"content":"!"},"finish_reason":null}]}
data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677858242,"model":"your-agent","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}
data: [DONE]
🛡️ Error Handling
Error responses also match OpenAI's format for seamless compatibility:
{
"error": {
"message": "The model 'unknown-agent' does not exist or you do not have access to it.",
"type": "not_found_error",
"code": "model_not_found"
}
}
400 - Bad Request
Invalid request format or missing required fields
404 - Not Found
Agent/model not found or not registered
500 - Server Error
Internal error during agent execution
💡 Tips & Best Practices
-
🎯
Agent Naming Strategy: Map commonly used OpenAI model names to your best agents to make migration seamless. For example, map
gpt-4
to your most advanced agent. -
⚡
Performance Optimization: Use the
user
parameter to maintain persistent sessions and memory across conversations for more personalized responses. -
🔧
Development Workflow: Test your OpenAI compatibility with existing tools during development. Most AI applications allow changing the base URL for easy integration testing.
-
📦
Direct Agent Access: You can use
model: "your_agent_name"
directly without any mapping configuration.
🎉 Welcome to the OpenAI Ecosystem!
Your Vizra agents are now compatible with thousands of existing tools and workflows
Ready for Professional AI Agent Evaluation? 🚀
Evaluate and debug your Vizra ADK agents with professional cloud tools. Get early access to Vizra Cloud and be among the first to experience advanced evaluation and trace analysis at scale.
Join other developers already on the waitlist. No spam, just launch updates.