Skip to content

Getting Started with Helix

This guide walks you through installing Helix, deploying your first AI agent, and building intelligent workflows.

Helix is an enterprise agentic AI platform that combines integration patterns, AI agents, and protocol interoperability in a single binary. You define agents and workflows in YAML, and Helix handles the rest: LLM orchestration, tool use, memory, streaming, and connectivity to 440+ external systems.

Table of Contents

Prerequisites

  • The helix binary for your platform and your license file (see Licensing).
  • An LLM API key (OpenAI, Anthropic, or a local Ollama instance) if you plan to use AI agents.
  • Go 1.25 or later -- only if you build custom components, processors or connectors.

Installation

Install the binary

Helix ships as a single self-contained binary. Put helix on your $PATH and point it at your license file (see Licensing):

export HELIX_LICENSE=/path/to/your.helix.license

Verify Installation

helix version
# Helix 0.3.0

Deploy Your First AI Agent

Helix agents are AI-powered processing units that live inside your integration pipelines. They receive messages, reason with an LLM, optionally call tools, and route results to downstream systems -- all defined in a single YAML file.

Option 1: Use helix init

The init command scaffolds a new project with a sample flow and configuration:

helix init my-project
cd my-project

This creates: - helix.yaml -- framework configuration (management API, health checks) - flow.yaml -- a sample workflow

Option 2: Write an agent flow manually

Create a file named flow.yaml:

agents:
  - id: assistant
    type: react
    trigger: http-server://0.0.0.0:8080/chat
    model:
      provider: openai
      model: gpt-4o
      api_key: "${env:OPENAI_API_KEY}"
    system_prompt: |
      You are a helpful assistant. Answer questions clearly
      and concisely.
    memory:
      enabled: true
      type: sliding-window
      window_size: 20

This agent: 1. Listens for HTTP POST requests on port 8080 at /chat 2. Uses a ReAct reasoning loop backed by GPT-4o 3. Reasons about the input, optionally calls tools, and returns a response 4. Conversation memory is maintained across requests (sliding window of 20 messages)

Run It

export OPENAI_API_KEY="sk-..."
helix run flow.yaml

You should see output like:

INFO  Helix starting workflows=1 connectors=0 version=0.3.0
INFO  Component started scheme=http-server
INFO  Workflow started id=chat-agent from=http-server://0.0.0.0:8080/chat
INFO  Helix is running. Press Ctrl+C to stop.

Test your agent:

curl -X POST http://localhost:8080/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "What is Helix?"}'

Press Ctrl+C to stop. The engine will drain in-flight exchanges and shut down gracefully.

Expose Your Agent as MCP Tools

Once your agent works, you can expose it to Claude Desktop, Cursor, or any MCP client by adding a mcps: block to your flow file:

agents:
  - id: assistant
    type: react
    trigger: http-server://0.0.0.0:8080/chat
    model:
      provider: openai
      model: gpt-4o
      api_key: "${env:OPENAI_API_KEY}"
    system_prompt: |
      You are a helpful assistant. Answer questions clearly
      and concisely.
    memory:
      enabled: true
      type: sliding-window
      window_size: 20

mcps:
  - id: my-tools
    addr: "0.0.0.0:3100"
    expose: [assistant]

Now your agent is discoverable as an MCP tool at http://localhost:3100/mcp. See the MCP Integration Guide for transport options, Claude Desktop configuration, and advanced usage.

Call External Agents

To call external agents from within your agent, use type: a2a tools with authentication:

agents:
  - id: coordinator
    type: react
    trigger: http-server://0.0.0.0:8080/coordinate
    model:
      provider: openai
      model: gpt-4o
    tools:
      - name: research_agent
        type: a2a
        description: "Delegate research to a remote agent"
        a2a_server:
          url: "http://research-agent.internal:9000"
        auth:
          type: bearer
          token: "${env:A2A_TOKEN}"

For local agents in the same flow, use sub_agents instead. See the Protocol Interop Guide for A2A details and the AI Agents Guide for all tool types.

Define a Tool

Tools are the AI-native way to define self-describing, schema-validated endpoints. Unlike workflows, every tool must declare description, input, and output schemas. The parser rejects tools without them.

Create a file named tools-flow.yaml:

tools:
  - id: search
    description: "Search knowledge base"
    input:
      query: { type: string, description: "Search query", required: true }
      limit: { type: integer, description: "Max results", default: 10 }
    output:
      results: { type: array, description: "Matching documents" }
      total: { type: integer, description: "Total matches" }
    steps:
      - transform:
          starlang: |
            q = payload["query"]
            limit = payload.get("limit", 10)
            write({"results": [], "total": 0}, "application/json")

This tool: 1. Auto-generates a tool://search URI (no from: needed) 2. Validates input against the input: schema before execution 3. Is auto-discoverable by MCP with full input and output schemas 4. Stores the output schema in the x-helix-output-schema extension

Expose your tools to MCP clients by adding an mcps: block:

tools:
  - id: search
    description: "Search knowledge base"
    input:
      query: { type: string, description: "Search query", required: true }
    output:
      results: { type: array, description: "Matching documents" }
    steps:
      - transform:
          starlang: '"[]"'

mcps:
  - id: my-tools
    addr: "0.0.0.0:3100"
    expose: [search]

MCP clients see the tool with guaranteed input and output schemas -- no guessing required.

Define a Pipeline

Pipelines chain a source to a sequence of processing steps. Use them for data ingestion, ETL, or any multi-step workflow that does not need an LLM:

pipelines:
  - id: ingest-docs
    source: http-server://0.0.0.0:8080/ingest
    steps:
      - rag-ingest: { reader: directory }
      - rag-chunk: { strategy: semantic }

Run with Debug Logging

helix debug flow.yaml

Run with Hot Reload

Watch files for changes and automatically reload workflows:

helix run --watch flow.yaml
# or short form:
helix run -w flow.yaml

CLI Commands Overview

Command Description
helix run <file\|dir> Run flow definitions (YAML or JSON)
helix run -w <file\|dir> Run with hot reload enabled
helix debug <file\|dir> Run with verbose debug logging
helix validate <file> Validate a flow definition without running it
helix export <file> Export a flow as a Dockerfile
helix components List all available components
helix init <name> Scaffold a new project
helix agent list <file> List all agents in a flow file
helix agent test <file> Test an agent interactively
helix mcp list <file> List MCP servers and exposed tools
helix mcp serve <file> Start MCP servers from a flow file
helix mcp inspect <addr> Inspect a running MCP server's tools
helix eval <file> Run evaluation against agents with a JSONL dataset
helix chat <file> Interactive terminal chat with an agent
helix cost Show token usage and estimated cost
helix version Show version information
helix help Show usage information

Running a Directory

You can point Helix at a directory and it will load all .yaml, .yml, and .json files:

helix run .
helix run flows/

Validating Definitions

Check that your YAML is well-formed before running:

helix validate flow.yaml
# Workflow "chat-agent": OK (trigger: http-server://0.0.0.0:8080/chat, steps: 1)
# Validation passed: 1 workflow(s), 0 connector(s)

Exporting a Dockerfile

Generate a multi-stage Dockerfile for containerized deployment:

helix export flow.yaml --output=Dockerfile
# or print to stdout:
helix export flow.yaml

Adding an HTTP Server with Starlang

You can also build lightweight APIs without an agent using Starlang transforms. Create api-flow.yaml:

workflows:
  - id: api-endpoint
    trigger:
      uri: http-server://0.0.0.0:8080/api/greet
    steps:
      - transform:
          starlang: |
            name = headers.name
            if name == "":
              name = "World"
            result = {"greeting": "Hello, " ++ name ++ "!"}
      - log:
          message: "Greeting served"

Run it:

helix run api-flow.yaml

Test with curl:

curl http://localhost:8080/api/greet
# {"greeting":"Hello, World!"}

curl -H "name: Alice" http://localhost:8080/api/greet
# {"greeting":"Hello, Alice!"}

Content-Based Routing with Choice

workflows:
  - id: order-router
    trigger:
      uri: http-server://0.0.0.0:8080/orders
    steps:
      - choice:
          when:
            - starlang: 'headers.priority == "high"'
              steps:
                - target: direct://high-priority
            - starlang: 'headers.priority == "low"'
              steps:
                - target: direct://low-priority
          otherwise:
            steps:
              - target: direct://default-queue

Using Kafka

workflows:
  - id: kafka-consumer
    trigger:
      uri: kafka://events?brokers=localhost:9092&group=helix-group&autoOffsetReset=earliest
    steps:
      - log:
          message: "Received event from Kafka"
      - transform:
          starlang: |
            data = read(payload, "application/json")
            data["processed_at"] = now()
            result = write(data, "application/json")
      - target: kafka://processed-events?brokers=localhost:9092

Adding Configuration

Create helix.yaml alongside your flow files:

helix:
  name: my-app
  management:
    port: 9090
    enabled: true
  health:
    port: 8081
    enabled: true
  metrics:
    prometheus:
      enabled: true
      port: 9100

The configuration file is automatically loaded when present. See Configuration Reference for full details.

Securing Your Agent

You can protect any workflow -- including agent endpoints -- with declarative authentication using the auth: block. Here is a JWT example:

workflows:
  - id: protected-agent
    trigger:
      uri: http-server://0.0.0.0:8080/api/secure
    auth:
      type: jwt
      jwt:
        secret: "${env:JWT_SECRET}"
        issuer: "https://auth.example.com"
        audience: "my-api"
    steps:
      - transform:
          starlang: |
            claims = properties["auth.claims"]
            result = {"message": "Hello, " ++ claims["sub"] ++ "!"}
      - log:
          message: "Authenticated request served"

Requests without a valid JWT bearer token receive a 401 response. The decoded claims are available as the auth.claims exchange property.

Helix also supports API key, basic, and OAuth2 authentication. See the User Guide Authentication section for all auth types and advanced patterns.

Project Structure

A typical Helix project looks like:

my-project/
  helix.yaml         # framework configuration
  flow.yaml          # workflow and agent definitions
  connectors.yaml    # connector definitions (optional)
  transforms/        # external Starlang scripts (optional)
    normalize.star
    enrich.star

Quick Start: Code Agent with helix chat

The fastest way to get a terminal coding-copilot experience with Helix is the helix chat command. Create a file named code-agent.yaml:

agents:
  - id: code-assistant
    type: react
    model:
      provider: anthropic
      model: claude-sonnet-4-20250514
      api_key: "${env:ANTHROPIC_API_KEY}"
    system_prompt: |
      You are an expert coding assistant. Read files before editing them.
      Use grep to find relevant code. Run tests after making changes.
    memory:
      enabled: true
      type: smart
      max_tokens: 100000
    tools:
      - name: read-file
        type: function
        function: fs.read
        description: Read a file
      - name: write-file
        type: function
        function: fs.write
        description: Write content to a file
      - name: edit-file
        type: function
        function: fs.edit
        description: Apply a targeted edit to a file
      - name: list-dir
        type: function
        function: fs.list
        description: List directory contents
      - name: find-files
        type: function
        function: fs.glob
        description: Find files matching a glob pattern
      - name: search
        type: function
        function: fs.grep
        description: Search file contents with regex
      - name: run
        type: function
        function: shell.exec
        description: Run a shell command
      - name: fetch
        type: function
        function: web.fetch
        description: Fetch a URL as plain text

Launch it:

export ANTHROPIC_API_KEY="sk-ant-..."
helix chat code-agent.yaml --dir ~/my-project

This gives you an interactive terminal session with the agent. It can read files, search code, make edits, and run commands -- all within the ~/my-project directory.

Key features: - Session persistence: your conversation auto-saves to ~/.helix/sessions/ and restores on next launch - SmartMemory: token-aware memory that compresses large tool results to stay within the 100K token budget - Built-in functions: 14 ready-to-use functions (file I/O, shell, web, data parsing, math) -- no Go code needed

Use /tools to list available tools, /clear to reset the conversation, and /exit to quit.

See CLI Reference for all flags and AI Agents Guide for the full function registry.

Quick Start with memx

memx is a high-performance vector database that provides both an Elasticsearch-compatible API and a PostgreSQL-compatible SQL interface. Helix integrates natively with memx for RAG pipelines, vector memory, and direct queries.

Start memx with Docker

docker run -d -p 5433:5433 -p 8080:8080 memx-server

Port 5433 exposes the pgwire (SQL) interface; port 8080 exposes the ES-compatible HTTP API.

RAG Pipeline with memx

Create memx-rag.yaml. With auto-discovery, memx detects column roles from table indexes (HNSW/IVF/DiskANN for embeddings, FULLTEXT for content) -- no id_column, embedding_column, or content_column configuration needed:

pipelines:
  - id: ingest-docs
    source: http-server://0.0.0.0:9090/ingest
    steps:
      - rag-ingest:
          reader: directory
          path: ./documents
          recursive: true
      - rag-chunk:
          strategy: recursive
          chunk_size: 512
          overlap: 64
      - rag-embed:
          provider: openai
          model: text-embedding-3-small
          api_key: "${env:OPENAI_API_KEY}"
      - rag-store:
          store: memx
          connection: "http://localhost:8080"
          database: knowledge_db
          collection: knowledge_base

  - id: search-pipeline
    steps:
      - rag-retrieve:
          strategy: memx_hybrid
          store: memx
          connection: "http://localhost:8080"
          database: knowledge_db
          collection: knowledge_base
          top_k: 5

agents:
  - id: search-agent
    type: react
    trigger: http-server://0.0.0.0:9090/search
    model:
      provider: openai
      model: gpt-4o
      api_key: "${env:OPENAI_API_KEY}"
    system_prompt: |
      You are a research assistant. Use the search tool to find
      relevant information and answer questions accurately.
    tools:
      - name: search_docs
        type: tool
        tool_id: search-pipeline
        description: "Search the knowledge base for relevant documents"
        parameters:
          type: object
          properties:
            query:
              type: string
              description: "Search query"

memx retrieve returns raw []map[string]any with all table columns (embedding excluded, _score included) -- the agent receives raw JSON, no Chunk wrapping. Use Starlang transforms downstream if reshaping is needed.

Agent with memx-backed Vector Memory

agents:
  - id: assistant
    type: react
    trigger: http-server://0.0.0.0:9090/chat
    model:
      provider: openai
      model: gpt-4o
      api_key: "${env:OPENAI_API_KEY}"
    system_prompt: "You are a helpful assistant with long-term memory."
    memory:
      enabled: true
      type: vector
      vector:
        store: memx
        connection: "http://localhost:8080"
        collection: agent_memory
        embed_provider: openai
        embed_model: text-embedding-3-small
        embed_api_key: "${env:OPENAI_API_KEY}"

Run it:

export OPENAI_API_KEY="sk-..."
helix run memx-rag.yaml

Next Steps