subagents

State key holding the most recent SummarizationEvent.

State key holding the id that names the offload history file.

Configurable key used by task-tool callers to request dynamic response format.

Base spec for general-purpose subagent (caller adds model, tools, middleware).

Append text to a system message.

Create a runnable agent from a raw SubAgent spec.

This is the shared entrypoint for the create_agent path used by raw subagent specs. Pre-compiled CompiledSubAgent runnables are already created by the caller and are handled separately by SubAgentMiddleware.

Middleware for providing filesystem and optional execution tools to an agent.

This middleware adds filesystem tools to the agent: ls, read_file, write_file, edit_file, glob, and grep.

Files can be stored using any backend that implements the BackendProtocol.

If the backend implements SandboxBackendProtocol, an execute tool is also added for running shell commands. Its results carry ExecuteArtifact metadata on ToolMessage.artifact.

This middleware also automatically evicts large tool results to the file system when they exceed a token threshold, preventing context window saturation.

A single access rule for filesystem operations.

Represents a summarization event.

Specification for a declarative subagent.

By default the subagent is isolated: it receives only the delegated task description. Setting mode="fork" makes it continue the parent's conversation instead.

When using create_deep_agent, subagents automatically receive a default middleware stack before any custom middleware specified in this spec.

A pre-compiled agent spec.

When the subagent completes, the parent reads the returned state: if structured_response is non-None, it is JSON-serialized and used as the ToolMessage content; otherwise, the last non-empty AIMessage text is used.

Input schema for the task tool.

Middleware for providing subagents to an agent via a task tool.

This middleware adds a task tool to the agent that can be used to invoke subagents.

Subagents are useful for handling complex tasks that require multiple steps, or tasks that require a lot of context to resolve.

A chief benefit of subagents is that they can handle multi-step tasks, and then return a clean, concise response to the main agent.

Subagents are also great for different domains of expertise that require a narrower subset of tools and focus.

Protocol for pluggable memory backends (single, unified).

Backends can store files in different locations (state, filesystem, database, etc.) and provide a uniform interface for file operations.

File operations (grep, glob, ls, read, etc.) live on this base protocol rather than only on SandboxBackendProtocol because not every backend has a shell. StateBackend and StoreBackend store files in in-memory state or a remote store with no process to exec into, so they implement grep/glob in pure Python and have no execute at all. Even on shell-capable backends, the tools are not just convenience wrappers around execute: they enforce literal-only matching (not regex), return structured GrepResult/GlobResult objects, support max_count truncation, and pass through filesystem permission rules — none of which raw execute + shell grep/find provides. Agent-facing prompt guidance should therefore recommend these tools only when they are actually registered, and never assume a shell is available as a fallback.

All file data is represented as dicts with the following structure:

{
    "content": str,  # Text content (utf-8) or base64-encoded binary
    "encoding": str,  # "utf-8" for text, "base64" for binary data
    "created_at": str,  # ISO format timestamp
    "modified_at": str,  # ISO format timestamp
}