Convert Custom GPTs to Workspace Agents (Migration Guide)

When NOT to migrate

A Custom GPT that answers questions about one document, runs when a user explicitly messages it, and has no autonomous behavior is perfectly served by staying a GPT. Migration adds complexity and cost without delivering anything the GPT didn't already do.

Same for GPTs you've published to the GPT Store. Workspace Agents don't publish externally. If your GPT is serving external users, a Workspace Agent can't replace that — you'd need to keep the GPT alive regardless.

When migration is worth it

• A GPT your team messages every day with the same chain of requests — agent-shaped.
• A GPT that needs to run on a schedule or respond to an event — agents do this natively; GPTs don't.
• A GPT that should read and write to HubSpot / Slack / Drive — Workspace Agents' connectors are better than GPT Actions for these.
• A GPT owned by one person who left, where nobody knows the prompt — migration is a forcing function to document and transfer ownership.
• A GPT whose Actions break frequently because of API changes — Workspace Agents' native connectors are maintained by OpenAI.

Migration playbook

1. 01

   Triage your existing GPTs

   List every Custom GPT your team uses. For each: does the GPT's job need multi-step execution, continuous runtime, or team-wide ownership? If no to all three, keep it as a GPT. Most GPTs that answer a single question per invocation don't benefit from migration.

2. 02

   Rewrite the spec in agent terms

   Custom GPTs are defined by 'instructions + knowledge + actions.' Workspace Agents need 'trigger + steps + tools + success criteria.' Rewrite the spec using the agent frame. This forces clarity on what actually happens and usually exposes assumptions the GPT made implicitly.

3. 03

   Port the system prompt

   The GPT's custom instructions become the agent's system prompt. Minor rewrites needed: remove references to 'when the user asks' (agents may run without a user), add references to the trigger that starts the workflow, be explicit about tool-calling behavior.

4. 04

   Migrate knowledge to connectors

   GPTs have knowledge files uploaded at build time. Workspace Agents prefer live connector access (Drive, Notion, etc.) so the source stays current. Decide whether each knowledge file should become a connector reference, stay as a static upload, or be re-authored entirely.

5. 05

   Rebuild Actions as Workspace connectors

   GPT Actions (OpenAPI-based) port conceptually but not mechanically. Reuse the OpenAPI spec, but re-wire authentication and permissions through the Workspace Agent's admin controls. Test each action individually before chaining.

6. 06

   Define the trigger

   GPTs trigger on user messages. Agents trigger on events, schedules, or messages. Pick the right trigger for the workflow. If the answer is 'still user messages,' the GPT probably shouldn't have been migrated.

7. 07

   Run both in parallel for 2 weeks

   Before retiring the GPT, run the new Workspace Agent in parallel. Same inputs, compare outputs. Find the divergences, tune the prompt. Only retire the GPT once the agent consistently matches or exceeds.

What carries over automatically

Questions