agentmap

AgentMap

Build and deploy LangGraph agentic workflows from CSV files.

AgentMap is a declarative orchestration framework that transforms simple CSV files into powerful AI agent workflows. Instead of writing hundreds of lines of boilerplate code for multi-agent systems, you define entire workflows in a spreadsheet format.

Why AgentMap?

• Declarative Workflows: Define complex multi-agent workflows in readable CSV format
• Rapid Prototyping: Iterate quickly without recompiling or redeploying
• Multiple LLM Providers: Built-in support for OpenAI, Anthropic Claude, and Google Gemini
• Flexible Deployment: Run from CLI, embed in Python code, or serve via FastAPI
• Production Ready: Includes execution tracking, memory management, and intelligent LLM routing

Installation

# Basic installation
pip install agentmap

# With LLM support (OpenAI, Anthropic, Google)
pip install agentmap[llm]

# With storage support (Firebase, FAISS, document processing)
pip install agentmap[storage]

# Everything included
pip install agentmap[all]

Requirements: Python 3.11+

Quick Start

1. Initialize Configuration

agentmap init-config

This creates three files in your current directory:

2. Configure Your LLM Provider

Edit agentmap_config.yaml and add your API key:

llm:
  openai:
    api_key: "your-openai-key"  # Or use env var: OPENAI_API_KEY
    model: "gpt-4o-mini"

  anthropic:
    api_key: "your-anthropic-key"  # Or use env var: ANTHROPIC_API_KEY
    model: "claude-sonnet-4-6"

  google:
    api_key: "your-google-key"  # Or use env var: GOOGLE_API_KEY
    model: "gemini-2.5-flash"

You can also set API keys via environment variables:

export OPENAI_API_KEY="your-key"
export ANTHROPIC_API_KEY="your-key"
export GOOGLE_API_KEY="your-key"

3. Run a Sample Workflow

# Run the hello world example
agentmap run hello_world.csv

# With formatted output
agentmap run hello_world.csv --pretty

# With initial state
agentmap run hello_world.csv --state '{"name": "Alice"}' --pretty

Configuration Reference

Main Configuration (agentmap_config.yaml)

Path Configuration:

paths:
  custom_agents: "agentmap_data/custom_agents"
  functions: "agentmap_data/custom_functions"
  csv_repository: "agentmap_data/workflows"

Memory Configuration:

memory:
  enabled: true
  default_type: "buffer_window"  # buffer, buffer_window, summary, token_buffer
  buffer_window_size: 5
  max_token_limit: 2000

Storage Configuration (agentmap_config_storage.yaml)

core:
  base_directory: "agentmap_data/data"

csv:
  enabled: true
  auto_create_files: true
  collections:
    users: "csv/users.csv"
    products: "csv/products.csv"

json:
  enabled: true
  auto_create_files: true

Workflow CSV Format

Workflows are defined in CSV files with these columns:

Example (hello_world.csv):

graph_name,node_name,agent_type,next_node,on_failure,prompt,input_fields,output_field
HelloWorld,Start,input,PrintResult,HandleError,"Hello world! What is your name?",,name
HelloWorld,PrintResult,echo,,,"Hello {name}. Welcome to AgentMap!",name,result
HelloWorld,HandleError,echo,,,Error occurred

CLI Commands

Workflow Execution

# Run a workflow
agentmap run my_workflow.csv
agentmap run my_workflow.csv --state '{"input": "value"}' --pretty --verbose

# Resume a suspended workflow
agentmap resume <thread_id> <action> --data '{"key": "value"}'

Configuration & Setup

# Initialize configuration files
agentmap init-config
agentmap init-config --force  # Overwrite existing

# Initialize API keys
agentmap auth init --config agentmap_config.yaml

# Check system dependencies
agentmap diagnose

# Refresh provider cache
agentmap refresh --force

Validation & Scaffolding

# Validate CSV structure
agentmap validate workflow.csv

# Generate agent templates
agentmap scaffold workflow.csv --output agents/ --overwrite

HTTP Server

# Start the API server
agentmap serve --host 0.0.0.0 --port 8000

# With auto-reload for development
agentmap serve --port 8000 --reload

API documentation available at http://localhost:8000/docs

Interfaces

AgentMap provides three ways to execute workflows:

1. Command Line Interface

Best for quick testing and scripting:

agentmap run my_workflow.csv --state '{"user_id": 123}' --pretty

2. Python API

Best for embedding in applications:

from agentmap import ensure_initialized, run_workflow

# Initialize once at startup
ensure_initialized()

# Execute a workflow
result = run_workflow(
    graph_name="my_workflow::MyGraph",
    inputs={"user_message": "Hello"},
    config_file="agentmap_config.yaml"
)

if result.get("success"):
    print(result.get("outputs"))

Available Functions:

from agentmap import (
    ensure_initialized,   # Initialize the runtime
    run_workflow,         # Execute a workflow
    resume_workflow,      # Resume suspended execution
    list_graphs,          # List available workflows
    inspect_graph,        # Get graph structure
    validate_workflow,    # Validate CSV
)

3. FastAPI HTTP Server

Best for microservices and REST APIs:

Start the Server:

agentmap serve --host 0.0.0.0 --port 8000

Execute via HTTP:

# Execute a workflow
curl -X POST "http://localhost:8000/execution/my_workflow.csv%3A%3AMyGraph" \
  -H "Content-Type: application/json" \
  -d '{"inputs": {"message": "Hello"}}'

# List workflows
curl http://localhost:8000/workflows

# Resume suspended execution
curl -X POST http://localhost:8000/resume/<thread_id> \
  -H "Content-Type: application/json" \
  -d '{"action": "approve", "data": {}}'

Embed in Existing FastAPI App:

from fastapi import FastAPI
from agentmap.deployment.http.api.server import create_sub_application

app = FastAPI(title="My Application")

# Mount AgentMap routes
agentmap_app = create_sub_application(
    config_file="agentmap_config.yaml",
    prefix="/agentmap"
)
app.mount("/agentmap", agentmap_app)

# AgentMap endpoints now at /agentmap/execute, /agentmap/workflows, etc.

Built-in Agent Types

AgentMap includes 20+ agent types:

Example: LLM Chatbot

graph_name,node_name,agent_type,input_fields,output_field,next_node,prompt
ChatBot,GetInput,input,,user_input,Respond,"How can I help you?"
ChatBot,Respond,openai,user_input|chat_memory,response,GetInput,"You are a helpful assistant. User says: {user_input}"

Run it:

agentmap run chatbot.csv --pretty

Example: Conditional Workflow

graph_name,node_name,agent_type,input_fields,output_field,next_node,on_failure,prompt
ReviewFlow,Start,input,,request,Classify,,"Enter your request:"
ReviewFlow,Classify,branching,request,decision,Approve,Reject,
ReviewFlow,Approve,default,request,result,,,"Request approved: {request}"
ReviewFlow,Reject,default,request,result,,,"Request rejected: {request}"

Useful Commands

# Check version
agentmap --version

# Get help
agentmap --help
agentmap run --help

Project Links

• Documentation: https://jwwelbor.github.io/AgentMap
• Repository: https://github.com/jwwelbor/AgentMap
• Issue Tracker: https://github.com/jwwelbor/AgentMap/issues
• Changelog: https://github.com/jwwelbor/AgentMap/blob/main/CHANGELOG.md

License

This project is licensed under the MIT License.