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.

Built-in tools are divided into two main categories:

1. Execution Tools: Tools like fs.*, web.*, and cmd.run that agents use to perform their tasks. (Documented on this page)
2. Management Tools: Tools like aegis.agent.* and aegis.workflow.* used for platform administration and generative authoring. See the Management Tools reference for more details.

Inner-Loop Judge Optimization (skip_judge)

When an agent manifest enables spec.execution.tool_validation, the orchestrator may run a semantic judge before the tool call is dispatched. The judge evaluates the proposed tool use and arguments, not the output of a completed tool run. This adds latency, but it can stop unsafe or incorrect actions before they reach a side effect boundary.

For read-only tools the judge often adds latency without meaningful safety value - 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 inner-loop judge for those specific tools.

The judge only applies to inner-loop tool calls routed through the orchestrator's tool invocation path. It is not the same as outer-loop iteration validation, and it is not part of direct SEAL authentication or policy enforcement.

The canonical explanation of this control is in Tool-Call Judging.

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.

Argument Validation

Before any tool call is dispatched — on both the inner-loop path and the external SEAL path — the orchestrator validates that all required parameters are present and non-null. If validation fails the call is rejected immediately with an InvalidArguments error; no execution target is allocated and no judge is invoked.

External SEAL callers (POST /v1/seal/invoke) receive a standard MCP JSON-RPC error response:

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32602,
    "message": "Invalid tool arguments: required field 'manifest_yaml' is missing or null for tool 'aegis.agent.create'",
    "data": null
  }
}

The full HTTP status-to-error-code mapping for /v1/seal/invoke is:

Required parameters by tool:

Tools with no required parameters (e.g. aegis.agent.list, aegis.tools.list, aegis.system.info, aegis.runtime.list) accept any object including {}. aegis.runtime.list accepts an optional language string to filter results by language name (e.g. "python", "go"). aegis.tools.search accepts an optional query string but has no required fields. aegis.agent.search and aegis.workflow.search require a query string.

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 subcommand_allowlist policy and the node's builtin_dispatchers.cmd resource ceilings.

Parameters:

• command (string, required): The base shell command to execute (e.g., "cargo", "git", "npm").
• args (array of strings, optional): Positional arguments passed to the command (e.g., ["build"], ["status"]).

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.

Subcommand Policy:

Every cmd.run call is validated against the subcommand_allowlist. This allowlist ensures that agents can only execute approved base commands and specific subcommands (the first positional argument).

# Manifest Example
tools:
  - name: cmd
    executor: "builtin:cmd"
    config:
      subcommand_allowlist:
        git: [clone, add, commit, push, status]
        cargo: [build, test, fmt, clippy]

A call like cmd.run(command="cargo", args=["build"]) is permitted, while cmd.run(command="cargo", args=["publish"]) would be rejected with SubcommandNotAllowed.

Errors:

• ToolNotAllowed: The cmd tool is not in the agent's spec.tools list.
• CommandNotAllowed: The base command is not present in the subcommand_allowlist.
• SubcommandNotAllowed: The first positional argument is not in the allowed list for that base command.
• OutputSizeLimitExceeded: The combined stdout and stderr exceeded the max_output_bytes limit (default 512 KB).
• ExecTimeoutCeilingExceeded: The execution exceeded the timeout_ceiling_secs.