# Workspace (/context-providers/providers/workspace)



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.

Create a virtual environment using [SDK setup](/sdk/setup), then install the model dependency and set your key:

```bash
uv pip install -U agno openai
export OPENAI_API_KEY="your-openai-api-key"
```

Save as `workspace_context.py` beside the project files you want to inspect, then run `python workspace_context.py`.

```python title="workspace_context.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="project",
    name="Local Project",
    root=Path(__file__).resolve().parent,
    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("Summarize this directory. Cite the files you read."))
```

## Workspace vs Filesystem provider [#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 using the same default exclusions for discovery; explicitly named excluded files remain readable. |

## Configuration [#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. `&#123;root&#125;` 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 blocked for discovery and explicit reads. 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.                                                     |

`allow_paths` accepts literal paths under the root that override exclusions for those paths. Allowing a directory exposes ordinary descendants, but exclusions still apply to components below it: allowing `build` permits `build/index.html` while still blocking `build/.env`. It is not a list of glob patterns. Use it for a specific dependency directory you intend to expose.

## Tools Exposed [#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 [#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 [#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>