In production software engineering, prompts are executable code. Treating system prompts as informal prose invites non-deterministic failures, format corruptions, and multi-turn state drift. This architectural playbook synthesizes hard-learned lessons from deploying mission-critical AI agents across banking and enterprise SaaS.
01 Enforcing Strict Determinism with Pydantic & Instructor
Relying on natural language instructions like "Please return only JSON" is a known anti-pattern with failure rates exceeding 4% under stress. Production pipelines require schema-level constrained sampling:
from pydantic import BaseModel, Field
import instructor
from openai import OpenAI
# Define strongly-typed response schema
class ExecutionPlan(BaseModel):
target_file: str = Field(description="Exact absolute path to target file")
action: str = Field(pattern="^(create|modify|delete)$")
confidence_score: float = Field(ge=0.0, le=1.0)
reasoning_steps: list[str] = Field(min_items=1)
client = instructor.from_openai(OpenAI())
plan = client.chat.completions.create(
model="gpt-4o",
response_model=ExecutionPlan,
messages=[{{"role": "user", "content": "Refactor auth middleware to handle Bearer JWTs"}}],
max_retries=3
)
import instructor
from openai import OpenAI
# Define strongly-typed response schema
class ExecutionPlan(BaseModel):
target_file: str = Field(description="Exact absolute path to target file")
action: str = Field(pattern="^(create|modify|delete)$")
confidence_score: float = Field(ge=0.0, le=1.0)
reasoning_steps: list[str] = Field(min_items=1)
client = instructor.from_openai(OpenAI())
plan = client.chat.completions.create(
model="gpt-4o",
response_model=ExecutionPlan,
messages=[{{"role": "user", "content": "Refactor auth middleware to handle Bearer JWTs"}}],
max_retries=3
)