Provider SDK migration
Integrate existing OpenAI, Anthropic, or Gemini SDK applications into AGTCloud and systematically check compatibility boundaries.
If an application already uses an OpenAI, Anthropic, or Gemini SDK, it can usually retain the SDK and application structure while pointing the client to the corresponding AGTCloud-compatible protocol. Migration involves more than replacing an address: authentication, model IDs, automatically appended paths, request fields, and response parsing must all be checked.
Keep the protocol consistent
OpenAI, Anthropic Messages, and Gemini Generate Content are different protocols. Replace service addresses only within the same protocol. If you also change protocols, treat the work as a full interface migration and test it accordingly.
Pre-migration inventory
First, record the actual capabilities of the current application, avoiding only verifying the simplest text requests.
| Inspection items | What needs to be recorded |
|---|---|
| SDK | Package name, language, version, and synchronous or asynchronous client |
| Protocol | Chat Completions, Responses, Messages, or Generate Content |
| Model | The current model ID, and whether there is a model whitelist in the code |
| Input | Text, images, files, system commands, and historical messages |
| Output | Text shortcut properties, complete response objects, and custom parsing logic |
| Streaming | Event types, incremental splicing, and termination conditions |
| Tools | Tool definition, call ID, parameter parsing, and result return |
| Reliability | Timeout, retry, rate limiting, logging, and rollback strategies |
Minimal changes
All three SDKs require the following configurations, but the method of filling them out is determined by the SDK.
| Configuration | Migration action |
|---|---|
| API address | Use the Origin or Base URL provided in the tutorial on this page to confirm whether the SDK automatically adds version paths |
| API Key | Read the AGTCloud API Key from the environment variable without writing it to the source code or repository |
| Model ID | Models that are visible with the current API Key and support the target protocol |
| Request method | Retain the original protocol's Client methods, such as chat.completions.create or messages.create |
| Response read | Check text, tools, usage, and error structures against AGTCloud Reference |
Migrate by SDK
The OpenAI SDK can call Chat Completions and Responses. The AGTCloud Base URL contains /v1.
| Before the move | After the move |
|---|---|
| API Key of the original service | AGTCLOUD_API_KEY Environment variables |
| The default address of the original service's Base URL or SDK | https://api.agtcloud.cn/v1 |
| Original model name | The MODEL_ID available to the current API Key |
| Existing Chat or Responses methods | Keep the same Client method |
Do not add /v1 repeatedly
https://api.agtcloud.cn/v1 already includes the API version path. Do not append another /v1, and do not enter a full endpoint such as /chat/completions or /responses.
For full installation, client initialization, and examples of Python and TypeScript, please refer to OpenAI SDK.
You can't just change three configurations
The following scenarios require adjusting business code rather than just replacing the Base URL, Key, and model:
- The app changed from Chat Completions to Responses;
- Application migration across protocols such as OpenAI, Anthropic, or Gemini;
- Code directly depends on a specific SDK response class, convenience property, or streaming event;
- Tool calls use protocol-specific definitions and result return structures;
- Changes in multimodal content blocks, system instructions, or role names;
- The SDK automatically stitches the path, while the original project passes in the complete endpoint URL;
- Applications rely on native service-exclusive model discovery, file upload, or hosting tools.
Verify migration results
Verify a minimal text request
First, send a request that does not use streaming, tools, or multimodal content. Confirm that the request is sent to the expected API address and can read the text response.
Restoring the capacity needed for production
Restore item by item in the order of streaming, tool calls, structured output, multimodal and multi-turn states. Only one capability is added each time to facilitate differentiation.
Check for unsuccessful paths
At the very least, verify invalid API Keys, error model IDs, timeouts, rate limits, and connection interruptions. Ensure the application can read status codes and error messages without retrying indefinitely.
Compare business outcomes
Don't just check HTTP 200. Synchronize and compare text content, tool parameters, end reason, Usage, stream end condition, and Request ID in logs.
Phased switching and rollback
- Retain independent configurations for both new and old Providers, and do not scatter addresses and model names in business code.
- First, develop or test traffic using AGTCloud, then gradually expand the scope.
- Record success rates, delays, error types, and functional differences at each stage.
- Keep the original Provider configuration and controllable fallback switch, and clean up the old configuration after confirming stability.
Do not treat silent acceptance as support
Some compatible implementations accept unknown fields without applying the requested capability. Verify the actual output and response structure; an HTTP status alone does not prove that a field took effect.
Next
- View SDK Overview Select the corresponding tutorial;
- View API Key, Base URL, and Authentication;
- If you are preparing to migrate from Chat to Responses, please continue reading Chat Completions → Responses;
- When encountering status codes or request failures, refer to Error and Troubleshooting.