Savine Documentation

Built-in Tools Reference ​

The Tool Gateway intercepts all agent execution requests. An agent never executes code or makes network calls directly. It issues a TOOL_CALL intent, and the Tool Gateway executes the function inside a secure, ephemeral gVisor sandbox.

This centralized approach guarantees:

  1. Security: Zero network escapes.
  2. Observability: Every tool input/output is logged.
  3. Metering: Infinite loops are caught by the platform before incurring massive costs.

Searches the web using DuckDuckGo.

  • Parameters: query (string, required), max_results (number, default 10).
  • Returns: JSON array of results with title, snippet, and url.
  • Security: Requires Medium security level or above.
  • Limitations: Returns instant answer snippets, does not perform deep web crawling or scraping behind paywalls.

http_request ​

Makes HTTP requests to external APIs.

  • Parameters: url (string, required), method (GET/POST/PUT/DELETE, default GET), headers (object, optional), body (string, optional).
  • Returns: Status code, headers, and body payload.
  • Security: Requires High security level. Will only resolve domains matching the agent's allowlist if explicitly configured in agent.json.

python_exec ​

Executes arbitrary Python code in an isolated environment.

  • Parameters: code (string, required), timeout (seconds, default 30).
  • Returns: { "stdout": "...", "stderr": "...", "return": 0 }
  • Security: No filesystem access by default. No network outbound access unless explicitly enabled.
  • Environment: Standard library is available. Pre-installed packages include pandas, numpy, and requests.

sql_query ​

Connects to a database and runs a query.

  • Parameters: query (string, required), connection_ref (string, required variable name).
  • Returns: JSON array of row objects.
  • Security: The database connection string must be stored as a secure environment variable (e.g., savine config set DB_URL="..."). Execute is strictly read-only unless allow_mutations is true in agent.json config.

file_read ​

Reads content from the agent's local, ephemeral workspace directory.

  • Parameters: path (string, relative to /agent-workspace).
  • Returns: Raw string content of the file.
  • Security: Traversal blocks in place (../). Sandbox filesystem is completely destroyed after task execution.

Queries an agent's long-term persistent memory store (if memory_type is set to persistent).

  • Parameters: query (string, required), top_k (number, default 5).
  • Returns: JSON array of memory nodes with semantic similarity scores.

send_email ​

Dispatches an email.

  • Parameters: to (string), subject (string), body (string), from_ref (string, env var reference).
  • Security: Requires valid SMTP configuration set via platform environment variables.

Adding Custom Tools ​

If the built-in tools are insufficient, you can mount an HTTP endpoint as a custom tool schema. See the Custom Tools Walkthrough for OpenAPI/Swagger ingestion guides.