AgentFiles¶
- class AgentFiles[source]¶
Bases:
ABCPersistent files owned by the authenticated agent.
Methods
delete(key, *, expected_revision)Delete a file from the current view, retaining its history.
get(key)Return the current file content and metadata.
list(*[, prefix, start_after, limit])List live file metadata in lexicographic key order.
put(key, data, *[, expected_revision])Create or update a file, preserving its previous revisions.
- abstract delete(key: str, *, expected_revision: int) None[source]¶
Delete a file from the current view, retaining its history.
- Parameters:
key (str) – File key within the agent’s scope.
expected_revision (int) – Must match the current live revision; missing or deleted files also cause a revision conflict.
- abstract get(key: str) File | None[source]¶
Return the current file content and metadata.
- Parameters:
key (str) – File key within the agent’s scope.
- Returns:
Content and metadata, or None if absent or deleted.
- Return type:
File | None
- abstract list(*, prefix: str = '', start_after: str = '', limit: int | None = None) tuple[list[FileMetadata], str][source]¶
List live file metadata in lexicographic key order.
- Parameters:
prefix (str (default: "")) – Include only keys starting with this prefix.
start_after (str (default: "")) – Exclusive key cursor; empty starts from the beginning.
limit (int | None (default: None)) – Maximum number of entries. None returns all matches; zero returns an empty page.
- Returns:
Metadata and the next cursor, which is empty when no more remain.
- Return type:
tuple[list[FileMetadata], str]
- abstract put(key: str, data: bytes, *, expected_revision: int | None = None) int[source]¶
Create or update a file, preserving its previous revisions.
- Parameters:
key (str) – Non-empty, non-whitespace file key, preserved unchanged.
data (bytes) – File content to store.
expected_revision (int | None (default: None)) – None means create-only and fails if a live file exists. Otherwise, the current live revision must match for the update to succeed.
- Returns:
The new revision ID.
- Return type:
int