Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.agno.com/llms.txt

Use this file to discover all available pages before exploring further.

Workspace is a local-machine toolkit scoped to a single root directory. Reads (read, list, search) run silently; destructive operations (write, edit, move, delete, shell) require human confirmation by default, which AgentOS renders as approval prompts in the run timeline.

​
Example

cookbook/91_tools/workspace_tools/basic_usage.py
from agno.agent import Agent
from agno.models.openai import OpenAIResponses
from agno.tools.workspace import Workspace

agent = Agent(
    model=OpenAIResponses(id="gpt-5.4"),
    tools=[
        Workspace(
            "/path/to/project",
            allowed=["read", "list", "search"],
            confirm=["write", "edit", "move", "delete", "shell"],
        )
    ],
    markdown=True,
)

agent.print_response("Read README.md, then write a 2-line summary to NOTES.md.")

​
Permission Model

allowed and confirm are mutually exclusive partitions of short aliases:
In listBehavior
allowedRuns silently.
confirmRequires user approval via HITL pause/resume.
neitherNot registered with the toolkit. The LLM never sees it.
bothRaises ValueError.
When both lists are None, reads auto-pass and writes require confirmation (the safe default). When only one is set, the other defaults to []. Use Workspace.ALL_TOOLS to register every tool.
AliasRegistered toolWhat it does
readread_fileRead a file (line-numbered).
listlist_filesList a directory (recursive option).
searchsearch_contentRecursive content grep.
writewrite_fileCreate or overwrite a file (atomic).
editedit_fileReplace a substring (with replace_all).
movemove_fileMove or rename a file.
deletedelete_fileDelete a file.
shellrun_commandRun a shell command in root.
This is a path-scoping boundary, not a process sandbox. Paths resolving outside root are rejected, but the agent can still read environment variables and make network calls via shell. For untrusted code execution, run the agent inside a real sandbox (container, VM, or Daytona).

​
Toolkit Params

ParameterTypeDefaultDescription
rootOptional[str|Path]cwdDirectory all operations are scoped to.
allowedOptional[List[str]]NoneAliases that run silently.
confirmOptional[List[str]]NoneAliases that require confirmation.
require_read_before_writeboolFalseBlock writes/edits/move/delete on existing files until read this session.
max_file_linesint100000Maximum lines read_file will load.
max_file_lengthint10000000Maximum file size (bytes) read_file will load.
exclude_patternsOptional[List[str]]noise dirsPatterns skipped by list_files/search_content. Pass [] to disable.
list_files and search_content skip common noise directories (.venv, .git, __pycache__, node_modules, etc.) by default.

​
Confirmation Flow

With aliases in confirm, the run pauses when the agent calls a gated tool. Resolve the requirement and continue the run: 
run_response = agent.run("Delete the old logs in /tmp/project")

while run_response.is_paused:
    for requirement in run_response.active_requirements:
        if requirement.needs_confirmation:
            requirement.confirm()  # or requirement.reject()
    run_response = agent.continue_run(
        run_id=run_response.run_id,
        requirements=run_response.requirements,
    )
See Workspace with confirmation for the full pause/resume example, and User Confirmation for the HITL pattern.

​
Developer Resources