This guide gets you from zero to a deployed, working AI agent.

Step 1: Install Flutch CLI

Install the Flutch CLI globally:

bash
npm install -g flutch

Verify installation:

bash
flutch --version
# Output: flutch v1.0.0

Step 2: Authenticate

bash
flutch login

This opens a browser window where you can sign in or create a new account. After authorization, the CLI will be authenticated and ready to use. Your session is saved locally at ~/.flutch/credentials and will be used automatically for local development.

Step 3: Create Your Graph

Create a new agent using the interactive wizard:

bash
flutch create my-agent

The wizard will guide you through:

bash
? Select framework:
  ❯ LangGraph
     LlamaIndex Workflows
     Haystack Pipelines

? Select language:
  ❯ Python
    TypeScript

? Select template:
  ❯ Simple starter (basic echo agent)
    Advanced example (multi-step workflow)

Flutch generates a complete project:

bash
Creating project 'my-agent'...
Generating project structure...
Project created successfully!

Next steps:
  cd my-agent
  flutch dev

Navigate to your project:

bash
cd my-agent

Project Structure

For Python + LangGraph:

bash
my-agent/
├── main.py                 # Entry point
├── graph/
│   ├── builder.py          # Graph construction
│   ├── nodes.py            # Node implementations
│   └── state.py            # State definition
├── graph.manifest.json     # Agent metadata
├── requirements.txt        # Python dependencies
└── README.md

For TypeScript + LangGraph:

bash
my-agent/
├── src/
│   ├── clients/                # MCP and external clients
│   ├── config/                 # Environment configuration
│   ├── nodes/                  # Graph nodes
│   ├── services/               # Additional services
│   ├── versions/v1.0.0/        # Versioned builders
│   │   ├── builder.ts          # Graph version builder
│   │   └── config-schema.json  # Graph version config
│   ├── my-agent.module.ts      # NestJS module
│   ├── state.model.ts          # State definition
│   └── main.ts                 # Entry point
├── graph.manifest.json         # Graph metadata
├── package.json
├── tsconfig.json
└── README.md

Edit graph.manifest.json to customize your agent:

json
{
  "companySlug": "your-company",
  "name": "my-agent",
  "title": "My First Agent",
  "description": "A simple AI agent that answers questions",
  "versioning": {
    "strategy": "semver",
    "defaultVersion": "1.0.0",
    "supportedVersions": ["1.0.0"]
  }
}

Step 4: Test Locally

Before deploying, test your agent locally:

Python:

bash
# Install dependencies
pip install -r requirements.txt

# Run in development mode
python main.py --dev

TypeScript:

bash
# Install dependencies
npm install / yarn install

# Run in development mode
flutch dev

You'll see:

bash
Starting agent in development mode...
Graph type: your-company.my-agent::1.0.0
Local server: http://localhost:3100
Agent ready for testing

Test your agent:

bash
flutch graph test "Hello! What can you do?"

If it works locally, it will work on Flutch!

Step 5: Deploy to Flutch

Deploy your agent with one command:

bash
flutch deploy

You'll see deployment progress:

bash
Validating manifest...                    ✓
Building graph package...                  ✓
Uploading to Flutch...                    ✓
Deploying your-company.my-agent::1.0.0...  ✓
Deployment successful!

View in console: https://console.flutch.ai/agents/abc123
Chat with agent: https://app.flutch.ai/a/abc123
API endpoint: https://api.flutch.ai/v1/agents/abc123/invoke

Your agent is now live!