Built-in Tools

The AEGIS Orchestrator provides a set of native, built-in tools out of the box. These tools are implemented internally for high performance, deep security integration, and specialized infrastructure abstraction. Built-in tools bypass the overhead of sidecar MCP servers.

Inner-Loop Judge Optimization (skip_judge)

When an agent manifest enables spec.execution.tool_validation, the orchestrator runs a semantic judge after each tool call to validate its output before letting the agent proceed. This adds latency but catches unsafe or incorrect tool results early.

For read-only tools the judge adds latency without safety benefit — the file contents or search results are deterministic and carry no write-side risk. Operators can set skip_judge: true on individual tools in spec.builtin_dispatchers[].capabilities or spec.mcp_servers[].capabilities in the Node Configuration to bypass the judge for those specific tools.

Compiled-in defaults:

These defaults can be overridden per-tool in the node configuration. skip_judge is an operator-level flag — agents cannot influence it.

---

Filesystem Abstraction Layer (FSAL) Tools

The fs.* tools interact directly with the AegisFSAL (File System Abstraction Layer), meaning they work transparently across SeaweedFS, Local Host storage, and OpenDAL backends. They automatically respect the agent's volume ownership and FilesystemPolicy.

fs.read

Reads the contents of a file.

Parameters:

• path (string, required): Absolute or relative POSIX path of the file to read.

Returns: The file contents as a string.

Errors: PathOutsideBoundary if path is outside the path_allowlist; NOT_FOUND if the file does not exist; PERMISSION_DENIED if the SecurityContext denies access.

fs.write

Writes content to a file, creating it if it doesn't exist or overwriting it if it does.

Parameters:

• path (string, required): Absolute or relative POSIX path of the file to write to.
• content (string, required): The string content to write.

Returns: Confirmation string with the path written.

Errors: PathOutsideBoundary if path is outside the allowlist; PERMISSION_DENIED if the SecurityContext denies fs.write; storage backend error if the volume is full.

fs.list

Lists the contents of a directory.

Parameters:

• path (string, required): Absolute or relative POSIX path of the directory to list. Defaults to / if not provided.

Returns: A newline-separated list of entry names in the directory, annotated with a trailing / for subdirectories.

Errors: NOT_FOUND if the directory does not exist; PathOutsideBoundary if outside the allowlist.

fs.create_dir

Creates a new directory along with any necessary parent directories.

Parameters:

• path (string, required): Absolute or relative POSIX path of the directory to create.

Returns: Confirmation string with the path created.

Errors: PathOutsideBoundary if path is outside the allowlist; ALREADY_EXISTS if the directory already exists (treated as success).

fs.delete

Deletes a file or directory.

Parameters:

• path (string, required): Absolute or relative POSIX path of the file or directory to delete.
• recursive (boolean, optional): Set to true to delete a directory and all its contents recursively. Default is false.

Returns: Confirmation string with the path deleted.

Errors: NOT_FOUND if the path does not exist; PathOutsideBoundary if outside the allowlist; PERMISSION_DENIED if fs.delete is in the SecurityContext deny_list; error if recursive is false and the path is a non-empty directory.

fs.edit

Performs an exact string replacement in a file. The target content must match exactly one occurrence in the file.

Parameters:

• path (string, required): Absolute or relative POSIX path of the file to edit.
• target_content (string, required): Exact string content to find and replace.
• replacement_content (string, required): New string content to insert.

Returns: Confirmation string with the path edited and a summary of the change.

Errors: NOT_FOUND if the file does not exist; error if target_content matches zero or more than one location in the file (must be unique); PathOutsideBoundary if outside the allowlist.

fs.multi_edit

Performs multiple sequential string replacements in a file. Provides a more atomic way to apply several edits at once.

Parameters:

• path (string, required): Absolute or relative POSIX path of the file to edit.
• edits (array of objects, required): Array of edits to apply sequentially. Each object must have:
  • target_content (string, required)
  • replacement_content (string, required)

Returns: Confirmation string with the number of replacements applied.

Errors: Same as fs.edit — any edit that fails (zero or multiple matches) aborts the entire operation and leaves the file unchanged.

fs.grep

Recursively searches for a regex pattern within files in a given directory. Uses the AegisFSAL to traverse the directory structure.

Parameters:

• pattern (string, required): Regex pattern to search for.
• path (string, required): Directory path to start the recursive search from.

Returns: A formatted list of matches, each showing the file path, line number, and the matching line.

Errors: PathOutsideBoundary if outside the allowlist; error if the regex pattern is invalid.

fs.glob

Recursively matches files against a glob pattern.

Parameters:

• pattern (string, required): Glob pattern to match files (e.g., *.rs, src/**/*.ts).
• path (string, required): Directory path to start the recursive search from.

Returns: A newline-separated list of matching file paths relative to path.

Errors: PathOutsideBoundary if outside the allowlist; empty result (not an error) if no files match.

Web Tools

The web.* tools provide native HTTP request and web search capabilities, including HTML scraping and content extraction.

web.search

Performs an internet search query. Currently defaults to DuckDuckGo HTML scraping.

Parameters:

• query (string, required): The search query.
• max_results (integer, optional): Maximum number of results to return. Default is 10.

Returns: A formatted list of search results, each containing title, URL, and snippet text.

Errors: DomainNotAllowed if the SecurityContext's domain_allowlist does not permit the search engine domain; network error if the external request fails.

web.fetch

Fetches content from a URL, optionally converting HTML pages into clean Markdown.

Parameters:

• url (string, required): URL to fetch content from. Must start with http:// or https://.
• to_markdown (boolean, optional): Convert HTML to markdown. Default is true.
• follow_redirects (boolean, optional): Whether to follow HTTP redirects. Default is true.
• timeout_secs (integer, optional): Request timeout in seconds. Default is 30.

Returns: The response body as a string (Markdown if to_markdown is true and the response is HTML, otherwise raw text/JSON).

Errors: DomainNotAllowed if the URL domain is not in the SecurityContext allowlist; network or timeout error if the remote server is unreachable; error if the response status is 4xx/5xx.

Dispatch Protocol Tools

These tools map to the AEGIS Dispatch Protocol, meaning the orchestrator intercepts the tool call and fulfills it by injecting execution commands into the agent's isolation boundary (e.g., Docker container).

cmd.run

Executes a shell command within the agent's containerized workspace. Subject to the agent's SubcommandAllowlist policy.

Parameters:

• command (string, required): The shell command and arguments to execute.

Returns: An object containing stdout (string), stderr (string), and exit_code (integer). A non-zero exit_code is returned as a successful tool result — the agent's LLM receives all three fields and can interpret the failure.

Errors: ToolNotAllowed or SubcommandNotAllowed if the command or subcommand is not in the SecurityContext allowlist; timeout error if the command exceeds the execution wall-clock limit; OutputSizeLimitExceeded if stdout/stderr combined exceed the configured maximum.