Tools¶

Tools are sub-component nodes that give agents the ability to take actions in the world -- running shell commands, making HTTP requests, searching the web, and even modifying the platform itself. Each tool is implemented as a LangChain @tool function that the LLM can invoke through function calling.

How Tools Connect to Agents¶

Tools are sub-component nodes that connect to agent nodes via the green diamond tools handle on the agent's bottom edge:

                    +------------------+
                    |     Agent        |
                    |                  |
                    +--[model][tools]--+
                         |       |
                    AI Model   run_command
                               web_search
                               calculator

The connection uses edge_label="tool" on the workflow edge. At build time, the agent queries all tool edges pointing to it, loads each tool node's component factory, and registers the resulting LangChain @tool functions for LLM function calling.

Real-Time Tool Status¶

When an agent invokes a tool during its reasoning loop, the tool node on the canvas shows live status badges via WebSocket:

1. Running (spinning circle) -- tool function is executing.
2. Success (checkmark) -- tool completed without errors.
3. Failed (X) -- tool raised an exception.

This is implemented by wrapping each tool function with a status publisher that broadcasts node_status events to the workflow:{slug} WebSocket channel before and after execution.

Built-In Utility Tools¶

These five tools provide general-purpose capabilities for agents:

Run Command¶

Executes arbitrary shell commands in a subprocess with configurable timeout. Output is capped at 50,000 characters (truncated from the middle if exceeded). The subprocess runs with stdin=DEVNULL and start_new_session=True for isolation.

Agent: "List files in the project directory"
Tool call: run_command(command="ls -la /home/user/project")
Tool result: "total 48\ndrwxr-xr-x  6 user user 4096 ..."

HTTP Request¶

Makes HTTP requests with configurable default method, headers, and timeout. The agent can override the method and provide a request body per call. Response bodies are truncated to 4,000 characters.

Web Search¶

Queries a SearXNG metasearch engine instance. Requires a running SearXNG deployment -- configure the URL in the node's extra_config. Returns the top 5 results formatted as title, URL, and content snippet.

Calculator¶

Uses Python's ast module to safely parse and evaluate mathematical expressions. Only numeric constants and basic arithmetic operators are allowed -- no function calls, variable access, or imports.

Date & Time¶

Returns the current timestamp formatted as YYYY-MM-DD HH:MM:SS TZ. Supports any timezone from Python's zoneinfo module (e.g., America/New_York, Europe/London). Defaults to UTC if no timezone is configured.

Self-Awareness Tools¶

These tools enable agents to introspect, manage the platform, and orchestrate other workflows. They are the building blocks for self-improving agents that can modify their own configuration, create new workflows, and delegate work.

Create Agent User + Platform API¶

These two tools work together to give an agent full API access:

1. The agent calls create_agent_user to get an API key.
2. The agent calls platform_api with that API key to interact with any REST endpoint.
3. Common first call: platform_api(path="/openapi.json") to discover available endpoints.

Spawn & Await¶

This tool enables multi-agent orchestration. When an agent calls spawn_and_await:

1. The tool calls LangGraph's interrupt() to checkpoint the agent mid-reasoning.
2. The orchestrator creates a child WorkflowExecution and enqueues it on RQ.
3. The parent agent's node enters a waiting state.
4. When the child execution completes, its output is injected into the parent's state.
5. The parent agent resumes from the checkpoint -- interrupt() returns the child's output as a JSON string.

This requires either conversation memory (SqliteSaver) or an ephemeral RedisSaver checkpointer to persist the agent's state during the wait.

Epic Tools + Task Tools¶

These tools provide a project management layer for agents:

• Epics group related tasks with optional token/USD budgets.
• Tasks are individual work items within an epic, each linked to a workflow execution.
• Budget enforcement happens at the orchestrator level -- if an epic's budget is exceeded, the execution fails.

System Health¶

Returns a comprehensive JSON health report including:

• Redis connectivity and ping latency
• RQ worker count and status
• Queue depths (pending jobs)
• Stuck executions (running for too long)
• Recent failed executions
• Scheduled job status

Complete Tool Reference¶