Context Files API¶
Project context files (DEEP.md, AGENTS.md, CLAUDE.md, SOUL.md) are auto-discovered
and injected into the system prompt. Enable discovery via context_discovery=True
on create_deep_agent. See
Context Files for the conceptual overview.
ContextFile¶
pydantic_deep.features.context.ContextFile
dataclass
¶
ContextToolset¶
pydantic_deep.features.context.ContextToolset
¶
Bases: FunctionToolset[Any]
Toolset that injects project context files into agent system prompt.
Has no tools - only provides instructions via get_instructions().
Loads files from the run's workspace (ctx.workspace).
Works with both main agents and subagents.
__init__(*, context_files=None, context_discovery=False, is_subagent=False, max_chars=DEFAULT_MAX_CONTEXT_CHARS)
¶
Initialize the context toolset.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
context_files
|
list[str] | None
|
Explicit list of file paths to load. |
None
|
context_discovery
|
bool
|
Whether to auto-discover context files. |
False
|
is_subagent
|
bool
|
Whether this is for a subagent (applies filtering). |
False
|
max_chars
|
int
|
Max chars per file before truncation. |
DEFAULT_MAX_CONTEXT_CHARS
|
get_instructions(ctx)
async
¶
Load and format context files for system prompt injection.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ctx
|
RunContext[Any]
|
The run context, whose workspace the files are read from. |
required |
Returns:
| Type | Description |
|---|---|
list[InstructionPart] | None
|
Formatted context prompt, or None if no files found. |
discover_context_files¶
pydantic_deep.features.context.discover_context_files(workspace, search_path='/', filenames=None)
async
¶
Auto-discover context files at the workspace root.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
workspace
|
Workspace
|
Workspace to search in. |
required |
search_path
|
str
|
Root path to search (default: "/", the working directory). |
'/'
|
filenames
|
list[str] | None
|
Filenames to look for (default: DEFAULT_CONTEXT_FILENAMES). |
None
|
Returns:
| Type | Description |
|---|---|
list[str]
|
List of paths to found context files. |
load_context_files¶
pydantic_deep.features.context.load_context_files(workspace, paths)
async
¶
Load context files from the workspace.
Missing, empty and unreadable files are skipped.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
workspace
|
Workspace
|
Workspace to read files from. |
required |
paths
|
list[str]
|
List of file paths to load. |
required |
Returns:
| Type | Description |
|---|---|
list[ContextFile]
|
List of loaded context files. |
format_context_prompt¶
pydantic_deep.features.context.format_context_prompt(files, *, is_subagent=False, subagent_allowlist=SUBAGENT_CONTEXT_ALLOWLIST, max_chars=DEFAULT_MAX_CONTEXT_CHARS)
¶
Format context files for system prompt injection.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
files
|
list[ContextFile]
|
Loaded context files. |
required |
is_subagent
|
bool
|
Whether this is for a subagent (applies filtering). |
False
|
subagent_allowlist
|
frozenset[str]
|
Filenames allowed for subagents. |
SUBAGENT_CONTEXT_ALLOWLIST
|
max_chars
|
int
|
Max chars per file before truncation. |
DEFAULT_MAX_CONTEXT_CHARS
|
Returns:
| Type | Description |
|---|---|
str
|
Formatted system prompt section, or empty string if no files. |