Hatchify Documentation

Hatchify is a multi-agent workflow platform that uses a dynamic graph execution engine to enable complex AI Agent collaboration. It is built using FastAPI and the AWS Strands SDK, allowing developers to dynamically create and execute Agent workflows via JSON configurations.

Key capabilities include:

• Dynamic Orchestration: Build workflows via JSON.
• Intelligent Routing: Supports Rules, JSONLogic, Router Agents, and Orchestrators.
• MCP Integration: Native support for the Model Context Protocol to extend tool capabilities.
• Event-Driven Architecture: Uses SSE (Server-Sent Events) for real-time execution tracking.
• Multi-Model Support: Unified interface for OpenAI, Gemini, Claude, etc.

The Hatchify Web Frontend is built using the following technologies:

• React 19: UI framework
• TypeScript 5.7: Type safety
• Vite 7: Build tool
• Tailwind CSS 4: Styling
• React Flow: Workflow visualization
• Biome: Code formatting and linting

Hatchify follows a three-tier architecture designed for high cohesion and low coupling using generics and dependency injection:

1. API Layer (FastAPI Router): Handles route definitions, request validation (via Pydantic), and response serialization. It uses Depends for dependency injection.
2. Service Layer (GenericService[T]): Orchestrates business logic, manages transactions (auto commit/rollback), and coordinates between different repositories.
3. Repository Layer (BaseRepository[T]): Provides a type-safe, asynchronous abstraction for data access (CRUD operations) and query building. It uses fastapi-pagination for unified pagination.
4. Database Layer (SQLAlchemy ORM): The underlying data persistence layer.

When developing with or for Hatchify, keep the following architectural constraints in mind:

• Async First: All database and I/O operations must use async/await.
• Dependency Injection: Services and Repositories are obtained through Manager singletons.
• Version Management: The current_spec of a Graph is the single source of truth; the version table is used for snapshots.
• Security: Web Builder file operations are restricted by the security.allowed_directories setting found in development.yaml.
• Configuration Priority: Settings are applied in the following order: Environment Variables > YAML > .env file.

Function nodes are deterministic nodes used for operations like data transformation, formatting, or calculation.

To create a Function node:

1. Use the @tool decorator.
2. The function must accept inputs (often structured output from an upstream Agent).
3. The function must return a Pydantic BaseModel type to ensure type-safe data passing within the Graph.
4. Reference the function in the Graph using its function_ref (the registered name).

from pydantic import BaseModel
from strands import tool

class EchoResult(BaseModel):
    text: str

@tool(name="echo_function", description="Echo input")
async def echo_function(text: str) -> EchoResult:
    return EchoResult(text=f"[ECHO] {text}")

In Hatchify's Graph system, Agent nodes are LLM-based nodes used to execute tasks. There are three primary types:

• General Agent: Performs specific tasks like data analysis or content generation.
• Router Agent: Decides the next step in the workflow based on structured fields from upstream output.
• Orchestrator Agent: Acts as a central coordinator for all nodes and can terminate the process using a COMPLETE signal.

Agents can be configured with dynamic model selection (OpenAI, Gemini, Claude, etc.), toolset registration (MCP or custom local tools), and structured output Schemas for routing and data passing.

The project follows a layered architecture:

• hatchify/business/: Business layer containing API routes (api/v1/), DB config (db/), ORM models (models/), repositories (repositories/), and logic (services/).
• hatchify/common/: Shared layer for domain models (domain/), extensions (extensions/), and settings (settings/).
• hatchify/core/: The core engine, including the graph building system (graph/), MCP integration (mcp/), and event stream processing (stream_handler/).
• hatchify/launch/: Application entry point.
• resources/: Configuration directory for mcp.toml, models.toml, and development.yaml.

The frontend requires Node.js 20+ and pnpm 9+. You must build the icons package before the first run.

# Navigate to web directory
cd web

# Install dependencies
pnpm install

# Build icons package (required before first run)
pnpm build:icons

You can override any configuration setting using environment variables with the HATCHIFY__ prefix. Environment variables have the highest priority, followed by the YAML configuration file, and finally default values.

Example overrides:

• HATCHIFY__SERVER__PORT=8080 overrides the server port.
• HATCHIFY__SERVER__BASE_URL=https://your-domain.com overrides the base URL.
• HATCHIFY__DB__PLATFORM=postgresql overrides the database platform.

# Override server port
export HATCHIFY__SERVER__PORT=8080

# Override base_url (use in production deployment)
export HATCHIFY__SERVER__BASE_URL=https://your-domain.com

# Override database platform
export HATCHIFY__DB__PLATFORM=postgresql

You can override any configuration in development.yaml using environment variables with the HATCHIFY__ prefix. The priority order is: Environment Variables > YAML Configuration > Defaults.

Use double underscores __ to represent nesting in the YAML structure.

Examples:

• Override server port: export HATCHIFY__SERVER__PORT=8080
• Override production base URL: export HATCHIFY__SERVER__BASE_URL=https://your-domain.com
• Override database platform: export HATCHIFY__DB__PLATFORM=postgresql

# Example overrides
export HATCHIFY__SERVER__PORT=8080
export HATCHIFY__SERVER__BASE_URL=https://your-domain.com
export HATCHIFY__DB__PLATFORM=postgresql

To start the application for development, run the backend and frontend in separate terminals.

Start Backend

Using uvicorn:

uvicorn hatchify.launch.launch:app --reload --host 0.0.0.0 --port 8000

Or using main.py:

python main.py

API documentation will be available at http://localhost:8000/docs.

Start Frontend

cd web
pnpm dev

The web interface will be available at http://localhost:5173.

# Backend
uvicorn hatchify.launch.launch:app --reload --host 0.0.0.0 --port 8000

# Frontend
cd web
pnpm dev