An API contract defines how software components interact: what a caller can send, what it can receive, and which interface it uses. Callers rely on that interface rather than the service’s private implementation. section 8.1.2 section 3.4.1
A contract can specify an HTTP endpoint’s request and response, or an agent tool’s name, description, parameter schema, and return type. In both cases, a defined boundary lets the implementation change without requiring callers to know its internals. section 8.1.2 section 3.4.1
A practical API contract makes the interaction inspectable:
- Specify the operation and input shape; for example, POST /generate accepts an input string. section 8.1.2
- Make the response format clear; the image endpoint returns PNG bytes, while a base64 response would require client-side decoding. section 8.1.2
- Define tool parameters and return types so agents can use tools without depending on their implementation. section 3.4.1
Image generation endpoint
A client sends JSON containing an input string to POST /generate. The service runs the image agent and returns image/png bytes; if the tool produces no image, the endpoint reports an error instead of returning an empty image. section 8.1.2
Listing 8.2 02_app.py (API code only)
app = FastAPI(
title="Fixed-Config Image Generator API",
version="1.0.0") #1
class GenerateIn(BaseModel):
input: str = Field(...,
description="Plain-language request (the agent crafts the prompt)."
) #2
@app.post("/generate", response_class=Response) #3
async def generate(body: GenerateIn):
agent = build_agent()
with trace("Image generation"):
result = await Runner.run(agent, body.input)
b64 = extract_image_b64(result) #4
if not b64:
raise HTTPException(
status_code=500, detail="Image generation tool produced no output."
)
png_bytes = base64.b64decode(b64)
return Response(content=png_bytes, media_type="image/png") #5
The listing shows the request model, POST endpoint, missing-output error, and PNG response in one implementation. section 8.1.2
