Responses APITutorial7 min

Build a production AI feature with the Responses API

A practical route for moving from a prompt demo to a feature with state, tools, validation, and operator review.

Real workflow example

A B2B agency receives inbound project requests from email, a contact form, and LinkedIn. The old AI demo generated a paragraph saying whether the lead looked good, but sales still had to re-read the whole message and decide what to do.

The production version stores every request as a lead, sends the text plus account context to the Responses API, asks for a structured decision, and renders the result as fields: fit, budget signal, deadline risk, missing context, recommended reply, and reviewer action.

The user does not see a magical answer. They see a queue item with evidence, editable fields, and an approve/send/escalate path. That makes the AI output auditable and useful inside a real sales workflow.

Implementation approach

This guide is anchored in OpenAI Responses API guide. Use the official API behavior as the boundary, then design the surrounding product state so the feature can be reviewed, retried, and improved.

Start with one user decision, such as qualify this lead, triage this tender, or draft this response.
Define the input contract, expected output shape, allowed tools, and failure states before writing UI.
Call the Responses API from a server route and store the request, response id, parsed result, and reviewer decision.
Render the output as editable fields with evidence links instead of a single blob of generated text.
Add a second pass for retry, escalation, or manual review when the output is incomplete.

Server-side response run

const result = await openai.responses.create({
  model: "gpt-4.1-mini",
  input: [
    { role: "system", content: "Extract a reviewable operating decision. Return only valid JSON." },
    { role: "user", content: sourceText },
  ],
  text: {
    format: {
      type: "json_schema",
      name: "workflow_decision",
      schema: decisionSchema,
      strict: true,
    },
  },
});

await db.aiRun.create({
  data: {
    responseId: result.id,
    status: "needs_review",
    parsed: result.output_parsed,
  },
});

Field notes

Treat a response as one step in a product workflow, not the entire product.
Keep the model input, selected tools, output schema, and review state visible in your own system.
Persist enough context to explain why the feature made a recommendation.

Mistakes to avoid

Do not let the client call OpenAI directly with your API key.
Do not store only the final prose; keep response id, parsed fields, and reviewer decision.
Do not trigger email, CRM updates, or status changes until validation and approval pass.

Ready checklist

Server-only API key handling
Typed request and response payloads
Stored response metadata
Human approval path
Clear empty, loading, and error states

Practical note

Start with one decision that already costs the team time. A narrow workflow creates better examples, better evals, and a cleaner UI than a general assistant.

Use this as an implementation constraint, not just advice. The interface, server code, and validation path should make the same behavior true.

Apply this to a build