Chapter 8: Empowering agents with code execution

Introduction

The introduction contrasts predefined tools with giving an agent an environment where its LLM can write and run code.

• Predefined tools versus code execution: Distinguish an agent that selects from registered tools from one whose LLM can write and run code in an execution environment. Explain that predefined tools are predictable and easy to control but have limitations for complex real-world problems.
  Why it matters: This distinction explains why the chapter considers code execution alongside registered tools.

Key terms: predefined tool approaches, execution environment, code execution, give an agent a computer

8.1 Giving agents a computer

This section explains why predefined tool calls constrain agents and introduces direct code execution as an alternative.

• From Tool Calls to Code: Explain why relying on predefined tool calls can limit an agent, and describe the proposed alternative of having the LLM generate and execute code directly.
  Why it matters: This is the motivation for giving the agent a code-execution capability.

Key terms: tool-calling approach, predefined functions, action space, generate and execute code

8.1.1 Limitations of the predefined-tool approach

This section explains why an agent limited to predefined tools can get stuck, incur repeated LLM calls and context costs, and struggle with a growing tool list.

• Predefined Tool Action Limits: Explain why an agent using predefined tools cannot handle an operation absent from its developer-defined list, and contrast that limit with giving the LLM an environment in which it can write and execute code.
  Why it matters: This is why an unexpected but simple request can defeat an otherwise capable agent.
• Repeated Calls and Context Costs: Explain how step-by-step tool execution can add latency on a task involving many files, and how passing whole tool results into context can add cost and slow the agent when only a small part is needed.
  Why it matters: The cost of a task can come from repeated decisions and unnecessary text in context, not just from executing its tools.
• Tool Proliferation Tradeoffs: Explain why registering more tools, including tools supplied through MCP servers, enlarges prompts and can make accurate tool selection harder.
  Why it matters: Adding capabilities through tools has a prompt-size and selection-accuracy tradeoff.

Key terms: predefined-tool approach, action space, execution environment, LLM call, tool execution, observation, context, latency, tool proliferation, tool definitions

8.1.2 What code execution brings

This section explains how code execution lets an agent complete tasks more efficiently and handle more complex work through control flow, intermediate data, and tool composition.

• Whole-task code execution: Explain how having an LLM write a program can replace a sequence of individual tool calls, including the section’s file-link filtering example.
  Why it matters: Writing a program can reduce repeated LLM decisions and avoid adding a separate tool for every small operation.
• Conditional and repeated actions: Describe how control flow lets code branch, repeat actions, and handle exceptions, using the shopping-cart example to show several conditions handled in one code block.
  Why it matters: Control flow lets one program make the repeated and conditional choices a task requires.
• Reusable intermediate results: Explain how variables let code retain, transform, and pass intermediate results between steps instead of returning the full context to the LLM for each decision.
  Why it matters: Keeping intermediate data in a program makes sequences of transformations more efficient.
• New functionality through composition: Explain how code can combine existing functions and tools into a more complex tool, as in the company-analysis example.
  Why it matters: Composition lets an agent build a solution when its individual available tools are not enough.
• Progression of code-based actions: Distinguish the four approaches in the section’s comparison: independent tool calls, code with control flow, code that connects tool outputs, and creation of new tools by code.
  Why it matters: The comparison helps you describe precisely what each added use of code contributes.

Key terms: code-execution capability, LLM call, code execution, predefined-tool approach, control flow, conditionals, loops, business logic, data flow, intermediate results

8.1.3 The effectiveness of code-based actions

This section uses CodeAct research to show that expressing agent actions as code can improve task success and reduce LLM interactions compared with JSON or text actions.

• CodeAct performance comparison: Describe what the CodeAct study compared and what it found about success rates and interactions.
  Why it matters: The comparison gives a concrete reason to consider code as an agent action format.
• Code as action procedure: Explain how expressing actions as code addresses difficulties seen with JSON and text actions and can reduce LLM calls.
  Why it matters: It explains why the action format can change an agent’s effectiveness, not just the appearance of its tool calls.
• Existing programming language leverage: Explain why the approach can be used without additional training and why the section favors Python without requiring it.
  Why it matters: It distinguishes a practical implementation choice from a fundamental requirement of code-based actions.

Key terms: CodeAct, JSON format, text format, code format, interactions, intermediate results, variables, conditionals, loops, plan and procedure

8.2 Connecting code environments

This section introduces the upcoming work of adding code execution to the agent using a sandbox and testing the integration.

8.2.1 Why sandboxes are necessary

This section explains why LLM-generated code should run in a sandbox, what protections isolation provides, and why the book uses E2B.

• Risks of generated code: Explain why an agent should not run LLM-generated code without isolation, using examples of accidental harm and deliberate misuse.
  Why it matters: Recognizing these risks explains why code execution needs safeguards.
• Sandbox protection layers: Describe how isolating code execution in a sandbox reduces security, resource, and recovery risks.
  Why it matters: Isolation limits the damage that a faulty or harmful code run can cause to the host.
• Sandbox options and persistence: Distinguish directly managed Docker containers from cloud sandbox services, and explain why the book chooses E2B.
  Why it matters: The choice of E2B supports simple sandbox access without losing results between code executions.

Key terms: LLM-generated code, prompt injection, sandbox, isolation, resource management, recoverability, Docker containers, cloud sandbox services, E2B, state persistence

8.2.2 Introduction to E2B

This section introduces the E2B sandbox workflow and explains how to inspect results, configure execution, reuse state, and recover from code errors.

• E2B Access Setup: State the prerequisites for using E2B: sign up, generate an API key, add it to the project’s .env file, and install the E2B package.
  Why it matters: These steps prepare a project to use the sandbox.
• Basic Sandbox Execution Flow: Trace the basic E2B flow from creating an isolated cloud Python sandbox through executing code, checking its execution object, and terminating the sandbox.
  Why it matters: This is the basic lifecycle for running code in E2B.
• Execution Output Properties: Distinguish printed output, evaluated last-expression results, and execution errors in the object returned by run_code().
  Why it matters: Inspecting the right property lets an agent tell output, a computed result, and a failure apart.
• Sandbox Runtime Configuration: Describe how to set or extend a sandbox timeout and how to pass environment variables into sandbox code.
  Why it matters: These settings control how long the sandbox is available and what values its code can access.
• Persistent Sandbox State: Explain what persists between run_code() calls in the same sandbox and why that helps multistep agent work.
  Why it matters: An agent can build on earlier calculations without recreating its variables and functions at every step.
• Execution Error Recovery: Explain where execution errors are reported, why the sandbox remains usable afterward, and how an agent can use the error message to retry.
  Why it matters: An agent can treat a code failure as feedback for another attempt rather than as the end of the task.

Key terms: E2B, API key, .env file, E2B package, Sandbox.create(), run_code(), execution object, kill(), execution.logs.stdout, execution.results

8.2.3 Connecting the sandbox to the agent

This section connects an E2B sandbox to the Agent so code execution is available through a tool, shares execution state, and cleans up reliably.

• Code execution configuration: Explain how setting code_execution="e2b" enables code execution without changing how developers register tools.
  Why it matters: A single Agent option makes the capability available without separate tool registration.
• Shared sandbox execution state: Describe where the sandbox is stored and why tools access it through ExecutionContext.
  Why it matters: Sharing the sandbox lets successive tool calls work with state established earlier in the same run.
• Sandbox lifecycle cleanup: Trace when Agent.run() creates and cleans up the sandbox, including when execution fails.
  Why it matters: Reliable cleanup prevents sandbox resources from leaking after a failed run.
• Python tool result handling: Explain how execute_python uses the sandbox and why it returns JSON results.
  Why it matters: Separating the kinds of output helps the LLM interpret what happened when code ran.

Key terms: code_execution, e2b, _setup_tools(), execute_python, ExecutionContext, code_env, sandbox, Optional, run(), sandbox life cycle

8.2.4 Testing the code-execution agent

A Fibonacci test shows how a code-execution agent combines the LLM’s choice of code with Python’s precise calculation.

• Reasoning and calculation roles: Explain how the agent answers the 100th-Fibonacci-number request by writing and executing Python code, rather than relying on the LLM to produce the large number directly.
  Why it matters: The example shows why giving an agent code execution can make its answers more accurate.

Key terms: code-execution agent, LLM’s reasoning ability, precise calculation capability

8.3 Porting tools to sandboxes

This introduction identifies a limitation of sandboxed code execution: code in the sandbox cannot directly call tools built earlier in the book.

• Sandbox access to existing tools: Explain that although the agent can write and execute Python code, that code cannot directly call the tools built in previous chapters from inside the sandbox.
  Why it matters: This limitation explains why making existing tools available in the sandbox is worth addressing.

Key terms: sandbox, tools, code execution

8.3.1 The need for tool portability

This section uses a historical Wikipedia query to show why sandbox-executed code can be more efficient than repeated agent tool calls and why local tools need a way to run in an isolated sandbox.

• Historical revision requirement: Explain why the Wikipedia task needs a custom revision-querying tool rather than a regular web search or the current Wikipedia API.
  Why it matters: The historical-version requirement explains why an ordinary lookup is insufficient in the example.
• Sandbox iteration advantage: Contrast repeated agent tool calls with a sandbox-executed program for the 31 daily queries.
  Why it matters: Moving repetition into code avoids making the LLM coordinate every daily query.
• Local result processing: Explain how processing retrieved pages inside the sandbox reduces what enters the agent’s context.
  Why it matters: Returning just the needed counts keeps lengthy source pages out of the model’s context.
• Local and sandbox separation: Describe the portability problem posed by a locally defined Python function and a remote E2B sandbox.
  Why it matters: The environment boundary explains why an existing local tool cannot simply be assumed to run in the sandbox.

Key terms: last version from June 2023, Wikipedia’s revision API, regular agent tool, sandbox-executed code, LLM call, agent’s context, small extracted outputs, token use, E2B sandbox, isolated environment

8.3.2 Extending FunctionTool

This section narrows sandbox tool support to suitable FunctionTools and explains the flag, validation, and source-code extraction needed to make them available there.

• Sandbox tool portability limits: Explain why this implementation ports only pure-function FunctionTools that do not need ExecutionContext, rather than every kind of tool.
  Why it matters: These limits tell you which existing tools are candidates for sandbox execution.
• Sandbox eligibility flag: Describe what the sandbox_executable flag means and how FunctionTool rejects an incompatible context parameter.
  Why it matters: The flag makes sandbox eligibility explicit, while early validation catches an invalid tool configuration.
• Sandbox source code preparation: Explain how get_source_code() prepares a FunctionTool for sandbox registration and why it removes the @tool decorator.
  Why it matters: The sandbox needs the function definition without a decorator that exists only in the agent framework.

Key terms: FunctionTool, ExecutionContext, pure functions, sandbox, sandbox_executable, context parameter, get_source_code(), inspect.getsource(), @tool decorator, sandbox registration

8.3.3 Implementing the Wikipedia revision tool

This section shows how a Wikipedia revision tool retrieves historical page versions and why its function must be self-contained to run in a sandbox.

• Historical Wikipedia revision queries: Explain how the Wikipedia API can retrieve a page version from before a specified time using action=query, prop=revisions, and rvstart.
  Why it matters: The timestamp lets the tool answer questions about what a page said before a particular date.
• Self-contained sandbox tool function: Explain why the Wikipedia revision tool is marked sandbox_executable=True and written without a context parameter, with imports inside the function and a structured return value.
  Why it matters: These choices let generated code use the tool independently inside the sandbox.

Key terms: action=query, prop=revisions, rvstart, sandbox_executable=True, pure function, context parameter, structured data

8.3.4 Handling sandbox tools in the Agent

This section shows how the Agent separates sandbox-executable tools, makes their functions available in the sandbox, and tells the LLM how to call them.

• Sandbox tool classification: Explain how the Agent separates sandbox-executable tools from regular tools and detects an incompatible configuration.
  Why it matters: Separating these tools ensures the Agent handles them as sandbox code and catches configuration mistakes early.
• Sandbox function registration: Describe when sandbox-executable tool code is run and what that makes possible for LLM-generated code.
  Why it matters: Defining the functions in the sandbox gives generated code something it can call.
• Sandbox tool prompt guidance: Explain what the system prompt tells the LLM about sandbox functions and why.
  Why it matters: The prompt lets the LLM discover the available sandbox functions and use them in the right way.

Key terms: Agent, _setup_tools(), sandbox_executable, code execution, sandbox, source code, LLM-generated code, system prompt, tool signatures, descriptions

8.3.5 Practical testing

Shows how a sandbox-executable tool processes a Wikipedia example and explains when code-based tool use is worth its overhead.

• Sandboxed Wikipedia processing: Trace the example from registering get_wikipedia_revisions as a sandbox_executable tool to the agent generating loop-based Python code. Explain what stays in the sandbox and what returns to the agent’s context.
  Why it matters: Keeping page contents in the sandbox lets the agent work with the resulting counts rather than the full intermediate data.
• Code execution suitability: Distinguish tasks that benefit from code-based tool use from tasks better served by regular tool calls, using the section’s data-processing, workflow, feedback, and overhead criteria.
  Why it matters: Choosing the approach by workload avoids sending unnecessary intermediate data to the LLM or paying code-execution overhead for trivial work.

Key terms: sandbox_executable, get_wikipedia_revisions, sandbox, context, aggregations or summaries, dependent tool calls, intermediate data, code execution overhead, regular tool calling

8.4 Workspace: Using filesystems and the CLI

This introduction explains why agents need a workspace in addition to code execution.

• Need for an agent workspace: Explain why code execution alone is not a complete working environment for an agent, using the developer activities named in the section.
  Why it matters: It clarifies what an agent needs beyond the ability to run code.

Key terms: code execution, workspace, terminal, intermediate results

8.4.1 The workspace concept

This section defines an agent workspace, explains how agents can create file-handling actions on demand, and shows how E2B exposes CLI and filesystem access.

• Workspace environment components: Explain that a workspace combines code execution, a filesystem, and a CLI, allowing an agent to manage files and use command-line tools rather than only execute code.
  Why it matters: The workspace is the environment in which the agent can work with files as well as run code.
• On-demand workspace actions: Explain how an agent can generate code or use existing CLI commands for a needed file task instead of relying on a separately implemented tool for each action.
  Why it matters: This reduces the need to build a dedicated tool for every action the agent might need.
• E2B workspace access methods: Describe how the E2B sandbox exposes workspace capabilities: commands.run() executes CLI commands and returns results, while files.write() uploads local files for the agent to use.
  Why it matters: These two interfaces make command execution and file transfer concrete in the sandbox.

Key terms: workspace, code execution, filesystem, CLI, list_files, os.listdir(), grep, E2B sandbox, commands.run(), files.write()

8.4.2 Implementing workspace tools

This section explains how to give an agent CLI and file-transfer access to an E2B sandbox and how those workspace tools are registered.

• Sandbox CLI command execution: Explain how bash_tool runs CLI commands in the E2B sandbox and presents their results to the LLM.
  Why it matters: The agent needs readable command results to make use of its sandbox CLI access.
• Local file upload behavior: Describe how upload_file transfers a local file into the sandbox, including its default destination and invalid-path response.
  Why it matters: Uploading files lets the agent work with local data inside its sandbox.
• Workspace tool registration: Distinguish the automatic registration of execute_python from the explicit registration of workspace tools in the Agent class.
  Why it matters: This distinction explains why enabling E2B code execution does not by itself add every workspace capability.

Key terms: bash_tool, commands.run(), _format_command_result, stdout, stderr, exit codes, upload_file, local file path, destination path, /home/user/

8.4.3 Practical example: Analyzing an Excel file

This section shows how an agent uses sandboxed workspace tools to analyze an Excel sales file and contrasts that approach with local filesystem tools.

• Workspace Excel analysis workflow: Describe how the agent is equipped to upload and analyze an Excel file, then compare total sales for two cities.
  Why it matters: This connects the workspace setup to the steps needed to answer a question about spreadsheet data.
• Sandbox workspace advantages: Explain why the sandboxed workspace is more flexible and safer than the earlier local filesystem-tool approach for this example.
  Why it matters: It explains why the example uses a sandboxed workspace rather than adding another local file-reading tool.

Key terms: code_execution="e2b", execute_python, bash_tool, upload_file, pandas, filesystem tools, sandbox, pip install, state

8.5 Agent skills

This section explains why a growing tool catalog strains an agent’s prompt and introduces agent skills as a way to reduce that burden.

• Tool proliferation and prompt costs: Explain why connecting MCP servers can make tool use less efficient even though MCP makes tools easier to reuse.
  Why it matters: More available tools are not automatically better if their definitions burden every request.
• Agent skills high-level purpose: Describe the two problems agent skills are introduced to address and the approaches named here, without detailing their implementation.
  Why it matters: This identifies what agent skills are meant to improve before their mechanics are introduced.

Key terms: MCP server, tool definitions, prompt, tokens, tool proliferation, agent skills, progressively disclosing tool information, tool portability, folder-based structure

8.5.1 The agent skills concept

This section explains how agent skills package instructions and optional code in portable folders while giving the LLM brief descriptions before it needs the full documentation.

• On-demand skill documentation: Explain how an agent first receives brief information about available skills and reads a skill’s full instructions only when it decides that skill is needed.
  Why it matters: It explains how an agent can discover available skills without receiving every instruction up front.
• Portable skill folder structure: Describe what belongs in a skill folder and why that arrangement makes skills portable.
  Why it matters: Keeping a skill’s description and any supporting code together makes it easier to reuse.

Key terms: agent skills, YAML front matter, SKILL.md, skill folder, scripts, tool-portability problem

8.5.2 Progressive tool-information disclosure

This section explains how agent skills reveal tool information only as needed, reducing the tokens used for most requests.

• Three levels of skill disclosure: Trace how an agent moves from a short skill list in the system prompt to a needed skill’s SKILL.md, and then, only if necessary, to additional documents and scripts.
  Why it matters: The agent can discover available skills without loading every skill’s full instructions up front.
• Token savings from selective loading: Explain why loading skill details only when needed uses fewer tokens than placing all tool definitions in every prompt, using the section’s comparison.
  Why it matters: It explains why progressive disclosure becomes valuable when an agent has many possible tools but uses only a few per request.

Key terms: progressively disclosing tool information, skill list, SKILL.md, bash_tool, traditional approach, agent skills approach, tokens

8.5.3 Implementation

This section shows how to discover agent skills, summarize them in the system prompt, and place their full files in the agent’s sandbox.

• Skill metadata and full files: Explain the division between the skill information shown to the agent in its prompt and the full skill directories kept in its filesystem.
  Why it matters: The agent can see which skills are available without putting their full contents in the prompt.
• Skill loading and discovery: Describe how skill information is obtained from SKILL.md files and how skills are found within a directory.
  Why it matters: Loading and discovery turn skill folders into the information the agent uses to list and upload skills.
• Agent sandbox skill integration: Trace how the Agent uses skills_path to include skills in its prompt and upload their files during a run.
  Why it matters: This connects the agent’s advertised skills to files available in its execution environment.

Key terms: system prompt, skill list, skill directories, SkillInfo, SKILL.md, YAML front matter, parse_frontmatter, load_skill, discover_skills, skills_path

8.5.4 Practical example: PDF merge skill

This section shows how a PDF-merge skill is registered with an agent and used only when a request calls for it.

• Skill packaging and selective loading: Describe how the pdf-merge skill is made available to the agent and what its SKILL.md provides. Explain why the agent reads the detailed instructions only when the skill is needed.
  Why it matters: The agent can identify a relevant skill without reading its full instructions on every request.
• PDF merge execution flow: Trace what the agent does when asked to merge three PDF files, from choosing the skill through confirming the output.
  Why it matters: This sequence shows how a skill's instructions become a checked result, rather than a response based on the skill description alone.

Key terms: pdf-merge, SKILL.md, pypdf, skill folder path, one-line description, skill list, system prompt, bash_tool, execute_python, merged.pdf

8.5.5 Hierarchical tool structure

This section organizes agent tools into three layers and explains how a fixed interface provides broad capabilities without putting every tool definition in the prompt.

• Three Layers of Agent Tools: Describe the roles of core tools, installable agent skills, and generated tools, including how the core tools provide access to the other layers.
  Why it matters: The three layers explain how a few tools the LLM can call directly support skills and newly written code.
• Workspace Offloading of Tool Definitions: Explain why the hierarchy keeps detailed tool definitions in the workspace rather than placing them all in the prompt.
  Why it matters: Moving details to the workspace lets the agent retain access to functionality without filling its context with information it does not currently need.

Key terms: core tools, installable tools, agent skills, generated tools, bash_tool, execute_python, hierarchical structure, workspace, tool definitions, tool summaries

8.6 Summary

The chapter summary explains how code execution expands agent actions, why it needs a sandbox and workspace, and how layered tools keep prompts lean.