create-forge-agent

v1.1.0

Published

a month ago

🔥 FORGE - Framework for Orchestrating Robust Generative Engineers. Build production-ready AI agents with Kestra orchestration.

0High
0Medium
0Low

programmer-impeto

forge ai-agents kestra orchestration llm openrouter pydantic workflow automation cli

🔥 FORGE

███████╗ ██████╗ ██████╗  ██████╗ ███████╗
██╔════╝██╔═══██╗██╔══██╗██╔════╝ ██╔════╝
█████╗  ██║   ██║██████╔╝██║  ███╗█████╗
██╔══╝  ██║   ██║██╔══██╗██║   ██║██╔══╝
██║     ╚██████╔╝██║  ██║╚██████╔╝███████╗
╚═╝      ╚═════╝ ╚═╝  ╚═╝ ╚═════╝ ╚══════╝

🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥

Framework for Orchestrating Robust Generative Engineers

Build production-ready AI agents with Kestra orchestration in minutes, not weeks.

🚀 Quick Start

# Install globally
npm install -g create-forge-agent

# Initialize a new FORGE project
forge init

# Configure your credentials in .env
# Then list workflows
forge workflow list

# Run a workflow
forge workflow run my-workflow --wait

# View execution logs
forge logs <execution-id>

🎯 What is FORGE?

FORGE is a comprehensive framework for building production-grade AI agents with Kestra orchestration. It combines:

🤖 AI Agents - Pydantic-first Python agents with type safety
🎼 Orchestration - Kestra workflows for reliable execution
🔥 Best Practices - Production patterns from day one
⚡ Performance - 60x faster with Docker custom images
📊 Observability - OpenTelemetry built-in
🛡️ Guardrails - PII detection, rate limiting, cost control

🏗️ Architecture

FORGE uses a meta-agent architecture powered by Claude Code:

┌─────────────────────────────────────────────────────────┐
│                    FORGE Symphony                        │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  Researcher (4-Tier) → Architect (Dual-Mode)            │
│         ↓                    ↓                           │
│  Knowledge Base      Python Agent Spec                  │
│                              ↓                           │
│                      Smith-Code Generator               │
│                              ↓                           │
│                   Production-Ready Agent                │
│                                                          │
│  ─────────────────────────────────────────────          │
│                                                          │
│  Researcher (4-Tier) → Architect (Dual-Mode)            │
│         ↓                    ↓                           │
│  Knowledge Base      Kestra Workflow Spec               │
│                              ↓                           │
│                Smith-Orchestrator Generator             │
│                              ↓                           │
│               Kestra YAML + Docker + Tests              │
│                                                          │
└─────────────────────────────────────────────────────────┘

🎼 Meta-Agents

FORGE includes 4 production-ready meta-agents (Claude Code slash commands):

1. 🔍 Researcher (4-Tier Web Search Specialist)

/researcher *deep "customer support agent patterns"

Tier 1: Basic web, GitHub, docs search
Tier 2: Multi-source, cross-validation, temporal filtering
Tier 3: arXiv, Stack Overflow, GitHub Issues, Reddit/HN
Tier 4: Knowledge graph, concept mapping, best practices

2. 🎭 Architect (Dual-Mode Designer)

# Design Python AI agent
/architect *design python-agent customer-support

# Design Kestra workflow
/architect *design kestra-workflow ml-training

5-question interview for complete requirements
Generates comprehensive YAML specs
Supports both Python agents and Kestra workflows

3. ⚒️ Smith-Code (Python Agent Generator)

/smith-code *generate customer-support

Generates Pydantic-first Python agents
Includes tools, guardrails, tests
Type-safe I/O with JSON Schema export
OpenTelemetry observability built-in

4. 🎼 Smith-Orchestrator (Kestra Workflow Generator)

/smith-orchestrator *generate ml-training

Generates Kestra YAML workflows
Includes Docker custom images (60x faster!)
Git integration patterns
Test workflows and CI/CD automation

📚 Documentation

FORGE includes 7 comprehensive documentation files (163KB):

Orchestration Docs

kestra-patterns.md (21KB) - 12 production Kestra patterns
kestra-git-integration.md (10KB) - 10 Git integration patterns
kestra-requirements.md (8KB) - Docker optimization (60x speedup)

Code Docs

agent-pattern.md (15KB) - ForgeAgent base class
pydantic-schemas.md (10KB) - Type-safe I/O patterns
tool-pattern.md (8KB) - @forge.tool decorator
testing-strategy.md (7KB) - Comprehensive testing guide

🔥 Key Features

⚡ 60x Performance Boost

Docker custom images instead of beforeCommands:

Before: ~10 minutes (pip install every execution)
After: ~10 seconds (dependencies pre-installed)
Impact: Production-grade by default

🛡️ Production-Ready Guardrails

PII Detection: Prevent sensitive data leakage
Prompt Injection: Detect jailbreak attempts
Rate Limiting: Control request volume
Cost Control: Cap inference costs
Toxicity Detection: Filter harmful content

📊 Built-in Observability

OpenTelemetry: Distributed tracing
Structured Logs: JSON logging
Metrics: Request duration, token usage, error rate
Dashboards: Track agent performance

🔄 Transformation Protocol

Agents can transform into each other seamlessly:

User: /smith-code *generate customer-support
[Spec missing - transforms to Architect]
Architect: 🎭 Let's design the architecture...
[Completes 5-question interview]
[Generates spec YAML]
[Transforms back to Smith-Code]
Smith-Code: ✅ Agent generated!

📦 Installation

Global Installation (Recommended)

npm install -g create-forge-agent
forge --version

Local Installation

npm install create-forge-agent
npx forge init

From Source

git clone https://github.com/forge-ai/create-forge-agent
cd create-forge-agent
npm install
npm run build
npm link

🎯 CLI Commands

Initialize Project

forge init

Creates:

forge.config.yaml - FORGE configuration
.env - Environment variables (add to .gitignore!)
.forge-specs/ - Agent and workflow specs
.forge-docs/ - Documentation
src/agents/ - Generated agents
tests/ - Test files

Workflow Management

# List workflows
forge workflow list
forge workflow list --namespace forge.workflows

# Run workflow
forge workflow run my-workflow
forge workflow run my-workflow --inputs '{"param": "value"}'
forge workflow run my-workflow --wait  # Wait for completion

# Check workflow
forge workflow check my-workflow

# Delete workflow
forge workflow delete my-workflow
forge workflow delete my-workflow --force

Execution Logs

# Show execution logs
forge logs <execution-id>
forge logs <execution-id> --follow  # Follow real-time

# List recent executions
forge logs:list my-workflow
forge logs:list my-workflow --limit 20

Quick Commands

# List workflows (alias)
forge list
forge ls

# Workflow run (alias)
forge w run my-workflow

⚙️ Configuration

forge.config.yaml

kestra:
  url: ${KESTRA_URL:-http://localhost:8080}
  apiToken: ${KESTRA_API_TOKEN}
  # Or use basic auth:
  # basicAuth:
  #   username: ${KESTRA_USERNAME}
  #   password: ${KESTRA_PASSWORD}

openrouter:
  apiKey: ${OPENROUTER_API_KEY}

defaults:
  namespace: forge.workflows
  docker_registry: registry.example.com  # Optional

.env

# Kestra Configuration
KESTRA_URL=http://localhost:8080
KESTRA_API_TOKEN=your-api-token-here

# Or use basic auth:
# KESTRA_USERNAME=admin
# KESTRA_PASSWORD=admin

# OpenRouter Configuration
OPENROUTER_API_KEY=your-openrouter-api-key-here

# Docker Registry (optional)
DOCKER_REGISTRY=registry.example.com

🚀 Complete Workflow

1. Research Best Practices

# In Claude Code
/researcher *deep "customer support agent patterns 2024"

Output: Research stored in knowledge base

2. Design Agent Architecture

# In Claude Code
/architect *design python-agent customer-support

5-Question Interview:

Agent type? → Support Agent
Input/Output? → question (str), customer_id (int) → answer (str), confidence (float)
Tools? → kb_search, web_search, create_ticket
Routing? → claude-3.5-sonnet → llama-3.2-3b-instruct
Guardrails? → PII detection, toxicity, rate limiting

Output: .forge-specs/agents/customer-support.yaml

3. Generate Agent Code

# In Claude Code
/smith-code *generate customer-support

Output:

src/agents/customer_support.py - Agent class
src/tools/kb_search.py - Tools
tests/test_customer_support.py - Tests

4. Design Kestra Workflow

# In Claude Code
/architect *design kestra-workflow support-pipeline

5-Question Interview:

Workflow type? → Event-driven
Git integration? → Clone & execute
Scripts? → Python + Docker custom image
Orchestration? → Sequential
Triggers? → Webhook

Output: .forge-specs/workflows/support-pipeline.yaml

5. Generate Workflow

# In Claude Code
/smith-orchestrator *generate support-pipeline

Output:

workflows/support-pipeline.yaml - Kestra YAML
Dockerfile - Custom image
requirements.txt - Dependencies
workflows/support-pipeline-test.yaml - Test workflow

6. Deploy & Monitor

# Deploy workflow to Kestra (manual or via Kestra UI)

# Run workflow
forge workflow run support-pipeline --wait

# Monitor logs
forge logs <execution-id> --follow

# Check statistics
forge workflow check support-pipeline

🎨 Examples

Customer Support Agent

# Generated by Smith-Code
from forge import forge, ForgeAgent
from pydantic import BaseModel, Field

class CustomerSupportInput(BaseModel):
    customer_question: str = Field(..., description="Customer's question")
    customer_id: int = Field(..., description="Customer ID")

class CustomerSupportOutput(BaseModel):
    answer: str = Field(..., description="Answer to question")
    confidence: float = Field(..., ge=0.0, le=1.0)
    sources: list[str] = Field(default=[])

@forge.agent(
    name="customer_support",
    model="anthropic/claude-3.5-sonnet",
    fallback="meta-llama/llama-3.2-3b-instruct",
    tools=[kb_search_tool, web_search_tool],
    guardrails={
        "input": ["pii_detection", "toxicity"],
        "output": ["pii_leakage", "factual_consistency"]
    },
    memory_type="hybrid"
)
class CustomerSupportAgent(ForgeAgent[CustomerSupportInput, CustomerSupportOutput]):
    system_prompt = """
    You are a customer support agent...
    """

    async def before_execute(self, input: CustomerSupportInput):
        # Load customer profile
        self.customer_profile = await self.db.get_customer(input.customer_id)

    async def after_execute(self, output: CustomerSupportOutput):
        # Store interaction
        await self.db.store_interaction(...)

ML Training Workflow

# Generated by Smith-Orchestrator
id: ml-training
namespace: forge.workflows

tasks:
  - id: clone_repo
    type: io.kestra.plugin.git.Clone
    url: https://github.com/org/ml-training
    branch: main
    username: "{{ secret('GITHUB_USER') }}"
    password: "{{ secret('GITHUB_TOKEN') }}"

  - id: train_model
    type: io.kestra.plugin.scripts.python.Script
    docker:
      image: myorg/ml-base:1.0  # 60x faster!
    script: |
      import sys
      sys.path.insert(0, '{{ outputs.clone_repo.directory }}')
      from training import train_model
      result = train_model()
      print(f"::{{outputs.accuracy}}::{result['accuracy']}")

  - id: deploy_if_good
    type: io.kestra.plugin.core.flow.Switch
    value: "{{ outputs.train_model.vars.accuracy }}"
    cases:
      HIGH:
        - id: deploy_model
          type: io.kestra.plugin.scripts.python.Script
          script: |
            from deployment import deploy
            deploy(model_uri="{{ outputs.train_model.vars.model_uri }}")
      LOW:
        - id: notify_team
          type: io.kestra.plugin.notifications.slack.SlackExecution
          url: "{{ secret('SLACK_WEBHOOK') }}"
          customMessage: "Model accuracy too low: {{ outputs.train_model.vars.accuracy }}"

triggers:
  - id: daily_training
    type: io.kestra.plugin.core.trigger.Schedule
    cron: "0 2 * * *"

  - id: on_push
    type: io.kestra.plugin.core.trigger.Webhook
    key: github-push

🧪 Testing

FORGE includes comprehensive testing patterns:

Test Pyramid

60% Unit Tests: Individual components
30% Integration Tests: Agent + dependencies
10% E2E Tests: Full workflows

Run Tests

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Watch mode
npm run test:watch

Example Test

// tests/kestra-client.test.ts
import { KestraClient } from '../src/clients/kestra';

describe('KestraClient', () => {
  it('should list flows', async () => {
    const client = new KestraClient(testConfig.kestra, 'forge.workflows');
    const flows = await client.listFlows();
    expect(flows).toBeInstanceOf(Array);
  });

  it('should execute workflow', async () => {
    const client = new KestraClient(testConfig.kestra, 'forge.workflows');
    const execution = await client.executeFlow('test-workflow');
    expect(execution.id).toBeDefined();
    expect(execution.state.current).toBe('RUNNING');
  });
});

📈 Performance

Benchmark: ML Training Pipeline (10 tasks)

| Metric | Before (beforeCommands) | After (Docker Custom) | Improvement | |--------|-------------------------|----------------------|-------------| | Dependency Install | 10 min × 10 = 100 min | 0 min (cached) | ∞ | | Execution | 20 min | 20 min | - | | Total | 120 minutes | 20 minutes | 6x faster |

Per-Task Performance

| Metric | Before | After | Improvement | |--------|--------|-------|-------------| | First Run | 10 minutes | 30 seconds | 20x | | Subsequent Runs | 10 minutes | 10 seconds | 60x | | Reliability | Network-dependent | Cached | 100% |

🤝 Contributing

Contributions welcome! Please read CONTRIBUTING.md first.

Development Setup

git clone https://github.com/forge-ai/create-forge-agent
cd create-forge-agent
npm install
npm run dev  # Watch mode

Project Structure

create-forge-agent/
├── src/
│   ├── commands/      # CLI commands
│   ├── clients/       # Kestra API client
│   ├── utils/         # Utilities (config, logo)
│   └── types/         # TypeScript types
├── tests/             # Test files
├── bin/               # Executable
└── dist/              # Compiled output

📄 License

🔗 Links

GitHub: https://github.com/forge-ai/create-forge-agent
Documentation: https://forge-ai.github.io/docs
Issues: https://github.com/forge-ai/create-forge-agent/issues
NPM: https://www.npmjs.com/package/create-forge-agent

🌟 Show Your Support

Give a ⭐️ if this project helped you!

Built with ❤️ by the FORGE community