StateBackend

StateBackend

Bases: BackendProtocol

Backend that stores files in agent state (ephemeral).

Uses LangGraph's state management and checkpointing. Files persist within a conversation thread but not across threads. State is automatically checkpointed after each agent step.

Special handling: Since LangGraph state must be updated via Command objects (not direct mutation), operations return Command objects instead of None. This is indicated by the uses_state=True flag.

METHOD	DESCRIPTION
__init__	Initialize StateBackend with runtime.
ls_info	List files and directories in the specified directory (non-recursive).
read	Read file content with line numbers.
write	Create a new file with content.
edit	Edit a file by replacing string occurrences.
grep_raw	Search for a literal text pattern in files.
glob_info	Get FileInfo for files matching glob pattern.
upload_files	Upload multiple files to state.
download_files	Download multiple files from state.
als_info	Async version of ls_info.
aread	Async version of read.
agrep_raw	Async version of grep_raw.
aglob_info	Async version of glob_info.
awrite	Async version of write.
aedit	Async version of edit.
aupload_files	Async version of upload_files.
adownload_files	Async version of download_files.

__init__

__init__(runtime: ToolRuntime)

Initialize StateBackend with runtime.

ls_info

ls_info(path: str) -> list[FileInfo]

List files and directories in the specified directory (non-recursive).

PARAMETER	DESCRIPTION
path	Absolute path to directory. TYPE: str

RETURNS	DESCRIPTION
list[FileInfo]	List of FileInfo-like dicts for files and directories directly in the directory.
list[FileInfo]	Directories have a trailing / in their path and is_dir=True.

read

read(file_path: str, offset: int = 0, limit: int = 2000) -> str

Read file content with line numbers.

PARAMETER	DESCRIPTION
file_path	Absolute file path. TYPE: str
offset	Line offset to start reading from (0-indexed). TYPE: int DEFAULT: 0
limit	Maximum number of lines to read. TYPE: int DEFAULT: 2000

RETURNS	DESCRIPTION
str	Formatted file content with line numbers, or error message.

write

write(file_path: str, content: str) -> WriteResult

Create a new file with content. Returns WriteResult with files_update to update LangGraph state.

edit

edit(
    file_path: str, old_string: str, new_string: str, replace_all: bool = False
) -> EditResult

Edit a file by replacing string occurrences. Returns EditResult with files_update and occurrences.

grep_raw

grep_raw(
    pattern: str, path: str = "/", glob: str | None = None
) -> list[GrepMatch] | str

Search for a literal text pattern in files.

PARAMETER	DESCRIPTION
pattern	Literal string to search for (NOT regex). Performs exact substring matching within file content. Example: "TODO" matches any line containing "TODO" TYPE: str
path	Optional directory path to search in. If None, searches in current working directory. Example: "/workspace/src" TYPE: str | None DEFAULT: None
glob	Optional glob pattern to filter which FILES to search. Filters by filename/path, not content. Supports standard glob wildcards: - * matches any characters in filename - ** matches any directories recursively - ? matches single character - [abc] matches one character from set TYPE: str | None DEFAULT: None

Examples:

• "*.py" - only search Python files
• "**/*.txt" - search all .txt files recursively
• "src/**/*.js" - search JS files under src/
• "test[0-9].txt" - search test0.txt, test1.txt, etc.

RETURNS	DESCRIPTION
list[GrepMatch] | str	On success: list[GrepMatch] with structured results containing: - path: Absolute file path - line: Line number (1-indexed) - text: Full line content containing the match
list[GrepMatch] | str	On error: str with error message (e.g., invalid path, permission denied)

glob_info

glob_info(pattern: str, path: str = '/') -> list[FileInfo]

Get FileInfo for files matching glob pattern.

upload_files

upload_files(files: list[tuple[str, bytes]]) -> list[FileUploadResponse]

Upload multiple files to state.

PARAMETER	DESCRIPTION
files	List of (path, content) tuples to upload TYPE: list[tuple[str, bytes]]

RETURNS	DESCRIPTION
list[FileUploadResponse]	List of FileUploadResponse objects, one per input file

download_files

download_files(paths: list[str]) -> list[FileDownloadResponse]

Download multiple files from state.

PARAMETER	DESCRIPTION
paths	List of file paths to download TYPE: list[str]

RETURNS	DESCRIPTION
list[FileDownloadResponse]	List of FileDownloadResponse objects, one per input path

als_info async

als_info(path: str) -> list[FileInfo]

Async version of ls_info.

aread async

aread(file_path: str, offset: int = 0, limit: int = 2000) -> str

Async version of read.

agrep_raw async

agrep_raw(
    pattern: str, path: str | None = None, glob: str | None = None
) -> list[GrepMatch] | str

Async version of grep_raw.

aglob_info async

aglob_info(pattern: str, path: str = '/') -> list[FileInfo]

Async version of glob_info.

awrite async

awrite(file_path: str, content: str) -> WriteResult

Async version of write.

aedit async

aedit(
    file_path: str, old_string: str, new_string: str, replace_all: bool = False
) -> EditResult

Async version of edit.

aupload_files async

aupload_files(files: list[tuple[str, bytes]]) -> list[FileUploadResponse]

Async version of upload_files.

adownload_files async

adownload_files(paths: list[str]) -> list[FileDownloadResponse]

Async version of download_files.