Tool system
This page is for contributors. For what tools do from a user's point of view, see Tools. Tools extend the agent's capabilities, allowing it to interact with the filesystem, web, me
This page is for contributors. For what tools do from a user's point of view, see Tools.
Tools extend the agent's capabilities, allowing it to interact with the filesystem, web, memory, social platforms, and more. Each tool is a function owned by a named capability in the centralized registry.
Architecture
Suzent uses pydantic-ai for its agent framework. Registry classes provide metadata and typed functions. Selected functions are bundled into Pydantic AI capabilities; tools that need per-request state receive it through RunContext[AgentDeps].
Agent
├── capabilities
│ ├── filesystem: [read_file, write_file, ...]
│ ├── shell: [run_command, start_command, ...]
│ └── web: [web_search, webpage_fetch, ...]
├── toolsets: [MCPServerStdio(...), ...] ← MCP servers
│ └── _deferred_toolset (per_run_step=True) ← AI-activated tools
└── deps_type: AgentDeps ← shared contextThe configuration API exposes the same capability catalog to the frontend, including capability descriptions and each tool's display name, description, runtime function name, and approval requirement. Capability headers toggle a whole category, while every tool remains independently selectable.
Deferred (AI-Activated) Tools
Not all tools need to be loaded at session start. The agent can call tool_search mid-conversation to activate additional tools on demand. Activated tools are injected into the agent's toolset before each LLM step via a @agent.toolset with per_run_step=True, and persist for the rest of the session.
Tools opt out of deferral by setting deferrable = False on their class (e.g. MemorySearchTool, SkillTool, SocialMessageTool — always-on internals that the agent shouldn't re-activate).
Denied tools
Unchecking a tool only demotes it to the search pool. A chat's denied_tools config (registry class names, written by the picker's deny button) removes a tool outright. create_agent drops denied names from the equipped list and the deferred pool, and adds ToolDenyCapability (tools/capability.py), whose prepare_tools hook filters every function tool definition each step. pydantic-ai wraps ToolSearch outside prepare_tools, so a definition removed there is not offered, not executable and not in the search corpus, and the hook sees MCP tools as well as ours.
The same hook also honours always_deny in the session tool_approval_policy, which previously had no effect on an equipped tool that needs no approval. Names are matched by class name, runtime name and legacy shell aliases. Builtins are never denied. Sub-agents inherit their parent's denied_tools, and the list is persisted on the child chat so a resumed turn cannot regain the tool. An ACP sub-agent brings its own tools, which this list cannot reach, so _run_subagent refuses to start one while the parent has any denied tools. The list is per chat: the frontend keeps it out of the settings a new chat inherits.
AgentDeps
All per-session context lives in a single AgentDeps dataclass, injected into every tool that needs it:
@dataclass
class AgentDeps:
chat_id: str # Current conversation ID
user_id: str # Current user
sandbox_enabled: bool # Whether sandbox mode is active
workspace_root: str # Root path for file operations
path_resolver: PathResolver # Resolves relative paths safely
memory_manager: MemoryManager # Long-term memory system
channel_manager: Any # Social messaging channels
skill_manager: Any # User-defined skills
a2ui_queue: asyncio.Queue # Canvas UI event queue (render_ui)
base_tool_names: frozenset # User-selected tools for this session (used by tool_search)
# ... plus HITL fields (see Human-in-the-Loop doc)Tools that are stateless (e.g. web_search, webpage_fetch) omit RunContext entirely — they're plain functions with no dependency injection.
Available Tools
Web & Search
| Tool | Function | Context | Description |
|---|---|---|---|
| WebSearchTool | web_search | — | Web search via SearXNG or DuckDuckGo |
| WebpageTool | webpage_fetch | — | Fetch and extract webpage content as markdown |
| BrowsingTool | browser_action | — | Control a headless browser (Playwright) |
| DesktopTool | desktop | — | Optional. Host-only agent-desktop CLI. Registered by the desktop plugin, which is off by default. Reads are allowed; mutations ask. |
Filesystem
| Tool | Function | Context | HITL | Description |
|---|---|---|---|---|
| ReadFileTool | read_file | PathResolver | — | Read file contents (text, PDF, DOCX, images via OCR) |
| WriteFileTool | write_file | PathResolver | Yes | Create or overwrite files |
| EditFileTool | edit_file | PathResolver | Yes | Find-and-replace text in files |
| GlobTool | glob_search | PathResolver | — | Find files matching glob patterns |
| GrepTool | grep_search | PathResolver | — | Search file contents with regex |
Shell
| Tool | Function | Context | HITL | Description |
|---|---|---|---|---|
| RunCommandTool | run_command | Sandbox config | Yes | Return quick output or yield a running process ID after 10 seconds |
| StartCommandTool | start_command | Sandbox config | Yes | Start a long-running background command |
| CheckCommandTool | check_command | Process registry | Yes | Read incremental output and command status |
| StopCommandTool | stop_command | Process registry | Yes | Stop a background command and clean up resources |
Planning & Memory
| Tool | Function | Context | Description |
|---|---|---|---|
| PlanningTool | planning_update | chat_id | Create and manage structured task plans |
| MemorySearchTool | memory_search | MemoryManager | Semantic search over long-term memory |
| MemoryUpdateTool | memory_update | MemoryManager | Remember, correct or retract a fact the user stated |
Canvas & UI
| Tool | Function | Context | Description |
|---|---|---|---|
| RenderUITool | render_ui | a2ui_queue | Render interactive UI surfaces (tables, forms, cards, buttons) in the sidebar canvas or inline in chat |
See Canvas (A2UI) for full documentation.
Social & Output
| Tool | Function | Context | HITL | Description |
|---|---|---|---|---|
| SendFileTool | send_file | ChannelManager, PathResolver | — | Builtin. Deliver workspace files to the user in the current conversation |
| SocialMessageTool | social_message | ChannelManager | Yes (sends only) | Send messages to Telegram, Discord, Slack, Feishu |
| SpeakTool | speak | — | — | Text-to-speech output |
| SkillTool | skill_execute | SkillManager | — | Execute user-defined skills |
Agent & Meta
| Tool | Function | Context | Description |
|---|---|---|---|
| ToolSearchTool | tool_search | AgentDeps | Discover and activate additional tools mid-conversation |
| AgentTool | agent | chat_id | Start a bounded sub-agent in the foreground or background |
| AgentListTool | agent_list | chat_id | List local project sessions and paired remote Suzent agents |
| AgentReadTool | agent_read | chat_id | Read one accessible agent's bounded visible transcript |
| AgentSendTool | agent_send | chat_id | Persist a message and wake another agent-backed session |
| AgentStopTool | agent_stop | chat_id | Stop one accessible active agent |
The lifecycle tools are intentionally separate instead of using one action-heavy
management schema. agent_list defaults to active tasks and caps results at 20;
recent results cap at 50. Agent IDs are stable chat IDs. Access is inferred from
the current project for local sessions; paired devices use stable peer:
addresses. Callers do not pass parent chat or project identifiers.
agent_read applies an internal transcript budget and returns the newest visible
messages when a conversation is large. agent_send has only two parameters
(agent_id and message): it writes to the durable agent inbox, returns after
the message is queued, and a background dispatcher wakes the target session.
Paired Suzent backends appear as peer:<peer_id> agents and use the same tool
schemas; their messages remain durable while the peer is temporarily offline.
Selecting AgentTool automatically equips these lifecycle operations as its
management dependencies. Sub-agents themselves cannot use the lifecycle tools,
which prevents unbounded recursive orchestration.
See Agent Communication for inbox delivery, idempotency, and cross-device boundaries.
HITL = Requires human approval before execution. See Human-in-the-Loop.
Tool Details
web_search
Performs web searches using SearXNG (self-hosted, privacy-focused) with automatic fallback to DuckDuckGo.
Parameters:
query(required): Search query stringcategories: Search category —general,news,images,videosmax_results: Max results to return (default 10, max 20)time_range: Time filter —day,week,month,yearpage: Pagination (default 1)
Configuration: Set SEARXNG_BASE_URL in .env for SearXNG. Without it, falls back to DuckDuckGo.
Shell capability
Executes shell commands in a secure environment. Runs inside an isolated Docker container when sandbox mode is enabled, or on the host when disabled.
Parameters:
content(required): Shell command to executerun_command: run bounded work synchronously with an optional timeoutstart_command: start a long-running command and return a command IDcheck_command: read incremental output and check completionstop_command: terminate the command and its process tree
Background commands continue after the agent finishes a turn. While the backend
is running, command completion or failure sends a durable inbox message to the
owning agent: an active turn receives the result in place, and an idle agent
starts a new background turn. Results include the exit code and the last 8,000
characters of output. check_command remains available for retained output.
A completed result already read by check_command, or a command explicitly
stopped with stop_command or the sidebar, does not trigger another wakeup.
The Background tasks sidebar combines sub-agents and Shell commands. It shows live status, recent command output, exit codes, and stop controls. Command tracking and recent sidebar history are in memory; they are not restored after a backend restart. Once queued, completion messages use the existing durable agent inbox.
All four operations belong to the Shell capability and can be enabled separately.
Selecting a capability header in the frontend toggles every tool in that capability.
Existing ShellTool, BashTool, or ProcessTool selections are expanded to all
four operations during migration.
Storage paths (available in both modes):
/persistence— Private storage, persists across sessions (current chat only)/shared— Shared storage, accessible by all chats
Permission controlled — execution is evaluated by the active permission mode, shell policy, and persisted rules. It may run, be denied, or show backend-provided approval actions.
read_file
Reads file content with format-aware extraction.
Supported formats:
- Text files:
.txt,.py,.js,.json,.md,.csv, etc. - Documents:
.pdf,.docx,.xlsx,.pptx(converted to markdown) - Images:
.jpg,.png(OCR text extraction)
Parameters:
file_path(required): Path to the fileoffset: Line number to start from (0-indexed)limit: Number of lines to read
write_file / edit_file
File creation and modification tools.
write_file: Creates or overwrites a file. Creates parent directories automatically.edit_file: Find-and-replace within a file. Supportsreplace_allfor bulk replacements.
Both are permission controlled. Default mode asks before writes, Auto mode allows deterministic low-risk edits or escalates unresolved cases, and Full Access removes ordinary approval prompts while preserving hard path and deny checks.
glob_search / grep_search
Filesystem search tools.
glob_search(pattern, path): Find files matching glob patterns (e.g.**/*.py)grep_search(pattern, path, include, case_insensitive, context_lines): Regex search through file contents
planning_update
Creates and manages structured plans for multi-step tasks. Plans are stored in the database and visualized in the frontend sidebar.
Parameters:
action:update(create/overwrite a plan) oradvance(mark a phase complete)goal: High-level goal description (required forupdate)phases: List of phases, each withid,title,capabilities(required forupdate)current_phase_id: Phase being completed (required foradvance)next_phase_id: Phase to start next (required foradvance)
action='update' — Creates a new plan or overwrites the existing one. Resets all progress: first phase becomes in_progress, all others pending.
action='advance' — Marks current_phase_id as completed and next_phase_id as in_progress. If next_phase_id skips phases, all intermediate phases are auto-completed.
memory_search / memory_update
Long-term memory tools. See Memory for the full memory architecture.
memory_search(query, limit): Semantic similarity search over archived memoriesmemory_update(fact, retract, retract_as, kind, outcome, source, category, horizon): Record what the user states directly.factwrites a candidate for the dream;retracttakes a claim back (retract_as=wrongalso adds it to the rejected list,outdatedonly hides it); both together are a correction.kind=experienceneedsoutcomeandkind=worldneedssource. See Memory Architecture.
send_file
Hands up to 10 finished files to the user in the current conversation. Each path goes
through the chat's PathResolver, so only files the conversation may read can be sent.
In a social conversation (deps.social_context has platform and target_id) every file
is sent with ChannelManager.send_file, dispatched onto the channel's event loop, with the
caption on the first file only. Each channel driver owns its platform's differences: the
tool checks the driver's max_file_bytes before uploading and reports a driver with
supports_files = False (WeChat today) as unsupported, and the driver's send_file does
the upload itself (Slack threads, Feishu image and file keys, and so on). A new channel
needs no change to the tool.
Elsewhere nothing is sent. saved_paths holds virtual paths (to_virtual_path, falling
back to the host path), because the desktop and phone load them back through the
resolver. It is what the desktop chat renders
(images and video in the gallery, other files as SentFileCard) and what the mobile chat
load turns into media ids. The result also carries delivered_paths and, for channels,
failed with a reason per file. It is builtin and needs no approval because it never
reaches anyone but the person already in the conversation; sending elsewhere is
social_message.
social_message
Send messages to social platforms or list available contacts.
- Listing contacts (
list_contacts=True) does not require approval - Sending messages requires approval
See Social Messaging for platform setup.
browser_action
Control your existing Chrome/Edge tabs and logins through the Suzent browser extension, or use a managed Playwright browser with optional persistent profiles. Direct CDP attachment remains an advanced option. All modes use the native tool; MCP is optional. See Browser for extension installation, pairing, tab selection, and snapshot pagination.
Commands: tabs, select_tab, open, snapshot, click, dblclick, hover, fill, type, scroll, back, forward, reload, refresh, press, click_coords
speak
Text-to-speech output. Converts text to audio and plays it.
skill_execute
Execute user-defined skills. See Skills.
tool_search
Meta-tool always available to the agent. Lets it discover and activate additional tools mid-conversation without restarting the session.
Parameters:
query(optional): Exact tool key to activate — either the class name (e.g."WebSearchTool") or the pydantic-ai runtime name (e.g."web_search"). Omit to list tool status.
List mode (no query): Returns three sections:
ENABLED (user-selected)— tools the user turned on in ConfigViewACTIVE (AI-activated this session)— tools the agent has already activatedAVAILABLE TO ACTIVATE— deferrable tools not yet active
Activation mode (with query): Activates the matched tool immediately; the tool becomes callable in the agent's next step. Emits a tool_activated SSE event so the frontend can update ConfigView in real time.
Tools with deferrable = False (MemorySearchTool, SkillTool, SocialMessageTool) are excluded from the catalog and cannot be activated this way — they are always-on internals.
Configuring Tools
Default Tools
The default selection is default_tools in src/suzent/config/model.py.
Custom Tool Selection
Specify tools in the agent configuration:
config = {
"model": "gemini/gemini-2.5-pro",
"tools": [
"WebSearchTool",
"PlanningTool",
"ReadFileTool",
"RunCommandTool",
"MemorySearchTool",
]
}Tool names use the legacy class-name format (e.g. "WebSearchTool") for backward compatibility with existing configs.
Creating Custom Tools
To add a new tool:
- Create the tool function in
src/suzent/tools/tool_functions.py:
from pydantic_ai import RunContext
from suzent.core.agent_deps import AgentDeps
def my_tool(
ctx: RunContext[AgentDeps], # omit if stateless
param1: str,
param2: int = 10,
) -> str:
"""Short description of what this tool does.
Args:
param1: Description of param1.
param2: Description of param2.
"""
# Your logic here
return f"Result: {param1}"- Register it in the
TOOL_FUNCTIONSdict at the bottom oftool_functions.py:
TOOL_FUNCTIONS = {
# ... existing tools ...
"MyTool": my_tool,
}- Add to defaults (optional) in
config.pyif it should be enabled by default.
Guidelines
- Use Google-style docstrings — pydantic-ai generates the tool schema from type hints + docstring
- Use
RunContext[AgentDeps]as the first parameter only if the tool needs session context - Async tools (
async def) are preferred for I/O operations - If the tool is dangerous (writes, executes, sends), add HITL approval — see Human-in-the-Loop
- Return informative error messages as strings (don't raise exceptions)
- Set
deferrable = Falseon the tool class if it should never appear in thetool_searchcatalog (e.g. always-on internals like MemorySearchTool)
Structured results
A tool that returns a list the caller may want to loop over (paths, matches, search hits, tasks) should also return it as typed metadata, so calling code does not have to parse the message:
- Declare the metadata as a
TypedDictand subclassToolResultwithmetadata: <YourMetadata>, then annotateforward()with the subclass. pydantic-ai turns that annotation into the tool's return schema. Decorate theTypedDictwith@with_config(ConfigDict(extra="allow", use_attribute_docstrings=True)): withoutextra="allow"pydantic silently drops any key the type does not declare. - When the message already shows the same data, list the key in
model_excluded_metadata. The model then reads it once, in the message; the stored result keeps it, and the context estimate leaves it out. - Bound the list. The message is capped by
output_char_limit, metadata is not, and it is stored with the chat. - Text written by someone other than the user (mail, web pages) reaches the model fenced in the message. Keep its structured copy in an excluded key and pass strings through
sanitize_untrusted_text.
glob_search, grep_search, read_file, web_search, webpage_fetch, memory_search, session_search, list_tasks, mail_search and mail_read follow this pattern.
Code mode
Code mode (src/suzent/core/code_mode.py, off unless code_mode is set in
the user's preferences) adds pydantic-ai-harness's CodeMode capability.
The model gets one run_code tool whose Python snippet calls tools as async
functions inside the Monty sandbox (pydantic-monty, pinned exactly).
- Which tools.
CODE_MODE_TOOLSlists the tools a snippet may call. Only read-only tools that never ask for approval belong there. Suzent approves a call by ending the run withDeferredToolRequestsand resuming it, which a running snippet cannot do, and the shell would make the sandbox pointless. Every other tool stays a direct call. Tools with typed results (see Structured results) are what make snippets useful, since the code reads fields instead of parsing text. - Live display. Nested calls go through
ToolManager.handle_call, so capability hooks fire, but they emit no events on the run stream.CodeModeEventsCapability.wrap_tool_executesees each one (its id is<run_code id>__<n>) and puts acode_mode_callcustom event and the usualTOOL_CALL_START/ARGS/END/RESULTevents ondeps.ui_event_queue.streaming.pydrains that queue on every loop tick and right after each stream event, so a snippet's calls reach the client before itsrun_coderesult. The frontend indents parts that carryparentToolCallId. - Reload. The draft accumulator keeps
parentToolCallIdon streamed parts. When a display is rebuilt from history,_rebuild_display_messagesexpands eachrun_codereturn'stool_calls/tool_returnsmetadata into the same nested parts. - Timeout. The stream waits
RUN_CODE_STREAM_TIMEOUT_SECONDSfor arun_coderesult, since a snippet may call several slow tools in turn. - Cost. The harness puts the signatures of the sandboxed tools, including their return types, in the instructions on every request.
Tool Registry
The tool registry (src/suzent/tools/registry.py) provides programmatic access:
from suzent.tools.registry import get_tool_function, list_available_tools
# Get a specific tool function
fn = get_tool_function("WebSearchTool")
# List all available tool names
names = list_available_tools()Permission engine
User-facing behavior is described in Permissions & approvals. The rest of this section covers the API and event contract.
APIs
GET /permissions?chat_id={chat_id}
POST /permissions/rules
DELETE /permissions/rules/{rule_id}?destination=session|global&chat_id={chat_id}
GET /chats/{chat_id}/permission-state
GET /chats/{chat_id}/permission-mode
PUT /chats/{chat_id}/permission-modeResume a suspended call through /chat or /chat/send:
{
"chat_id": "chat-id",
"message": "",
"resume_approvals": [
{
"request_id": "tool-call-id",
"tool_call_id": "tool-call-id",
"action_id": "allow_session",
"feedback": "Optional user guidance"
}
]
}Legacy binary approval payloads remain accepted as allow-once or deny-only decisions. They cannot create remembered policies.
Streaming Contract
Permission provenance is streamed separately from the tool result so the UI can show how a deferred action was authorized. Full Access is labeled as allowed without review; it must not be presented as an Auto classifier approval.
{
"name": "tool_permission_decision",
"value": {
"toolCallId": "tool-call-id",
"behavior": "ask",
"source": "auto_classifier",
"reason": "This command changes workspace files.",
"reasonCode": "auto_classifier_ask",
"risk": "medium",
"confidence": "high",
"riskCategories": ["filesystem"],
"reviewerModel": "openai/gpt-4.1-mini"
}
}The tool_approval_request custom event contains:
{
"approvalId": "tool-call-id",
"toolCallId": "tool-call-id",
"toolName": "run_command",
"args": {"content": "npm test"},
"decision": {
"behavior": "ask",
"reason": "Git commands require approval",
"reasonCode": "shell_policy_ask",
"risk": "high",
"actions": []
}
}The frontend renders decision.actions in order, including feedback inputs and rule explanations declared by the backend. Pending contracts are persisted in _pending_approvals so the same prompt can be restored after refresh.
After a user acts on an approval prompt, Suzent streams
tool_permission_resolution with the selected action and scope. Older clients
can ignore provenance events and still rely on tool_approval_request.
The classifier writes reason in the language of the user's latest request
(falling back to the delegated task's language, then English) and keeps tool
names and arguments verbatim. What the agent sees for a refused call:
- A policy or headless deny returns
ToolDenied("The tool call was denied: <reason>"). - A user deny of a call whose persisted decision has
reasonCodeauto_classifier_high_riskorshell_policy_high_riskreturns the flagged reason, any typed feedback, and an instruction not to retry the same action. - Any other user deny returns the feedback, or pydantic-ai's default message.
Audit Trail
Permission evaluations and user resolutions are appended to permission-audit.jsonl in the user configuration directory. Entries include chat, run, tool-call, mode, decision, reason, user action, and classifier or matched-rule metadata.
Arguments are bounded and recursively sanitized. Sensitive keys and common inline credential forms are redacted. The append is offloaded to a worker thread so audit logging never blocks the streaming event loop.
Adding Approval to a Tool
Set requires_approval = True on the tool class:
class MyTool(BaseTool):
tool_name = "my_tool"
requires_approval = TrueThe registry wraps it as a pydantic-ai deferred tool. Add deterministic read-only or mode-specific behavior to PermissionEngine when needed; otherwise the default decision asks before execution.
Keep execution-time validation inside the tool. Permission approval answers whether an operation may proceed, while the tool must still validate paths, symlinks, arguments, and current external state immediately before execution.
Headless Runs
Cron, heartbeat, goals, dream jobs, and subagents use Auto mode with a non-interactive profile. Nothing approves every tool call wholesale. A headless action that cannot be classified safely is denied.
Browser extension development
Browser-side source lives in extensions/browser/. The current installer clones
the repository, so no separate extension packaging or build step is required.
The optional download endpoint creates a ZIP from that directory. A standalone
Python wheel alone does not include the extension source. Python browser code lives
in src/suzent/tools/browser/, with the extension bridge in its extension/ package.
No Node runtime is required for users. Load the source directory unpacked for development,
then reload the extension after changes. English and Chinese extension strings are
in _locales/. Run uv run pytest tests/tools/test_browser_extension.py for the
real bundled-Chromium extension regression, using an isolated test profile.