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 example

Example: turn lead qualification into a reviewable workflow

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.

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,
  },
});

Tutorial path

How to implement it

Step 01

Start with one user decision, such as qualify this lead, triage this tender, or draft this response.

Step 02

Define the input contract, expected output shape, allowed tools, and failure states before writing UI.

Step 03

Call the Responses API from a server route and store the request, response id, parsed result, and reviewer decision.

Step 04

Render the output as editable fields with evidence links instead of a single blob of generated text.

Step 05

Add a second pass for retry, escalation, or manual review when the output is incomplete.

Checklist

Ready when these are true

Server-only API key handling

Typed request and response payloads

Stored response metadata

Human approval path

Clear empty, loading, and error states

Field notes

What matters in practice

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.

Avoid these mistakes

Common failure modes

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.

Practical tip

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.

Apply this to a build