Tooling & Sandbox Execution
Relevant source files
The following files were used as context for generating this wiki page:
The Flow platform leverages a robust system for extending agent capabilities through specialized tools and isolated execution environments. Tools allow agents to interact with external data, perform computations, and manage state, while the Sandbox provides a secure, restricted environment for executing arbitrary Python code. This infrastructure is critical for agents like the Data Analyst, who must perform numeric work and data profiling, and the Code Review Agent, who uses the sandbox to detect runtime errors.
Sources: README.md, services/api/scripts/seed_agents_and_datasets.py:175-180
Tooling Architecture
Tools in Flow are associated with an agent's "Genome" and are configurable via the agents.config.tools attribute. The system supports a variety of tool types including knowledge retrieval, web searching, and long-term memory management.
Available Tools and Capabilities
Agents are assigned specific toolsets based on their specialized roles. These tools are enabled or disabled within the agent's configuration.
| Tool | Description | Enabled For (Examples) |
|---|---|---|
retrieve | Knowledge search using pgvector retrieval (and optionally Qdrant). | General Assistant, Code Review Agent, Bug Triage |
sandbox | Isolated Python code execution environment. | Data Analyst, Bug Triage, Code Review Agent |
long_term_memory | Recall of past run summaries and facts via AsyncPostgresStore. | Meeting Summarizer, Research Analyst |
tavily_search | Web search capabilities for external research. | Research Analyst, Content Strategist |
arxiv_search | Specialized search for academic papers on arXiv. | Research Analyst |
hf_papers | Access to research highlights and papers from HuggingFace. | Research Analyst, Daily AI Briefing |
subagent_call | Ability to delegate specialized tasks to other agents. | General Assistant |
Sources: README.md, AGENTS.md, services/api/scripts/seed_agents_and_datasets.py:44-51, 80-87
Tool Execution Flow
The execution of tools occurs within the LangGraph pipeline, specifically during the "worker" phase.
The diagram shows the LangGraph pipeline where the Worker node invokes enabled tools before passing results to the Synthesizer.
Sources: README.md, services/api/scripts/seed_agents_and_datasets.py:44-60
Sandbox Execution
The Sandbox is a specialized tool that allows agents to execute Python code blocks safely. This is primarily used for data analysis, bug reproduction, and code validation.
Use Cases by Agent
- Data Analyst: Uses the sandbox to load, clean, and analyze datasets using libraries like
pandas,numpy, andscipy. It interprets results to identify trends and anomalies. - Code Review Agent: Executes code diffs in the sandbox to detect runtime errors as part of its security and quality assessment.
- Bug Triage Assistant: Writes and runs minimal reproduction scripts in the sandbox to confirm the existence of reported bugs.
Sources: services/api/scripts/seed_agents_and_datasets.py:108-112, 175-180, 219-222
Implementation in Skills
Skills are embedded in an agent's prompt and often specify allowed tools. For example, the exploratory-data-analysis skill explicitly triggers the sandbox tool to profile datasets.
name: exploratory-data-analysis
description: Perform statistical summaries or dataset profiling
allowed-tools: sandbox, retrieve
triggers:
- "analyze this data"
- "data profiling"
Sources: services/api/scripts/seed_skills.py:657-665
Observability and Monitoring
Tool invocations are instrumented via the FlowCallbackHandler to ensure performance and reliability.
- Latency Tracking: The system tracks the latency (in milliseconds) of every tool invocation.
- Structured Logging: Tools emit structured events such as
tool.startandtool.end. - Error Handling: Failures in tool chains are logged with specific metadata like
workspace_idandagent_idfor debugging.
Sources: README.md
Knowledge Graph Integration
Tools and tool calls are represented as nodes within the system's Knowledge Graph (KG). This allows for visual analysis of how tools are utilized during executions.
Node Types in Graph
tool_call: Represents a specific instance where an agent utilized a tool.skill: Represents the specialized logic that may trigger a tool call.
The Knowledge Graph visualizes the relationship between Agents, their versioned Genomes, the Skills they possess, and the resulting Tool Calls.
Sources: apps/web/src/app/(app)/graph/page.tsx:32-37, 48-60
Conclusion
Tooling and Sandbox execution form the functional backbone of Flow's agentic capabilities. By providing isolated environments for code execution and structured access to external data sources, Flow enables agents to perform complex, high-stakes tasks such as financial analysis and security auditing while maintaining observability and safety through restricted interfaces.