Key facts
| SDK shape | Agents, handoffs, guardrails, sessions and tool calling in Python and TypeScript |
| Model coupling | Runs against OpenAI-compatible chat completions endpoints |
| Migration surface | Model client base URL and model name mapping |
| Kept in your code | Agent instructions, tools, handoffs, guardrails and session store |
| Tracing | SDK tracing integrations stay yours; Plugsky provides audit logs |
| Model breadth | 30+ models on one key after migration, from free tiers to frontier |
| Deployment | Cloud, VPC, on-prem and air-gapped with region choice |
| Honest limit | Hosted tools and responses-style features have no equivalent yet |
TL;DR
- Agents SDK migration is a client configuration change, not a rewrite.
- Keep agents, tools, handoffs and guardrails exactly as they are.
- Re-map model names and re-check tool-call schemas per model.
- Move tracing to your own observability; Plugsky adds audit logs.
- Run your evaluation set before and after, then cut over gradually.
How it works, step by step
- Inventory your agents, tools, handoffs, guardrails and session store.
- Check which model client you use and whether it accepts a custom base URL.
- Create a Plugsky key and map each model name to a catalogue equivalent.
- Run the agent suite against the new endpoint with identical instructions and tools.
- Fix any tool-schema mismatches and re-test argument validation on each model.
- Replace hosted tracing with your own spans, plus Plugsky audit logs for platform events.
- Cut over by percentage and keep the old provider configured as a fallback.
Try it yourself
Open the OpenAI migration checker →
What maps cleanly and what does not
The Agents SDK is intentionally provider-flexible: agents declare instructions and tools, handoffs pass control between them, and guardrails validate input or output. All of that is your code and none of it changes when the model endpoint changes.
What needs attention: the model client must be configured with an OpenAI-compatible base URL and a specific model name; tool-call schemas should be re-verified per model because argument formatting differs slightly between families; and hosted conveniences such as built-in web search or file tools have no direct Plugsky equivalent, so reimplement them as your own tools if you rely on them.
Tracing, sessions and observability
SDK tracing is tied to its own dashboard and integrations. After migration, export spans to your own observability stack so you keep run-level visibility, while Plugsky's audit logs cover platform events such as key use and administrative changes. Sessions and conversation state are already yours; store them where your retention policy requires.
- Keep: agent definitions, tools, guardrails, session store, evaluation sets.
- Change: model client base URL, model names, tracing exporter.
- Re-verify: tool-call arguments, stop reasons, streaming behaviour.
- Add: scoped keys per environment and audit log review.
A safe cutover sequence
Migrate in this order: staging first with the full evaluation set, then shadow traffic where both providers process the same inputs and you compare outputs offline, then a small production percentage, then full cutover. Keep the old provider configured so rollback is a configuration change.
Plugsky provides the destination: 30+ models on one OpenAI-compatible key with live function calling, streaming, JSON mode, embeddings, RAG and agents, plus scoped keys, RBAC, SSO/SCIM and audit logs, and deployment from shared cloud to VPC, on-prem and air-gapped. Assistants, responses, batch, files and fine-tuning endpoints are coming soon, so leave those workloads where they are until then. Self-serve plans are flat monthly and the free tier covers plugsky-micro and plugsky-lite; current plans are on the live pricing page.
Honest comparison
| Component | Before migration | After migration | Effort |
|---|---|---|---|
| Model client | OpenAI endpoint and model names | Plugsky base URL and mapped names | One config change |
| Agents and tools | SDK definitions | Unchanged | None |
| Handoffs and guardrails | SDK primitives | Unchanged | None |
| Tracing | SDK dashboard integrations | Your observability plus audit logs | Moderate |
| Hosted tools | Built-in search or file tools | Your own tool implementations | Varies by tool |
Frequently asked questions
Does the Agents SDK work with non-OpenAI endpoints?
Yes, when configured with an OpenAI-compatible chat completions client and a model name the endpoint serves. That is exactly how a Plugsky migration works.
Will my tools and handoffs keep working?
Yes. Tools, handoffs, guardrails and instructions are your code. Only the model client and model names change, though you should re-verify argument schemas per model.
What happens to tracing?
Configure your tracing exporter to your own observability stack. Plugsky adds platform-level audit logs for key and administrative events rather than run tracing.
Can I migrate gradually?
Yes. Run staging first, then shadow traffic for offline comparison, then a small production share, then full cutover with the old provider kept as a fallback.
Which models should I map to?
Map by task tier: a small fast model for routing and extraction, a mid model for drafting, a frontier model for planning. Test two candidates per tier against your evals.
Are hosted SDK tools available?
Some hosted features have no equivalent yet. Reimplement them as your own function tools, or keep those specific workloads on the original provider during the transition.
How do I validate the migration?
Run the same evaluation set on both providers, compare task success, tool-call validity, latency and cost per task, and require parity before increasing traffic share.