Tools, Function Calling & the Agent Loop

Tools are how a model touches the world. The agent loop is how it decides what to touch next. This lesson defines tools, agents and the loop exactly. Then it gives you a decision guide for the question every architect gets asked: do we need an agent, or is a workflow enough?

Function calling and tool use

Tool use lets a model choose an operation and produce structured inputs for your application to run. Examples are get_customer(), search_orders(), create_ticket(), calculate_quote() and send_notification(). A tool has a name, a description, an input schema, a function that runs it, an authorization boundary, a timeout and an error contract. The model chooses the tool. The application runs it. The model should never directly receive database credentials or unrestricted shell access.

model proposes tool call
  -> validate schema
  -> authenticate user
  -> authorize this operation for this principal
  -> enforce policy (limits, approvals)
  -> execute with timeout + idempotency key
  -> sanitize the result
  -> return result to the model
  -> continue or finish

• Tool descriptions are part of the model's decision environment. Vague descriptions lead to poor tool choice.
• Keep tools narrow and easy to combine. A tool called manage_everything is hard to secure and hard for a model to use reliably.
• Design tools around business capabilities, not raw database access.
• Use least privilege and explicit authorization. The model may suggest delete customer. But only an authorized backend decides.

What an agent is

An AI agent is a software system that uses a model to interpret a goal and decide what to do next. It uses the available tools or context and watches the results. It carries on until it reaches a stopping condition. The key difference is between a model call and an agent loop. One call generates an answer. A loop does several actions, based on intermediate results. An agent is a model, plus state and context, plus tools, plus a control loop, plus a stopping policy. Autonomy is a spectrum, not a switch. Architects should justify it, and not add it for novelty.

The loop as a state machine

A basic loop is: observe, decide, act, observe. The model reads the current state and proposes an action. A tool runs it. The result becomes the new state. The loop needs clear limits: a maximum number of rounds, a time budget, a tool budget, a token budget and a list of allowed actions. Production agents benefit from named states such as PLANNING, WAITING_FOR_TOOL, VALIDATING, NEEDS_HUMAN, COMPLETED and FAILED.

type AgentState = {
  runId: string; tenantId: string; goal: string;
  status: "PLANNING" | "WAITING_FOR_TOOL" | "VALIDATING" | "NEEDS_HUMAN" | "COMPLETED" | "FAILED";
  messages: Message[];          // what the model sees
  evidence: Evidence[];         // retrieved facts with sources
  toolResults: ToolResult[];
  budget: { maxSteps: number; stepsUsed: number; maxTokens: number; tokensUsed: number; deadline: string };
  retries: number;
  terminationReason?: string;
};

// Persist this after every step so a transient failure resumes from a checkpoint instead of restarting an expensive run.
// Long tasks: return a run ID immediately, execute asynchronously, expose a status endpoint.
// Any externally visible side effect needs an idempotency key: a retried "create payment" must never create two.

Workflow or agent? A decision guide

Not every task needs an agent. If the sequence is known, a fixed workflow is usually cheaper, faster, easier to test and easier to audit. Agents are most useful when the path cannot be fully set out in advance. Many real systems are hybrids. They have fixed orchestration around bounded agent steps. That is often the strongest production pattern.

• A known sequence: use a workflow.
• An unknown sequence, where the choice of tool depends on what is found: use a bounded agent.
• A high-risk action: use a fixed policy gate, and often a person.
• A long-running task: use a durable workflow with saved state.