> ## Documentation Index
> Fetch the complete documentation index at: https://agno-v2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`](https://agno-v2.mintlify.site/tools/toolkits/local/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.

```python cookbook/12_context/13_workspace.py theme={null}
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`](https://agno-v2.mintlify.site/context-providers/providers/filesystem) | 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](https://agno-v2.mintlify.site/tools/toolkits/local/workspace) 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](https://agno-v2.mintlify.site/tools/toolkits/local/workspace.md)**
>
> The underlying read/write toolkit

> **[Cookbook Example](https://github.com/agno-agi/agno/blob/main/cookbook/12_context/13_workspace.py)**
>
> Project-aware workspace example


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.