Every agent starts with a prompt. Describe the task, list the tools, define the behavior. Ship it.
This works for demos. It falls apart in production.
The problem is not the prompt. The problem is that prompts are implicit contracts. They describe what the agent should do, but they do not enforce it.
What a prompt cannot guarantee:
Input validation. What happens when the agent receives unexpected input? The prompt says what to do with valid input, but edge cases get handled inconsistently.
Output guarantees. What shape does the output take? The prompt describes it, but nothing prevents the agent from returning something slightly different.
State transitions. What states can the agent be in? What transitions are valid? The prompt implies state, but does not define it.
Failure modes. When things go wrong, what should the agent do? Prompts rarely enumerate every failure path.
The contract mindset:
Software engineers solved this decades ago with APIs. You do not just write a comment describing what a function does. You define a contract: inputs, outputs, error states, side effects.
Agents need the same rigor. Not because agents are software, but because agents are software with more moving parts.
What an agent contract looks like:
Input schema. Define what the agent accepts. Validate before processing.
Output schema. Define what the agent returns. Validate before returning.
State machine. Define valid states and transitions. Enforce at runtime.
Error taxonomy. Define error types and recovery paths. Make failure explicit.
Resource limits. Define timeouts, token limits, and cost bounds. Enforce hard stops.
Why this matters:
Without a contract, debugging an agent is debugging behavior. With a contract, you debug contract violations.
Behavior debugging is open-ended. Contract debugging is binary: did the agent fulfill its contract or not?
The real lesson:
Prompts are for behavior. Contracts are for reliability.
If your agent is going to run in production, it needs both. The prompt tells it what to do. The contract tells it what it cannot do.
Right now, most agents have prompts. Almost none have contracts.
That is the gap between demo and production.
Top comments (0)