2. Make Your First Responses Requests
This section shows the Responses request surface from two angles. First, you inspect and run a raw HTTPS request so the endpoint, headers, and JSON body are visible. Then you use the OpenAI SDK for the same kind of application workflow, which is the path most production code should prefer once configuration is correct.
2.1 Inspect the Raw HTTPS Request Shape
Build a minimal Responses payload for a BrightCart support-assistant reply and render a copy-pasteable curl command. The command references $AWS_BEARER_TOKEN_BEDROCK instead of embedding a token, and the notebook does not execute shell commands that put bearer tokens in process arguments. Inspect the model, input, max_output_tokens, and store fields.
python
from __future__ import annotations
basic_curl_payload = {
"model": MODEL_ID,
"input": "BrightCart customer Maya asks why replacement order ORDER-8831 is delayed. Write two labeled plain-text lines for the support agent. Do not use leading hyphens or bold text.",
"max_output_tokens": 1024,
"store": False,
}
print_request_shape(basic_curl_payload)
print_labeled_text("Result", build_curl_command(basic_curl_payload))
print_key_takeaway('The curl command shows the raw HTTPS shape behind the SDK call.')Request shape
| field | value |
|---|---|
| model | openai.gpt-5.4 |
| max_output_tokens | 1024 |
| store | False |
| input | BrightCart customer Maya asks why replacement order ORDER-8831 is delayed. Write two labeled plain-text lines for the support agent. Do not use leading hyphens or bold text. |
Result
curl -sS https://bedrock-mantle.us-west-2.api.aws/openai/v1/responses -H 'Content-Type: application/json' -H 'Authorization: Bearer $AWS_BEARER_TOKEN_BEDROCK' -d '\{"model": "openai.gpt-5.4", "input": "BrightCart customer Maya asks why replacement order ORDER-8831 is delayed. Write two labeled plain-text lines for the support agent. Do not use leading hyphens or bold text.", "max_output_tokens": 1024, "store": false\}'
Key takeaway: The curl command shows the raw HTTPS shape behind the SDK call.
2.2 Send the Raw HTTPS Request
Send the same request through the raw HTTPS helper. This cell demonstrates the wire-level POST /responses path and extracts text from the response body by walking output items. Inspect the returned response ID, model, status, and text output to understand the schema your application receives.
python
from __future__ import annotations
print_request_shape(basic_curl_payload)
try:
basic_http_response = run_raw_http_request(basic_curl_payload)
record_check("Text generation", "pass", basic_http_response.get("id"))
response_text_parts = []
for item in basic_http_response.get("output", []):
for content in item.get("content", []):
if content.get("type") == "output_text":
response_text_parts.append(content.get("text", ""))
raw_http_output = "".join(response_text_parts).strip()
record_response("First raw HTTPS request", "text", raw_http_output)
print_labeled_text("Result", raw_http_output)
print_labeled_json("Response summary", {
"id": basic_http_response.get("id"),
"model": basic_http_response.get("model"),
"status": basic_http_response.get("status"),
})
print_key_takeaway("The response body contains message output that application code can extract as text.")
except Exception as exc:
handle_example_error("Text generation", exc)Request shape
| field | value |
|---|---|
| model | openai.gpt-5.4 |
| max_output_tokens | 1024 |
| store | False |
| input | BrightCart customer Maya asks why replacement order ORDER-8831 is delayed. Write two labeled plain-text lines for the support agent. Do not use leading hyphens or bold text. |
Result
Empathy: I’m sorry, Maya — your replacement order ORDER-8831 is delayed because the carrier reported a temporary transit hold at the regional sorting facility. Action: We’re monitoring the shipment closely and will send you an updated delivery estimate within 24 hours; if there’s no movement by then, we’ll review the next replacement or refund options with you.
Response summary
\{ "id": "resp_naythl6fvzhoctlsdogd4vpr673q5ibagqqpiujbast3sy6viroa", "model": "openai.gpt-5.4", "status": "completed" \}
Key takeaway: The response body contains message output that application code can extract as text.
2.3 Use the OpenAI SDK
The OpenAI SDK can call OpenAI-compatible APIs when you pass the Bedrock bearer token and base URL explicitly. This cell sends a text-generation request through client.responses.create, sets reasoning.effort to low, and prints a compact response summary. Inspect the output text, token counts, output item types, and any reasoning-token metadata returned by the endpoint.
Official docs: Reasoning models describes using reasoning effort with the Responses API.
python
from __future__ import annotations
sdk_text_payload = {
"model": MODEL_ID,
"input": "Write a three-sentence overview for a developer building a BrightCart support assistant with the Responses API.",
"reasoning": {"effort": "low"},
"max_output_tokens": 1024,
"store": False,
}
print_request_shape(sdk_text_payload)
try:
text_response = create_response(**sdk_text_payload)
sdk_text = output_text(text_response).strip()
require(sdk_text, "SDK text response did not return output text.")
record_check("Text generation", "pass", summarize_response(text_response))
record_check("Reasoning effort", "pass", summarize_response(text_response))
record_response("SDK text generation", "text", sdk_text)
print_labeled_text("Result", sdk_text)
print_response_summary(text_response)
print_key_takeaway('The SDK returns a response object with text, status, token usage, and output item metadata.')
except Exception as exc:
handle_example_error(["Text generation", "Reasoning effort"], exc)Request shape
| field | value |
|---|---|
| model | openai.gpt-5.4 |
| max_output_tokens | 1024 |
| store | False |
| reasoning | \{'effort': 'low'\} |
| input | Write a three-sentence overview for a developer building a BrightCart support assistant with the Responses API. |
Result
Use the Responses API to build a BrightCart support assistant that can answer customer questions, summarize policies, and guide users through common workflows like order tracking, refunds, and account updates. Ground the assistant in BrightCart documentation and connect it to relevant backend tools or APIs so it can retrieve live order data, check account status, and provide accurate, context-aware support responses. Design the experience around clear system instructions, structured tool calling, and conversation state management so the assistant stays on-brand, reliable, and safe when handling customer issues.
Response summary
| field | value |
|---|---|
| id | resp_nmvqefzghd5hi67uwy4wfvhwnnzild3lslqsxqor3cat63kmucoq |
| model | openai.gpt-5.4 |
| status | completed |
| output_item_types | ['reasoning', 'message'] |
| input_tokens | 177 |
| cached_input_tokens | 0 |
| output_tokens | 129 |
| total_tokens | 306 |
| reasoning_output_tokens | 18 |
| service_tier | default |
Key takeaway: The SDK returns a response object with text, status, token usage, and output item metadata.
2.4 Create and Retrieve a Response
The Responses API can store a response and retrieve it later by ID. This pattern is useful for audit trails, debugging, and follow-up turns that reference prior context. This cell creates a stored response, tracks the ID for cleanup, retrieves it, and compares the retrieved text and usage metadata.
python
from __future__ import annotations
lifecycle_payload = {
"model": MODEL_ID,
"input": (
"BrightCart is building a support assistant for delayed replacement orders. "
"Return exactly three labeled plain-text lines: goal, data needed, and human-review rule. Do not use leading hyphens or bold text."
),
"max_output_tokens": 1024,
"store": True,
}
print_request_shape(lifecycle_payload)
try:
lifecycle_response = create_response(**lifecycle_payload)
remember_stored_response(lifecycle_response)
retrieved_response = retrieve_response(lifecycle_response.id)
retrieved_summary = summarize_response(retrieved_response)
retrieved_text = output_text(retrieved_response).strip()
require(retrieved_text, "Retrieved response did not contain text output.")
lifecycle_status = "pass" if retrieved_summary.get("status") in {None, "completed"} else "warn"
record_check("Responses lifecycle", lifecycle_status, retrieved_response.id)
record_check("Response schema", "pass", retrieved_summary)
record_check("Usage metadata", "pass" if retrieved_summary.get("total_tokens") is not None else "warn", retrieved_summary)
record_response("Create and retrieve response", "text", retrieved_text)
print_labeled_text("Result", retrieved_text)
print_labeled_json("Created response summary", summarize_response(lifecycle_response))
print_response_summary(retrieved_summary)
print_key_takeaway('store=True lets an application retrieve the response later by ID with usage metadata intact.')
except Exception as exc:
handle_example_error(["Responses lifecycle", "Response schema", "Usage metadata"], exc)Request shape
| field | value |
|---|---|
| model | openai.gpt-5.4 |
| max_output_tokens | 1024 |
| store | True |
| input | BrightCart is building a support assistant for delayed replacement orders. Return exactly three labeled plain-text lines: goal, data needed, and human-review rule. Do not use leading hyphens or bold text. |
Result
goal: Help support agents explain delayed replacement orders, set expectations, and suggest next steps. data needed: Order ID, replacement order status, shipment/tracking events, delay reason, estimated ship/delivery date, customer contact history, inventory/backorder status, and applicable refund or reship policy. human-review rule: Escalate to a human if the delay exceeds policy thresholds, tracking is inconsistent or missing, the order appears lost, the customer is high-risk or highly upset, or any refund/reship exception is requested.
Created response summary
\{ "id": "resp_cvhvh7y5ghwrpa35snvk4bzgcgthgxp4tgwkllmf5mrhs7dikfia", "model": "openai.gpt-5.4", "status": "completed", "output_item_types": [ "message" ], "input_tokens": 198, "output_tokens": 109, "total_tokens": 307, "cached_input_tokens": 0, "reasoning_output_tokens": 0, "service_tier": "default" \}
Response summary
| field | value |
|---|---|
| id | resp_cvhvh7y5ghwrpa35snvk4bzgcgthgxp4tgwkllmf5mrhs7dikfia |
| model | openai.gpt-5.4 |
| status | completed |
| output_item_types | ['message'] |
| input_tokens | 198 |
| cached_input_tokens | 0 |
| output_tokens | 109 |
| total_tokens | 307 |
| reasoning_output_tokens | 0 |
| service_tier | default |
Key takeaway: store=True lets an application retrieve the response later by ID with usage metadata intact.
2.5 Add Reasoning Effort, Service Tier, and Prompt Cache Parameters
Model controls travel alongside the normal input. This request combines reasoning.effort, service_tier, prompt_cache_key, and prompt_cache_retention so you can see how operational controls and prompt-cache metadata appear in the same response schema as ordinary text output. Inspect service_tier, cached_input_tokens, reasoning token metadata, and total token usage.
Note: This notebook uses PROMPT_CACHE_RETENTION instead of hard-coding prompt_cache_retention. The value is in_memory for openai.gpt-5.4, and 24h for openai.gpt-5.5 and later models because those models require extended prompt caching.
python
from __future__ import annotations
control_payload = {
"model": MODEL_ID,
"input": (
"For the BrightCart support assistant, explain prompt caching in exactly two labeled plain-text lines: "
"one latency benefit and one consistency benefit."
),
"reasoning": {"effort": "low"},
"prompt_cache_key": "brightcart-support-policy-guide",
"prompt_cache_retention": PROMPT_CACHE_RETENTION,
"service_tier": "auto",
"max_output_tokens": 1024,
"store": False,
}
print_request_shape(control_payload)
try:
control_response = create_response(**control_payload)
control_summary = summarize_response(control_response)
control_text = output_text(control_response).strip()
require(control_text, "Control response did not return text.")
status = "pass" if control_summary.get("status") in {None, "completed"} else "warn"
record_check("Prompt caching", "pass" if control_summary.get("cached_input_tokens") is not None else "warn", control_summary)
record_check("Service tier", "pass" if control_summary.get("service_tier") is not None else "warn", control_summary)
record_check("Reasoning effort", status, control_summary)
record_response("Service tier and prompt cache request", "text", control_text)
print_labeled_text("Result", control_text)
print_response_summary(control_summary)
print_key_takeaway('Model controls travel with the same request as normal input, while returned metadata can vary by endpoint.')
except Exception as exc:
handle_example_error(["Prompt caching", "Service tier", "Reasoning effort"], exc)Request shape
| field | value |
|---|---|
| model | openai.gpt-5.4 |
| max_output_tokens | 1024 |
| store | False |
| service_tier | auto |
| prompt_cache_key | brightcart-support-policy-guide |
| prompt_cache_retention | in_memory |
| reasoning | \{'effort': 'low'\} |
| input | For the BrightCart support assistant, explain prompt caching in exactly two labeled plain-text lines: one latency benefit and one consistency benefit. |
Result
Latency benefit: Prompt caching lets the BrightCart support assistant reuse previously processed context, reducing response time for repeated or similar requests. Consistency benefit: Prompt caching helps the BrightCart support assistant return more uniform answers by reusing the same established prompt context across interactions.
Response summary
| field | value |
|---|---|
| id | resp_q4akwbeynfwfwnt5i4tdwkpcgsffdu4lqvng7lnwaob53opswvwq |
| model | openai.gpt-5.4 |
| status | completed |
| output_item_types | ['reasoning', 'message'] |
| input_tokens | 183 |
| cached_input_tokens | 0 |
| output_tokens | 91 |
| total_tokens | 274 |
| reasoning_output_tokens | 34 |
| service_tier | default |
Key takeaway: Model controls travel with the same request as normal input, while returned metadata can vary by endpoint.