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.

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

ProviderUse for
WorkspaceContextProviderRepository roots and active project trees. Excludes build/dependency noise by default.
FilesystemContextProviderA scoped directory of documents with no project-aware exclusions.

​
Configuration

ParameterTypeDefaultDescription
rootOptional[str|Path]cwdDirectory the workspace is rooted at.
idstr"workspace"Tool becomes query_<id>.
namestr"Workspace"Display name used in instructions.
modelModelNoneModel for the read-only sub-agent.
instructionsOptional[str]defaultsOverride the sub-agent’s instructions. {root} is substituted.
exclude_patternsOptional[List[str]]noise dirsPatterns skipped when listing/searching. Pass [] to disable.
max_file_linesint100000Maximum lines the sub-agent reads per file.
max_file_lengthint10000000Maximum file size (bytes) the sub-agent reads.

​
Tools Exposed

ToolDescription
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

QueryWhat 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