AI GUIDEStart with the decision, not the agent
A client asks your agency: ‘Please add a product comparison page. Tell me the likely scope and prepare a task for the team.’ An assistant could draft a response from supplied notes. A workflow could check required fields and prepare a task in a fixed sequence. An agent could investigate the repository and choose further checks based on what it discovers. These are different designs for the same request.
The useful question is: which decisions actually require a model? Writing a clear explanation may benefit from Claude. Checking whether a customer has access to a project belongs in application code. Authorising a promised delivery date belongs to the responsible person.
By the end of this lesson, you should be able to draw those boundaries, select a design and explain its failure path. You need basic familiarity with APIs: the interfaces through which software requests operations from other software. No account, payment or running integration is required for this design exercise. Read the Academy lesson ‘Understand tools, workflows and agents’ first if these terms are new.
Use the least autonomy the task needs
Design 1: an answer from supplied material. Give Claude the request, relevant notes and a requested output. It can organise the information, list assumptions and identify missing details. It cannot establish the current repository state without access to it. A sentence saying ‘I checked the code’ is not evidence of a check.
Design 2: a fixed workflow. Your application always validates project access, fetches an approved document, asks Claude to draft a brief and presents it for review. Code determines the sequence. The model handles a bounded part such as explaining the requirements. This is a good candidate when the necessary steps are known in advance.
Design 3: an agent. The model chooses which permitted investigation to perform next. After reading one file, it might request a dependency search or an existing test. The surrounding application still decides whether each operation is allowed. Choose this when the useful next step depends on intermediate findings.
Anthropic distinguishes workflows with predefined paths from agents that dynamically direct their process. That distinction helps design the application; it does not mean the most autonomous option will be the best. We still have to test our particular task.
A draft task without an invented commitment
Everything in this example is fictional. Input: ‘For project Pine, add comparison of up to three products. Mobile support matters. Can we have it on Friday?’ Supplied policy: only a project manager may approve a delivery date. Supplied project note: a product listing exists; no information about comparison is available.
A useful first output is: ‘Goal: compare up to three products, including mobile use. Known: the project has a product listing. Unknown: whether comparison already exists, which attributes must be shown, and the expected mobile interaction. Delivery: Friday requested, not approved. Next step: inspect the current implementation and ask the project manager to assess the date.’
That output creates value before any agent is needed. It separates requirements from assumptions. A fixed workflow can produce it from supplied information. If the team also needs an implementation investigation, add a separate read-only investigation stage. Allow it to search the authorised repository and read selected files; require it to attach file references to its findings.
The investigation should return a proposed scope, unresolved questions and evidence. It should not silently become an estimate, a client promise or an implementation change. Saving a task is another operation with its own authorisation. Preparing a draft does not establish permission to save or send it.
A model request is not an executed operation
For client tools in the Claude Messages API, the model returns a tool_use block describing a requested operation. Your application runs the permitted operation and returns a tool_result associated with that request. The model can then use the result in a later response. Do not report that a task was saved merely because the model asked to save it.
The response field stop_reason explains why generation stopped. tool_use means a tool operation is requested; end_turn means the response ended naturally. Neither is a business receipt. A completed task requires evidence from the application, such as a confirmed record identifier. An interrupted response, for example max_tokens, needs its own handling rather than being accepted as a complete brief.
For this exercise, define narrow operations: read_project_note(project_id), search_project_files(project_id, query), and prepare_task_draft(project_id, brief). The application checks the signed-in user's project access before each operation. Do not provide a write operation during the investigation stage. In Claude Code, permissions are configured separately from written project instructions; a request in a prompt is not an access-control mechanism.
These are design examples, not a tested API implementation. Consult the current linked documentation before writing a tool loop or selecting a Claude Code permission mode.
Plan the unsuccessful run first
Now change the exercise. The repository search times out. The useful result is a partial brief that says the implementation has not been checked, with a retry or manual-review option. ‘No comparison code exists’ would be an unsupported conclusion.
Next, imagine the project lookup denies access. The application stops that investigation. It does not broaden the search to other customers or ask the model to infer the missing project information.
Finally, imagine a future approved workflow saves a task but loses the response. Blindly saving again could create a duplicate. Design a way to check operation status and prevent repeated writes. This is an application requirement, not something a fluent model answer can settle.
For any agent investigation, specify time, cost and action limits as safeguards, and return an explicit incomplete status when a limit is reached. A limit is not proof of success. Start with one investigator; add specialised agents only if a measured problem justifies the extra coordination.
Make a one-page design you can defend
Use the fictional Pine request. Write five things: the deliverable, the supplied facts, the unknowns, the allowed operations and the success evidence. Then choose an answer-only design, a fixed workflow or an agent, and explain why the simpler alternative is insufficient if you choose more autonomy.
Test the design on paper with four cases: the request is complete; product attributes are missing; repository access is denied; a search times out. For each case, write what the user sees and what the application must not do.
A passing design keeps Friday unapproved, preserves unknowns, never reads an unauthorised project and never treats a model statement as proof that a write succeeded. For the original request, a fixed workflow producing a reviewable draft is a reasonable baseline. A bounded agent investigation becomes useful when the next repository check depends on what was found. Both choices need evidence, not an impressive agent count.
If you later implement this exercise, compare drafts against these criteria and record failures before increasing autonomy. This lesson does not assess exam readiness. Continue with CA02 to trace the client-tool cycle and interrupted responses.
Sources
Read the original sources to explore the topic and check specific claims.
Claude documentation: How tool use works ↗
Claude documentation: Stop reasons and fallback ↗
Claude Code documentation: Configure permissions ↗