System Overview

Agent Studio is composed of four primary subsystems that communicate over well-defined boundaries. Understanding this topology is essential for building an external harness that mirrors the same development experience.

Component Topology

Entity Hierarchy

The core data model has two parallel hierarchies — instances (live workflow state) and templates (portable blueprints):

Templates are the packaging unit. When a workflow template is imported, Agent Studio creates instances from the templates. When exported, instances are snapshot back into templates.

Data Flow

File-Based Storage: `studio-data/`

Alongside the SQLite database, Agent Studio uses a filesystem tree for code and assets:

studio-data/
├── tool_templates/              Tool code packages (tool.py + requirements.txt)
│   ├── sample_tool/
│   ├── json_reader_abc123/
│   └── calculator_def456/
├── dynamic_assets/              Icons for templates and instances
│   ├── tool_template_icons/
│   ├── tool_instance_icons/
│   ├── agent_template_icons/
│   ├── agent_icons/
│   ├── mcp_template_icons/
│   └── mcp_instance_icons/
├── workflows/                   Per-workflow working directories
├── deployable_workflows/        Staged deployment artifacts
├── deployable_applications/     Staged application artifacts
└── temp_files/                  Transient upload/export scratch space

The studio-data/ path is a hard-coded constant (consts.ALL_STUDIO_DATA_LOCATION = "studio-data"). All file references stored in the database (e.g., source_folder_path, tool_image_path) are relative to the project root and rooted under this directory.

Design Principles for Harness Builders

Proto-first API: All backend operations are defined in protobuf. The gRPC service is the single source of truth for capabilities.
Thin service layer: service.py is a router — business logic lives in domain modules. This pattern is easy to replicate.
Dual storage: SQLite for metadata, filesystem for code artifacts. Template ZIPs bridge both by bundling the manifest JSON and the studio-data/ subtree.
Isolated execution: The workflow engine is a separate package with its own virtualenv. This ensures tool dependencies don’t conflict with the studio itself.
Observable by default: Every workflow execution produces OTel traces and a structured event stream, enabling the visual canvas to show real-time progress.

Keyboard shortcuts