> ## 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

> 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`](/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}
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`](/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. |
| `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](/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

<CardGroup cols={2}>
  <Card title="Workspace Toolkit" icon="wrench" href="/tools/toolkits/local/workspace">
    The underlying read/write toolkit
  </Card>

  <Card title="Cookbook Example" icon="book" href="https://github.com/agno-agi/agno/blob/main/cookbook/12_context/13_workspace.py">
    Project-aware workspace example
  </Card>
</CardGroup>