AI workflows, agents and tool contracts

Why it matters

Agentic features move LLMs from producing text to changing state: sending email, updating a CRM, running code. The hard problems are mostly classic distributed-systems and security problems in a new setting: contracts, authorization, retries, idempotency and auditability. In an AI-assisted outreach product, for example, the difference between a draft that a user approves and an email sent automatically is the central design decision, and interviewers probe exactly that kind of judgment.

Core ideas

Workflows versus agents. A workflow is code that calls models along predefined paths; an agent lets the model choose the next step and the tools to use, in a loop, until it decides it is done. Workflows are cheaper, more predictable and easier to test; agents handle open-ended tasks whose steps cannot be enumerated, at the cost of latency, spend and compounding errors. Start with the simplest thing that works: one well-designed call with retrieval, then a workflow pattern.

• Prompt chaining: a fixed sequence of steps with programmatic checks between them.
• Routing: classify the input, then send it to a specialized path or model.
• Parallelization: split into independent subtasks, or sample several times and vote.
• Orchestrator-workers: a model plans subtasks dynamically and delegates them.
• Evaluator-optimizer: one call drafts, another critiques against criteria, repeat.

Use an agent when the path genuinely depends on intermediate results, and give it budgets (steps, tokens, wall time), explicit stopping conditions and a way to ask a human for help.

Tool contracts. A tool is an API whose client is a model. Specify:

• a precise name and description: what it does, when to use it, what it does not do;
• an input schema with types, enums, required fields and ranges;
• server-side validation of every argument, because model-produced arguments are untrusted input, like form data;
• structured, actionable errors ("start_date must be in the future; received 2024-01-03") that let the model correct itself;
• concise outputs containing what the next step needs, with stable identifiers rather than large dumps.

A few task-shaped tools ("schedule_meeting") usually work better than thin wrappers around every endpoint ("list_users", "list_events", "create_event").

Permissions. Authority belongs to the user, never to the model. Every tool call executes with the end user's identity and is authorized on the server against that user, the tenant and the specific resource, exactly as if the user had called the API directly. Grant the minimum scopes the task needs (read-only where possible), keep credentials out of prompts, and never let a model-chosen parameter such as tenant_id widen access.

Side effects. Classify each tool as read-only, reversible or irreversible. For writes: accept an idempotency key so a retry after a timeout cannot duplicate the action; offer a preview or dry run; require explicit human confirmation for irreversible or external actions (sending, paying, deleting); rate-limit; and record who approved what. For multi-step operations, design compensating actions such as cancel or undo.

Human review. Put people at approval gates for high-impact actions, route low-confidence or policy-sensitive cases to review, and sample routine outputs for audit. Make review fast by showing the proposed action, its inputs, its sources and a diff.

Observability. Log full trajectories (prompts, tool calls, arguments, results, decisions) with request IDs, so failures can be replayed and turned into evaluation cases.

Common misconceptions

• "Agents are more advanced, so prefer them." Use the simplest pattern that meets the requirement; many proposed agents should be workflows.
• "The system prompt can enforce permissions." Prompts are not security boundaries; enforce authorization in the tool server.
• "The provider's schema validation is enough." Validate again on the server, including semantics: does this record belong to this tenant?
• "Retries are harmless." Retrying a non-idempotent write after a timeout can duplicate it; use idempotency keys.
• "Human approval slows everything down, so skip it." Gate only irreversible or external actions and make approval quick; that is usually a small share of calls.
• "More tools make an agent more capable." Overlapping tools confuse tool selection and widen the attack surface.

How to approach it

Design one tool end to end on paper: schema, validation, authorization check, idempotency, errors and logging. Then take a task you know well and decide which parts are a workflow, which need an agent, and where a human approves. Map the OWASP "excessive agency" risk onto your design. Senior-level discussions add failure recovery, cost control and the evaluation of trajectories.