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.
Create a virtual environment using SDK setup, then install the model dependency and set your key:
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.
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
| Provider | Use for |
|---|---|
WorkspaceContextProvider | Repository roots and active project trees. Excludes build/dependency noise by default. |
FilesystemContextProvider | A scoped directory using the same default exclusions for discovery; explicitly named excluded files remain readable. |
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 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
| 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 |