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.

1from pathlib import Path
2from kern.agent import Agent
3from kern.context.workspace import WorkspaceContextProvider
4from kern.models.openai import OpenAIResponses
5
6project = WorkspaceContextProvider(
7    id="kern",
8    name="Kern Project",
9    root=Path("/path/to/repo"),
10    model=OpenAIResponses(id="gpt-5.4-mini"),
11)
12
13agent = Agent(
14    model=OpenAIResponses(id="gpt-5.4"),
15    tools=project.get_tools(),
16    instructions=project.instructions(),
17    markdown=True,
18)
19
20await 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`	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 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

wrench

Workspace Toolkit

The underlying read/write toolkit

book

Cookbook Example

Project-aware workspace example