Workspace

Give an agent read-only, project-aware access to a local working directory.

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

import asyncio
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,
)

asyncio.run(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.
mode	ContextMode	default	Both default and agent expose query_<id>. tools exposes the read-only Workspace toolkit.
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

Resources

Workspace Toolkit

The underlying read/write toolkit

Cookbook Example

Project-aware workspace example