A useful agent workflow needs a clear objective, a bounded set of actions, and a dependable way to establish what happened. The model is one part of that system. The application around it owns the execution contract.
I start an agent design by asking four questions: what can it decide, what can it do, how is progress recorded, and what evidence establishes success? Those questions lead directly to tool boundaries, state, authorization, and evaluation.
Choose the right amount of autonomy
Some tasks have a known sequence. Others require decisions about which information to retrieve or which step to take next. The architecture should reflect that difference.
Anthropic's architectural distinction is useful here: workflows follow predefined code paths, while agents can direct their own process and tool use. Its guide to effective agents explains that distinction and several foundational patterns. The tooling has evolved since that guide was published, so its lasting value is the design reasoning.
For a catalog-enrichment feature, a fixed pipeline may be enough: retrieve an item, generate a description, validate it, and send it for review. Letting a model decide whether validation is necessary would weaken the system without helping the user.
Add autonomy where the task benefits from judgment. Keep predictable requirements in ordinary application logic.
Define tools as application contracts
A tool should have a narrow purpose, explicit input, and an understandable result. The surrounding application should validate the request and enforce authorization using trusted context.
Consider a tool that prepares a product update. An illustrative contract could look like this:
{
"tool": "prepare_product_description",
"input": {
"product_id": "product_123",
"proposed_description": "A proposed description for review."
},
"result": {
"status": "review_required",
"change_id": "change_456"
}
}
The store identity and the current user's permissions should come from the authenticated application context. The model should not be able to select a different merchant by adding an arbitrary identifier.
The contract also distinguishes preparing a change from publishing it. That distinction lets the interface show the proposed content, request review where appropriate, and apply the action through an authorized pathway.
Make workflow state explicit
A conversation transcript is useful context, but an application often needs a more precise record of execution. A job may need to survive a worker restart, resume after a review, or explain why it stopped.
Define the important states and legal transitions. For example:
queued
-> gathering_context
-> preparing_change
-> awaiting_review
-> applying_change
-> completed
Any active state may transition to:
failed, cancelled, or needs_attention
This is an illustrative state model. The right states depend on the product. What matters is that the application can determine whether an action is pending, completed, or uncertain without asking the model to reconstruct that fact from prose.
Record the job identity, relevant input versions, tool attempts, and durable results. Make it possible to answer “what has already happened?” before resuming work.
Design for uncertain outcomes
A timeout does not prove that an action failed. A remote service may have committed a change before the response was lost. Repeating a non-idempotent action can then create a duplicate effect.
For actions that support it, use an idempotency key tied to the intended operation. Persist the relationship between that operation and the external result. When the outcome is uncertain, reconcile with the service before deciding to repeat the action.
Classify failures rather than retrying everything. A temporary connection error, an invalid input, and an authorization failure need different responses. Repeatedly sending a structurally invalid tool request wastes time and can obscure the real issue.
Set limits on retries, total execution time, tool calls, and cost where the provider and application make those limits enforceable. Reaching a limit should create a meaningful product state with enough context for the next action.
Keep untrusted content out of authority
Retrieved pages, catalog descriptions, documents, and tool output can contain instructions aimed at the model. Treat that material as data. It should not expand the agent's permissions or change the user's objective.
OWASP's prompt-injection overview describes both direct instructions and malicious instructions embedded in external content. Application-level authorization and narrow tool capabilities remain necessary even when the prompt clearly states the intended boundaries.
For a commerce assistant, a product description can inform an answer. It should not authorize changing store settings or exposing another customer's order. The application must enforce that boundary when a tool is invoked.
Evaluate the task, including failure
A polished conversation is not sufficient evidence that the task succeeded. Evaluate the application result: was the correct product selected, was the change valid, was it applied once, and could the user inspect it?
Build a representative evaluation set. Include ordinary tasks, missing information, ambiguous requests, outdated data, invalid tool output, permission failures, and interrupted execution.
Measure different outcomes separately. A workflow that refuses every action may avoid incorrect changes but fail to provide useful assistance. A workflow that completes quickly may still make unacceptable errors. The acceptable balance depends on the task and the consequences of an incorrect action.
Keep evaluation examples versioned alongside the behavior they test. When a tool or prompt changes, the relevant cases should be easy to rerun and inspect.
Give people an understandable interface
The user needs to know what the system is doing and what requires attention. Useful states include “review this change,” “more information needed,” and “could not confirm the result.” Avoid showing a completed state when only a model response has finished.
When work stops, explain the consequence and offer a practical next step. Preserve useful progress where the application can do so reliably.
An agent becomes a dependable product capability when its decisions fit inside clear engineering boundaries. Tools, durable state, authorization, recovery, and evaluation give those boundaries substance.
Put the ideas into practice.
Work through your development process, architecture, or next engineering challenge with me.
Explore one-to-one mentorship