Workspace

Wrap a project directory and expose a single query_<id> tool. The tool routes through a read-only sub-agent with the Workspace toolkit scoped to root: list files, search content, and read files with line numbers. Common dependency directories, build outputs, caches, and virtualenvs are excluded by default.

cookbook/12_context/13_workspace.py

from pathlib import Path
from agno.agent import Agent
from agno.context.workspace import WorkspaceContextProvider
from agno.models.openai import OpenAIResponses

project = WorkspaceContextProvider(
    id="agno",
    name="Agno Project",
    root=Path("/path/to/repo"),
    model=OpenAIResponses(id="gpt-5.4-mini"),
)

agent = Agent(
    model=OpenAIResponses(id="gpt-5.4"),
    tools=project.get_tools(),
    instructions=project.instructions(),
    markdown=True,
)

await agent.aprint_response("Where is the Workspace toolkit implemented? Cite the files you read.")

Workspace vs Filesystem provider

Provider	Use for
`WorkspaceContextProvider`	Repository roots and active project trees. Excludes build/dependency noise by default.
`FilesystemContextProvider`	A scoped directory of documents with no project-aware exclusions.

Configuration

Parameter	Type	Default	Description
`root`	`Optional[str\|Path]`	`cwd`	Directory the workspace is rooted at.
`id`	`str`	`"workspace"`	Tool becomes `query_<id>`.
`name`	`str`	`"Workspace"`	Display name used in instructions.
`model`	`Model`	`None`	Model for the read-only sub-agent.
`instructions`	`Optional[str]`	defaults	Override the sub-agent’s instructions. `{root}` is substituted.
`exclude_patterns`	`Optional[List[str]]`	noise dirs	Patterns skipped when listing/searching. Pass `[]` to disable.
`max_file_lines`	`int`	`100000`	Maximum lines the sub-agent reads per file.
`max_file_length`	`int`	`10000000`	Maximum file size (bytes) the sub-agent reads.

Tools Exposed

Tool	Description
`query_<id>`	Ask a question about the project. The sub-agent lists, searches, and reads files to answer. Read-only.

The provider is read-only by design. No save, edit, delete, move, or shell tools are exposed. For write access to a working directory, use the Workspace toolkit directly with confirmation gates.

Example queries

Query	What happens
”Where is authentication handled in this repo?”	Sub-agent searches and reads relevant files
”Summarize the structure of the cookbook directory”	Lists the directory tree, summarizes
”What does the workflow module export?”	Reads `__init__.py` and reports

Get Started

Basics

Advanced

Production

Providers

Other

Additional Resources

Workspace vs Filesystem provider

Configuration

Tools Exposed

Example queries

Resources

Workspace Toolkit

Cookbook Example

​Workspace vs Filesystem provider

​Configuration

​Tools Exposed

​Example queries

​Resources

Workspace Toolkit

Cookbook Example

Workspace vs Filesystem provider

Configuration

Tools Exposed

Example queries

Resources