Agency

Agency is the capacity to choose and carry out actions in an environment. Context and memory supply information to a model; agency connects the model's decisions to operations such as reading a file, querying a database, or editing a document. A model can generate a request for any of these operations, but application code must execute the request for the operation to happen.

The connection has three parts: a decision, its execution, and an observation of the result. The model chooses a search query, code runs the search, and the returned passages become input to a later call. The software around the model, often called a runtime or harness, connects these parts. It determines which requests the model can make, which requests actually run, and what the model learns about the outcome.

Three design questions

1. What decisions can the model express? The application supplies a vocabulary of operations and the information needed to choose among them. A named search function lets the model specify a query. A code-execution tool lets the model describe a computation as a program. The available forms determine how precisely and flexibly the model can request work.
2. What executes those decisions? A request needs an implementation: a function, an interpreter, or a service. The application must recognize the request, check its arguments, and route it to that implementation. The implementation and the resources it can reach determine what the operation can do.
3. What observation returns to the model? The next call needs evidence of what happened: source passages, a saved revision, or an error. A request to perform an action is not evidence that the action succeeded. The returned information must let the model decide whether to continue, revise the request, or stop.

Tool calling

Tool calling is the common way to make this connection. A tool definition gives the model an operation's name, a description of its purpose, and a schema specifying its arguments. For example, searchSourcesaccepts a query string and returns source passages. The model can request that operation with a query such as “latest company filing.” A handler is the function that receives those arguments and runs the search.

A tool registry connects each definition to its handler and argument validator. The application supplies the definitions to the model, then uses the registry to dispatch a returned request. The example below uses application interfaces; a provider adapter translates between these values and the model provider's message format. The observation retains the original call, including its identifier, so a later response can associate the result with the right request.

const decision = await callModel({
  messages,
  tools: registry.definitions(),
})

if (decision.kind === "tool") {
  const call = decision.toolCall
  const handler = registry.get(call.name)
  if (!handler) throw new Error("Unknown tool")

  const args = handler.parse(call.arguments)
  const result = await handler.run(args)

  observations.push({ call, result })
  // Include the request and its result when constructing the next call.
}

A tool's arguments determine how precisely the model can specify an action. An edit needs a document identifier and new text; an edit to a shared document may also need expectedVersion. If the model read revision 12 and another writer has since saved revision 13, the handler can reject the stale edit. That extra argument addresses a specific problem: the document can change between the model reading it and the application applying the model's decision.

Code execution

Named tools work well for operations with known inputs and outputs. Some tasks need combinations that would be cumbersome to describe as individual calls. To compare monthly totals in two CSV files, a model can write a short program that reads both files, groups their rows, and calculates the differences. An execution tool runs the program and returns the result. Loops, conditions, and transformations happen inside that execution, without a separate model call for each step. Tool calling still carries the request; the program is one of its arguments.

A shell extends the same idea to installed commands and pipelines: the model can search files, run a test suite, or invoke a command-line client. What those commands can do depends on the environment's files, libraries, network access, and credentials. A shell with a database client can query a data service even when the registry has no dedicated query tool. A sandbox can restrict those resources and operations. The full set of possible effects depends on both the tool and its environment.

Loading skills

An action can also change what the next model call knows. In the Memory chapter, a skill catalog let the model choose a relevant procedure. A file-reading tool completes that mechanism: the model requests a SKILL.md file, code reads it, and the instructions enter the next context. Loading a research skill can guide later searches without adding a new search implementation. The instructions can guide reasoning and responses within the next call. Steps that read files, run scripts, or change external state still need execution tools.

Tool discovery with MCP

A registry can start with functions defined in the application. As the system connects to more services, each integration otherwise needs its own code for describing operations, sending requests, and receiving results. Model Context Protocol (MCP) provides a shared protocol for these exchanges. An MCP server exposes tool descriptions and handles requests; the application acts as a client. The server's implementation can evolve independently while the application uses the same protocol to discover and call its tools.

Discovery and execution remain separate. The application obtains tool definitions from a server and selects which descriptions to include in the model's context. When the model requests one of those tools, the application checks the request and routes it to the server, then returns the result to a later call. A large catalog may need search or selective loading for the same reason a skill catalog does: descriptions occupy context. MCP supplies a common connection; the application still selects the definitions the model sees and routes its requests to the corresponding server.

Execution records

A useful tool result describes what the operation established. A search returns passages and source identifiers; an edit returns the saved revision; a test run returns findings and an exit status. The next call can interpret that evidence and choose a response. The result also needs to distinguish intermediate states: a service accepting a background job does not mean the job has finished. Source identifiers and job identifiers help connect each observation to the operation that produced it.

Sometimes the outcome is unknown. A service can start a data-processing job and then fail to return a response before a timeout. Repeating the request blindly may start the same analysis twice. An idempotency key identifies one logical action across attempts; a service that supports it can recognize the retry and return the existing job instead of creating another. The protection comes from the service's handling of the key, not from merely recording a key beside the request.

An action record connects the model's request, execution attempts, and observed results. For a data-processing job, the record can retain the input files, requested computation, idempotency key, returned job identifier, and output location. The application can use that record to investigate a failure or recover after interruption. It can also select the relevant outcome for the next context, so the model reasons from what happened instead of treating its own request as proof of success.

Agency connects a model decision to an operation and brings the result back as an observation. Repeating that connection lets the next decision depend on what the previous action revealed. The next chapter builds the tool-calling agent loop from these parts, then examines other ways to arrange model calls and computation into larger reasoning structures.