Custom Tools

Tools extend what your agents can do — call external APIs, reference documentation, or run code in a secure sandbox. This guide covers each tool type, how to configure them, and best practices.

Tool Types

Cognova supports three types of custom tools:

Every agent also has access to built-in tools (tasks, memory, files, code execution, development sandbox) which are always available without configuration.

Built-in: Development Sandbox

The development sandbox gives your agent a persistent Linux environment for building, running, and previewing full applications — not just executing single code snippets. When a user asks "build me a React todo app," the agent can scaffold the project, install dependencies, start a dev server, and provide a live preview URL.

Unlike custom sandbox tools (covered below) which execute a single code snippet and destroy the sandbox, the development sandbox persists across tool calls within a conversation. The agent can write files, run commands, check output, and iterate — just like a developer would.

How It Works

1. sandbox_create — Initializes a persistent sandbox for the conversation
2. sandbox_write_file — Creates or overwrites files in the sandbox filesystem
3. sandbox_read_file — Reads file contents from the sandbox
4. sandbox_list_files — Lists directory contents
5. sandbox_exec — Runs shell commands (npm install, npm run dev, etc.)
6. sandbox_preview — Gets a public URL for a running dev server and validates it's healthy
7. sandbox_export — Saves the project to your knowledge base or generates a download link

Enabling the Sandbox

Enable the Sandbox toggle in your agent's built-in tools configuration (Agent Settings → Built-in Tools). Once enabled, the agent will automatically use the sandbox when asked to build or develop applications.

Live Preview

When the agent starts a dev server, it can call sandbox_preview to generate a public URL. This URL is:

• Automatically validated (the agent checks the server is healthy before sharing)
• Rendered as an iframe directly in the chat UI
• Openable in a new browser tab

Credit Cost

The development sandbox uses the same credit model as code execution:

• First 60 seconds: Free (no credits charged)
• After 60 seconds: 1 credit per 5 minutes of runtime (rounded up)

Credits are reserved when the sandbox is created and refunded based on actual usage when it's destroyed.

Session Limits

The sandbox is automatically destroyed when the conversation ends or the session times out.

Export Options

When the user is done, the agent can export the project:

• Knowledge Base — Saves all project files to your workspace, searchable by other agents
• Download — Generates a .tar.gz archive with a 1-hour download link

HTTP Tools

HTTP tools let your agent call external APIs. You define the endpoint, and Cognova handles authentication, input mapping, and response parsing.

Definition

Input Interpolation

Use {{input.fieldName}} in your URL, headers, or body to inject values from the agent's tool call. The field names must match your inputSchema.

https://api.example.com/search?q={{input.query}}&limit={{input.limit}}

Secret References

Use {{secret:NAME}} to reference encrypted workspace secrets. Secrets are resolved at execution time and never exposed in exports.

Authorization: Bearer {{secret:API_KEY}}

Add secrets in Settings → Integrations and create a new secret before using them in tools. The tool detail page will warn you if any referenced secrets are missing.

Response Transform

Extract a specific value from the API response using dot-path notation:

• data.results — returns the results array from { data: { results: [...] } }
• items[0].name — returns the first item's name
• Leave empty to return the full response

Example: Weather API

Name: get_weatherMethod: GETURL: https://api.weatherapi.com/v1/current.json?key={{secret:WEATHER_KEY}}&q={{input.location}}Response Transform: currentInput Schema:

{
  "type": "object",
  "properties": {
    "location": {
      "type": "string",
      "description": "City name or coordinates"
    }
  },
  "required": ["location"]
}

Security

• URLs are validated against private IP ranges (10.x, 172.x, 192.168.x, localhost) to prevent SSRF attacks
• Requests have a 30-second timeout
• Response bodies are truncated at 50 KB

Knowledge Tools

Knowledge tools provide agents with reference documentation they can look up during conversations. Unlike knowledge files (which are searched automatically), knowledge tools are invoked explicitly by the agent when it needs specific information.

Definition

When to Use Knowledge vs Knowledge Files

• Knowledge files (uploaded in the Knowledge section) are automatically searched based on conversation context
• Knowledge tools are explicitly invoked by the agent and return the full content — useful for structured reference material like API specs, coding standards, or step-by-step procedures

Example: Code Style Guide

Name: code_style_guideContent:

# Code Style Rules

## Naming
- Use camelCase for variables and functions
- Use PascalCase for classes and components
- Use UPPER_SNAKE_CASE for constants

## Formatting
- 2-space indentation
- No semicolons
- Single quotes for strings

Sandbox Tools

Sandbox tools execute custom code in a secure, isolated environment powered by E2B. The code runs in a container with network access and can install packages.

Definition

Accessing Input

Your code receives agent input via the TOOL_INPUT variable, which is a parsed dictionary/object:

Python:

# TOOL_INPUT is automatically available as a dict
name = TOOL_INPUT.get("name", "World")
print(f"Hello, {name}!")

JavaScript:

// TOOL_INPUT is automatically available as an object
const name = TOOL_INPUT.name || "World";
console.log(`Hello, ${name}!`);

Credit Cost

Code execution uses a credit-based billing model with a 60-second grace period:

• First 60 seconds: Free (no credits charged)
• After 60 seconds: 1 credit per 5 minutes of runtime (rounded up)

Credits are reserved upfront based on your plan's max timeout, then refunded after execution based on actual duration.

Examples:

• A 5-second calculation → 0 credits
• A 2-minute data processing job → 1 credit
• A 30-minute analysis → 6 credits

Output

• Whatever your code prints to stdout is returned to the agent
• stderr is included if present
• Text output is truncated at 50 KB — for larger outputs, use artifact storage (see below)

Artifact Storage

Sandbox tools can upload files (images, PDFs, datasets) to artifact storage instead of printing large data to stdout. This is essential for binary outputs like generated images, which would otherwise exceed the 50 KB output limit and bloat the conversation context.

A built-in upload_artifact() helper is automatically available in every sandbox:

Python:

# Generate or fetch some binary data
image_bytes = base64.b64decode(image_b64)

# Upload to artifact storage — returns the artifact key
artifact_key = upload_artifact(image_bytes, 'image/png')

if artifact_key:
    # Print metadata with the artifact_key — Cognova will convert it to a URL
    print(json.dumps({
        'artifact_key': artifact_key,
        'contentType': 'image/png',
        'description': 'Generated chart'
    }))

How it works:

1. Your code calls upload_artifact(data, content_type) with raw bytes
2. The file is uploaded directly to cloud storage (Railway Buckets)
3. You print a JSON object containing artifact_key in stdout
4. Cognova replaces the key with a permanent /api/artifacts/... URL before passing it to the agent
5. Images are rendered inline in the chat UI with download and copy buttons

Parameters:

Returns: The artifact key (string) on success, or None if storage is unavailable.

The artifact URL never expires — it redirects to a fresh signed URL on each request. Artifacts persist in cloud storage independently of the conversation.

Example: CSV Analyzer

Name: analyze_csvLanguage: pythonPackages: pandasCode:

import pandas as pd
import io

csv_data = TOOL_INPUT.get("csv_data", "")
df = pd.read_csv(io.StringIO(csv_data))

print(f"Rows: {df.shape[0]}, Columns: {df.shape[1]}")
print(f"\nColumns: {', '.join(df.columns)}")
print(f"\nSummary:\n{df.describe()}")

Input Schema:

{
  "type": "object",
  "properties": {
    "csv_data": {
      "type": "string",
      "description": "Raw CSV data to analyze"
    }
  },
  "required": ["csv_data"]
}

Input Schema

Every tool requires an inputSchema that tells the agent what parameters to provide. This is a standard JSON Schema object.

Structure

{
  "type": "object",
  "properties": {
    "paramName": {
      "type": "string",
      "description": "What this parameter is for"
    },
    "count": {
      "type": "number",
      "description": "How many results to return"
    }
  },
  "required": ["paramName"]
}

Supported types: string, number, integer, boolean, array, object.

The description field is important — it tells the AI model what to put in each parameter. Be specific.

Import & Export

Tools can be exported as JSON and imported into other workspaces.

Export

Click Export on any custom tool's detail page. The exported JSON contains the full tool definition with secret references preserved as {{secret:NAME}} placeholders (actual secret values are never included).

Import

Click Import on the tools list page and select a .json file. If the tool references secrets that don't exist in your workspace, you'll see a warning listing the missing secrets.

Export Format

{
  "toolType": "http",
  "name": "get_weather",
  "description": "Fetch current weather for a location",
  "version": "1.0",
  "definition": {
    "method": "GET",
    "url": "https://api.weatherapi.com/v1/current.json?key={{secret:WEATHER_KEY}}&q={{input.location}}",
    "responseTransform": "current",
    "inputSchema": {
      "type": "object",
      "properties": {
        "location": { "type": "string", "description": "City name" }
      },
      "required": ["location"]
    }
  }
}

Attaching Tools to Agents

After creating a tool, attach it to one or more agents:

1. Go to Agents → select an agent
2. Scroll to the Tools section
3. Click Add Tool and select from your workspace tools
4. Save the agent

Each agent only uses tools explicitly attached to it (plus built-in tools which are always available).

Built-in Tools

Every agent automatically has access to these tools without any configuration:

Built-in tools cannot be disabled, edited, or exported. They appear in the Built-in tab on the Tools page.