🚀 Technical Briefing: This tutorial is part of our deep-dive series on Agentic Workflows at Gate of AI. For the full technical breakdown, interactive code sandbox, and the native Arabic translation, visit the original article here.
Tutorial · Intermediate
Build a Prompt Contract Service with FastAPI
Learn how to design a FastAPI service around a versioned prompt contract and OpenAI Structured Outputs. The key principle is that a schema constrains an answer’s shape; your application must still check its meaning, handle refusals and incomplete responses, and authorize any requested action.
What Is a Prompt Contract Service?
A conventional API contract describes the inputs and outputs that an application accepts. A prompt contract applies a similar idea to an AI model’s runtime behavior: it describes the task, relevant context, permitted response shape, and boundaries the model should follow. Instead of treating a system prompt as documentation alone, this approach treats it as one component of an AI-facing interface.
That is an architectural experiment, not a claim that a prompt can replace a backend. A real service still needs application code to receive requests, validate inputs, connect to databases and external services, and decide what operations are allowed. A useful mental model is a layer above existing systems: a user request arrives at an API, an LLM runtime interprets it, and application code decides whether any resulting structured operation may proceed.
This tutorial uses support-ticket routing as a running example. A service might ask a model to classify a ticket into a set of permitted labels and return a structured result. The model’s result can inform a workflow, but it is not itself proof that the selected label is correct. Nor is a structured result authorization to issue a refund, change an account, or carry out another consequential operation.
Prerequisites and Scope
- Familiarity with Python, HTTP APIs, JSON, and FastAPI concepts.
- An OpenAI API account if you intend to connect the service to OpenAI.
- A defined use case, a limited set of allowed labels, and a plan for reviewing errors.
The available source material establishes the architecture and safety distinctions described here, but does not verify a particular SDK version, model name, pricing, or copy-and-run integration. For those details, consult the current official API and framework documentation before deployment. The steps below focus on building the service boundary and defining its responsibilities without presenting unverified provider-specific code as tested.
Step 1: Define the Application Contract
Start with the application’s actual need. Avoid vague objectives such as “understand the customer.” Write a bounded task such as “select one label from this approved set and provide a short explanation grounded in the supplied ticket.” Decide which input fields are necessary and which output fields a downstream application can safely consume.
For a routing service, the request contract could include a ticket identifier and the customer’s message. Its response contract could contain a route label, a brief rationale, and a review indicator. The approved labels should be defined by the application rather than invented by the model. If there are only a few valid destinations, represent them as an explicit enumeration in the output schema.
Document the purpose of every field. A rationale is an explanation for an operator, not a guarantee that the selected route is correct. A review indicator is a recommendation unless application logic gives it a separately defined effect. Avoid fields that imply authority the model does not have, such as an instruction to execute a payment or alter an account.
Keep the backend authoritative. It should decide which services are reachable, which operations are permitted, and whether a human or another approval process is required. The prompt can describe the task and the desired result, but it cannot independently establish permissions or make an operation legitimate.
Step 2: Write a Versioned Prompt Contract
Write the system prompt as a maintained application artifact. State the task, provide only the context needed to complete it, list the allowed labels, and describe the output expectations. Give the prompt a version identifier in your application’s configuration or records so that teams can associate a decision with the prompt version used to produce it.
Keep policy instructions distinct from user-provided content. A ticket is input data, not a source of authority to change the service’s contract. Tell the model how to treat the ticket for the task, but do not rely on that instruction alone to neutralize malicious or irrelevant content. The surrounding application must still validate the response and restrict what can happen next.
Write instructions that can be evaluated. For example, specify that the model must choose one item from the documented label set and return the fields required by the schema. Avoid promising that a prompt will prevent every error or prompt-injection attempt. Prompts guide model behavior; they do not remove the need for application controls.
Maintain changes deliberately. When the task, labels, or output fields change, update the contract and assess the impact on consumers. A prompt change can alter the meaning of a field even when the JSON structure remains unchanged. Versioning makes that behavioral change easier to identify in investigations and evaluations.
Step 3: Define a Structured Output Schema
Use Structured Outputs when a caller needs a response conforming to a specified schema. A schema can constrain field names, types, and, where configured, the permitted values of an enumeration. This is useful for a routing interface because it can prevent the response from inventing an undocumented label or adding arbitrary fields.
Do not confuse this guarantee with correctness. If a schema allows four route labels, the model can return a structurally valid label that is still wrong for the ticket. Schema adherence answers a question about form; it does not establish that the selected value is factually or operationally appropriate.
Design the schema around the downstream application, not around everything the model could say. Make fields explicit and keep free-form text bounded where appropriate. Decide how the service will respond when it cannot accept the model’s result. In particular, handle refusals and incomplete responses as distinct outcomes rather than treating them as successful classifications.
On the FastAPI side, validate incoming requests at the HTTP boundary and validate accepted model results before passing them to other application components. The exact code for connecting a current OpenAI SDK to FastAPI depends on the supported API and library versions; verify it against current official documentation. Do not silently parse arbitrary text as a successful structured response.
Step 4: Separate Model Requests from Application Execution
Organize the service into responsibilities. The HTTP layer accepts a request and returns a response. A model-integration layer sends the task and schema to the provider and reports whether it received a usable result. A policy layer checks the result against application rules. An execution layer, if needed, calls authorized backend services only after those checks.
This separation matters especially when using function calling. A model-generated function call is a proposed request for the application to perform work. It is not evidence that the caller is authorized, that the requested action is safe, or that the operation should run. Application code must validate the arguments and apply authorization before executing a function.
For example, a model might propose an operation associated with a customer account. The backend should independently establish whether the account exists, whether the caller may act on it, whether the operation is allowed under current rules, and whether additional approval is needed. A prompt that says “only perform authorized actions” cannot substitute for those checks.
Keep permissions and deterministic requirements in code and authoritative data. Exact access rules, approval requirements, and other non-negotiable conditions should not be delegated to a model’s interpretation of a prompt. The model may help extract or classify information; the application remains responsible for deciding what that information permits.
Step 5: Handle Refusals, Incomplete Results, and Errors
A service should distinguish a complete, usable structured result from a refusal, an incomplete response, a provider error, or a response that fails application validation. The verified guidance specifically calls out refusals and incomplete responses as cases an implementation must handle. Treating all of them as ordinary JSON results creates ambiguous behavior for callers.
Define an explicit failure policy before connecting the endpoint to a workflow. Depending on the use case, the service might return a controlled error, request another review, or send the item to a human. Do not silently map every failure to a default route: that can make an unavailable or unresponsive model appear to have made a valid decision.
Keep error messages suitable for API consumers and avoid exposing secrets or internal implementation details. Record enough operational information to investigate failures, while avoiding unnecessary collection of customer content. A failure path should be visible to operators and predictable to clients.
When a response is available, validate its structure and then evaluate its meaning against application rules. These are separate checks: a response may pass schema validation and still violate a business rule. The application should reject, escalate, or otherwise handle that case according to the product’s defined policy.
Step 6: Expose the Contract Through FastAPI
Create a FastAPI endpoint that accepts the request model and returns a documented response model. Keep the HTTP route thin: it should validate the incoming shape, call the service layer, handle its defined outcomes, and return an appropriate result. Avoid putting policy, provider integration, and execution logic into one large route handler.
Document what the endpoint does and, just as importantly, what it does not do. If it returns a recommended route, call it a recommendation. Do not describe it as an authorized action unless the application actually performed the required authorization and execution steps. Do not accept a user-supplied prompt or policy as if it were trusted service configuration.
Before publishing the endpoint, decide who may call it and which backend capabilities it can reach. Authentication, authorization, request limits, and operational controls are application responsibilities; they are not supplied by a structured output schema. The provided sources do not prescribe a specific FastAPI deployment configuration, so verify those details against the environment in which you will run the service.
Document the service contract in terms clients can rely on: accepted input, possible successful outputs, and behavior for refusal, incomplete output, validation failure, or unavailable upstream service. Keep the public contract stable when possible, and version intentional changes that affect consumers.
Step 7: Evaluate Decisions, Not Just JSON
Build a representative evaluation set before using the service in a consequential workflow. Include ordinary examples, ambiguous cases, and cases where a wrong classification would matter. For each case, define the expected behavior in terms of the labels and safety decisions your application cares about.
Test the schema and the decision separately. Schema tests check that required fields and allowed values are respected. Decision tests check whether the selected label and any escalation recommendation are appropriate for the example. Passing the first category of tests does not mean the second has passed.
Review model behavior whenever you change the prompt, schema, supported labels, or model configuration. Compare results against the same test cases, investigate regressions, and decide in advance what failures block a release. The context supports this core distinction between schema adherence and correctness; it does not establish a particular accuracy threshold or benchmark, so set thresholds from your own use case and evaluation data.
Include human review where the consequences of an incorrect decision warrant it. Record corrections in a way that can inform future evaluation. Keep the review process separate from automatic execution so that an AI-generated label does not become an irreversible action by accident.
Common Design Mistakes
- Treating valid JSON as proof. A schema constrains output shape, not whether the answer is true or correct.
- Treating a function call as authorization. A model can propose a call; application code must validate and authorize it before execution.
- Using the prompt as the whole backend. Databases, APIs, services, access rules, and execution remain application responsibilities.
- Ignoring refusals or incomplete responses. Define explicit behavior for both instead of assuming every request yields a usable result.
- Failing silently. A fallback that looks like a successful decision can hide provider or validation failures.
- Changing behavior without tracking it. Version prompt contracts and assess changes against representative cases.
Conclusion
A prompt contract can provide a useful, structured interface between natural-language requests and an existing application. FastAPI can serve as the HTTP boundary, while the model returns a response constrained by a schema. The pattern is most useful when its limits are explicit: schema validity is not decision correctness, a proposed tool call is not authorization, and a prompt does not replace the backend.
Build the service around a bounded task, an explicit schema, clear handling for refusals and incomplete responses, and application-side validation and authorization. Then evaluate the decisions themselves before connecting them to real workflows. That is the practical path from prompt experimentation to a more reliable AI-enabled service.


