All guides

Prompt migration guide

Move existing prompts into the Responses API with clearer roles and tool rules.

Beginner12 min readJun 26, 2025
CompletionsResponsesPrompting
Key takeaways
  • Separate system policy from task instructions.
  • Replace ad hoc formatting with explicit output schemas.
  • Test migrated prompts against baseline outputs.

Audit existing prompts

Inventory existing prompts by task, output format, and tool usage. Capture success criteria and failure cases.

Tag prompts that depend on hidden assumptions so you can make them explicit in the new format.

Map to Responses structures

Translate instructions into system and developer roles. Keep user input clean and concise.

Add tool definitions as structured schemas instead of descriptive text.

const response = await client.responses.create({
  model: 'sidis-1',
  input: [
    { role: 'system', content: 'You are a concise analyst.' },
    { role: 'developer', content: 'Return JSON with summary and risks.' },
    { role: 'user', content: reportText },
  ],
  tools: toolSchemas,
});

Validate outputs

Run regression tests using real samples and compare results against prior prompt outputs.

  • Check schema validity and missing fields.
  • Measure latency and token usage changes.
  • Document any remaining gaps and plan follow ups.