GitHub - o3-cloud/agentman: Agentman: A tool for building and managing AI agents

Agentman is the first Docker-like tool for building, managing, and deploying AI agents using the Model Context Protocol (MCP). Transform your AI workflows with intuitive Agentfile syntax that lets you define complex multi-agent systems and deploy them as production-ready containers in minutes, not hours.

📚 Table of Contents

Tip

AI-Driven Development: This project showcases the future of software development - almost entirely coded by Claude Sonnet 4 + AI Agents, demonstrating how AI can handle complex architecture design, implementation, comprehensive testing, and documentation.

⚡ Quick Start

Get your first AI agent running in under 2 minutes:

# 1. Install Agentman

# From PyPI (recommended)
pip install agentman-mcp

# Or, install the latest version from GitHub using uv
uv tool install git+https://github.com/o3-cloud/agentman.git@main#egg=agentman-mcp

# 2. Create and run your first agent
mkdir my-agent && cd my-agent
agentman run --from-agentfile -t my-agent .

That's it! Your agent is now running in a Docker container.

🧠 Framework Support

Agentman supports two powerful AI agent frameworks:

FastAgent (Default)

Decorator-based approach with @fast.agent() and @fast.chain()
MCP-first design with seamless tool integration
Production-ready with comprehensive logging and monitoring
Configuration: Uses fastagent.config.yaml and fastagent.secrets.yaml

Agno

Class-based approach with Agent() and Team()
Multi-model support for OpenAI, Anthropic, and more
Rich tool ecosystem with built-in integrations
Configuration: Uses environment variables via .env file

Choose your framework:

FRAMEWORK fast-agent  # Recommended for production MCP workflows
FRAMEWORK agno        # Great for research and multi-model experiments

Feature	FastAgent (Default)	Agno
Best For	Production MCP workflows	Research & experimentation
API Style	Decorator-based (`@fast.agent()`)	Class-based (`Agent()`, `Team()`)
Configuration	YAML files	Environment variables (.env)
Model Focus	MCP-optimized models	Multi-provider support
Tool Integration	MCP-first design	Rich ecosystem
Learning Curve	Moderate	Easy

Prerequisites

Python 3.10+ installed on your system
Docker installed and running
Basic understanding of AI agents and MCP concepts

🏗️ Build Your First Agent

Create a URL-to-social-media pipeline in 5 minutes:

1. Create a project directory:

mkdir url-to-social && cd url-to-social

2. Create an Agentfile:

Option A: Dockerfile format (traditional)

FROM ghcr.io/o3-cloud/agentman/base:main
MODEL anthropic/claude-3-sonnet

# Add web search capability
MCP_SERVER fetch
COMMAND uvx
ARGS mcp-server-fetch
TRANSPORT stdio

# Define your agents
AGENT url_analyzer
INSTRUCTION Given a URL, provide a comprehensive summary of the content
SERVERS fetch

AGENT social_writer
INSTRUCTION Transform any text into a compelling 280-character social media post

# Chain them together
CHAIN content_pipeline
SEQUENCE url_analyzer social_writer

CMD ["python", "agent.py"]

Option B: YAML format (recommended for complex workflows)

# Agentfile.yml
apiVersion: v1
kind: Agent
base:
  model: anthropic/claude-3-sonnet
mcp_servers:
- name: fetch
  command: uvx
  args:
  - mcp-server-fetch
  transport: stdio
agents:
- name: url_analyzer
  instruction: Given a URL, provide a comprehensive summary of the content
  servers:
  - fetch
- name: social_writer
  instruction: Transform any text into a compelling 280-character social media post
chains:
- name: content_pipeline
  sequence:
  - url_analyzer
  - social_writer

3. Build and run:

agentman run --from-agentfile -t url-to-social .

4. Test it! Provide a URL when prompted and watch your agent fetch content and create a social media post.

💡 Pro Tip: Add Default Prompts

Make your agent start automatically with a predefined task:

echo "Analyze https://github.com/yeahdongcn/agentman and create a social post about it" > prompt.txt
agentman run --from-agentfile -t auto-agent .

Your agent will now execute this prompt automatically on startup! 🎉

🚀 Overview

Agentman brings the simplicity of Docker to AI agent development. Just as Docker revolutionized application deployment, Agentman revolutionizes AI agent development with:

Familiar workflow: build, run, and deploy like any container
Declarative syntax: Simple Agentfile configuration
Production-ready: Optimized containers with dependency management
MCP-native: First-class support for Model Context Protocol

The intuitive Agentfile syntax lets you focus on designing intelligent workflows while Agentman handles the complex orchestration, containerization, and deployment automatically.

Important

Agentman supports both FastAgent (production-focused) and Agno (research-focused) frameworks, with full support for Anthropic Claude and OpenAI GPT models.

🚀 See It In Action

🎬 Video Demonstrations

Framework	Use Case	Demo
FastAgent	Social Media Pipeline
Agno	GitHub Profile Analysis

In these demos you'll see:

Creating multi-agent workflows with simple Agentfile syntax
Building and running agents with one command
Real-time agent execution with URL fetching and content generation
Streaming output and reasoning steps

🎯 Why Choose Agentman?

Capability	Benefit
🐳 Docker-Like Interface	Familiar `build` and `run` commands - no learning curve
📝 Declarative `Agentfile`	Define complex workflows in simple, readable syntax
🔗 Multi-Agent Orchestration	Chains, routers, and parallel execution out-of-the-box
🔌 Native MCP Integration	Zero-configuration access to 50+ MCP servers
📄 Smart Prompt Loading	Auto-detect and load prompts from `prompt.txt`
🚀 Production-Ready	Optimized Docker containers with dependency management
🔐 Secure Secrets	Environment-based secret handling with templates
🧪 Battle-Tested	91%+ test coverage ensures reliability

✨ Environment Variable Expansion in Agentfiles

Now you can use environment variables directly in your Agentfile and Agentfile.yml for more flexible and secure configurations.

Usage examples:

Agentfile format

# Agentfile format
SECRET ALIYUN_API_KEY ${ALIYUN_API_KEY}
MCP_SERVER github-mcp-server
ENV GITHUB_PERSONAL_ACCESS_TOKEN ${GITHUB_TOKEN}

YAML format

# YAML format
secrets:
  - name: ALIYUN_API_KEY
    value: ${ALIYUN_API_KEY}
mcp_servers:
  - name: github-mcp-server
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: ${GITHUB_TOKEN}

🌟 What Makes Agentman Different?

Traditional AI Development:

# Multiple config files, complex setup, manual orchestration
npm install langchain
pip install openai anthropic
# Configure tools manually...
# Write orchestration code...
# Handle deployment yourself...

With Agentman:

# One tool, one config file, one command
pip install agentman-mcp
echo "AGENT helper\nINSTRUCTION Help users" > Agentfile
agentman run --from-agentfile .

Result: Production-ready containerized agents in minutes, not days.

Creating an Agentfile with multi-agent workflow
Building and running the agent with one command
Real-time agent execution with URL fetching and social media post generation

📖 Usage Guide

🔨 Building Agents

Create agent applications from an Agentfile using familiar Docker-like commands:

# Basic build in current directory
agentman build .

# Custom Agentfile and output directory
agentman build -f MyAgentfile -o ./output .

# Build and create Docker image
agentman build --build-docker -t my-agent:v1.0 .

📁 Generated Output:

agent.py - Main application with runtime logic
fastagent.config.yaml / .env - Framework configuration
Dockerfile - Optimized multi-stage container
requirements.txt - Auto-generated dependencies
prompt.txt - Default prompt (if exists)

🏃 Running Agents

Deploy and execute your agents with flexible options:

# Run existing Docker image
agentman run my-agent:latest

# Build and run from Agentfile (recommended for development)
agentman run --from-agentfile ./my-project

# Interactive mode with port forwarding
agentman run -it -p 8080:8080 my-agent:latest

# Clean up automatically when done
agentman run --rm my-agent:latest

🏗️ Agentfile Reference

The Agentfile uses a Docker-like syntax to define your agent applications. Here's a comprehensive reference:

Base Configuration

FROM ghcr.io/o3-cloud/agentman/base:main   # Base image
FRAMEWORK fast-agent                   # AI framework (fast-agent or agno)
MODEL anthropic/claude-3-sonnet        # Default model for agents
EXPOSE 8080                            # Expose ports
CMD ["python", "agent.py"]             # Container startup command

📄 File Format Support

Agentman supports two file formats for defining your agent configurations:

Dockerfile-style Agentfile (Default)

The traditional Docker-like syntax using an Agentfile without extension:

FROM ghcr.io/o3-cloud/agentman/base:main
MODEL anthropic/claude-3-sonnet
FRAMEWORK fast-agent

AGENT assistant
INSTRUCTION You are a helpful AI assistant

YAML Agentfile

Modern declarative YAML format using Agentfile.yml or Agentfile.yaml:

apiVersion: v1
kind: Agent
base:
  model: anthropic/claude-3-sonnet
  framework: fast-agent
agents:
- name: assistant
  instruction: You are a helpful AI assistant

Key advantages of YAML format:

🎯 Better structure for complex multi-agent configurations
📝 Native support for lists, nested objects, and comments
🔍 IDE support with syntax highlighting and validation
📊 Clear hierarchy for routers, chains, and orchestrators

Usage:

Build: agentman build . (auto-detects format)
Run: agentman run --from-agentfile . (works with both formats)
Convert: Agentman can automatically convert between formats

Framework Configuration

Choose between supported AI agent frameworks:

FRAMEWORK fast-agent  # Default: FastAgent framework
FRAMEWORK agno        # Alternative: Agno framework

Framework Differences:

Feature	FastAgent	Agno
API Style	Decorator-based (`@fast.agent()`)	Class-based (`Agent()`)
Configuration	YAML files	Environment variables
Model Support	MCP-optimized models	Multi-provider support
Tool Integration	MCP-first	Rich ecosystem
Use Case	Production MCP workflows	Research & experimentation

MCP Servers

Define external MCP servers that provide tools and capabilities:

Dockerfile format:

MCP_SERVER filesystem
COMMAND uvx
ARGS mcp-server-filesystem
TRANSPORT stdio
ENV PATH_PREFIX /app/data

YAML format:

mcp_servers:
- name: filesystem
  command: uvx
  args:
  - mcp-server-filesystem
  transport: stdio
  env:
    PATH_PREFIX: /app/data

Agent Definitions

Create individual agents with specific roles and capabilities:

Dockerfile format:

AGENT assistant
INSTRUCTION You are a helpful AI assistant specialized in data analysis
SERVERS filesystem brave
MODEL anthropic/claude-3-sonnet
USE_HISTORY true
HUMAN_INPUT false

YAML format:

agents:
- name: assistant
  instruction: You are a helpful AI assistant specialized in data analysis
  servers:
  - filesystem
  - brave
  model: anthropic/claude-3-sonnet
  use_history: true
  human_input: false

Structured Output Format

Define validation schemas for agent outputs using JSONSchema:

Dockerfile format:

AGENT data_analyzer
INSTRUCTION Analyze data and return structured results
OUTPUT_FORMAT json_schema {"type":"object","properties":{"status":{"type":"string","enum":["success","error"]},"data":{"type":"object"}},"required":["status","data"]}

AGENT file_processor
INSTRUCTION Process files according to predefined schema
OUTPUT_FORMAT schema_file ./schemas/processing_schema.yaml

YAML format:

agents:
- name: data_analyzer
  instruction: Analyze data and return structured results
  output_format:
    type: json_schema
    schema:
      type: object
      properties:
        status:
          type: string
          enum: [success, error]
        data:
          type: object
          properties:
            count:
              type: number
            items:
              type: array
              items:
                type: string
      required: [status, data]

- name: file_processor
  instruction: Process files according to predefined schema
  output_format:
    type: schema_file
    file: ./schemas/processing_schema.yaml

Schema Types:

json_schema: Inline JSONSchema definition in JSON format (Dockerfile) or YAML format (YAML Agentfile)
schema_file: Reference to external .json or .yaml schema file

Benefits:

Type Safety: Validate agent outputs against predefined schemas
Documentation: Schemas serve as output documentation
IDE Support: JSONSchema provides autocomplete and validation
Standards: Uses standard JSONSchema specification

Workflow Orchestration

Chains (Sequential processing):

Dockerfile format:

CHAIN data_pipeline
SEQUENCE data_loader data_processor data_exporter
CUMULATIVE true

YAML format:

chains:
- name: data_pipeline
  sequence:
  - data_loader
  - data_processor
  - data_exporter
  cumulative: true

Parallels (Concurrent execution with fan-out/fan-in):

Dockerfile format:

PARALLEL translate_workflow
FAN_OUT translate_fr translate_de translate_es
FAN_IN aggregator
INSTRUCTION Coordinate parallel translation tasks
INCLUDE_REQUEST true
DEFAULT false

YAML format:

parallels:
- name: translate_workflow
  fan_out:
  - translate_fr
  - translate_de
  - translate_es
  fan_in: aggregator
  instruction: Coordinate parallel translation tasks
  include_request: true
  default: false

Routers (Conditional routing):

Dockerfile format:

ROUTER query_router
AGENTS sql_agent api_agent file_agent
INSTRUCTION Route queries based on data source type

YAML format:

routers:
- name: query_router
  agents:
  - sql_agent
  - api_agent
  - file_agent
  instruction: Route queries based on data source type

Orchestrators (Complex coordination):

Dockerfile format:

ORCHESTRATOR project_manager
AGENTS developer tester deployer
PLAN_TYPE iterative
PLAN_ITERATIONS 5
HUMAN_INPUT true

YAML format:

orchestrators:
- name: project_manager
  agents:
  - developer
  - tester
  - deployer
  plan_type: iterative
  plan_iterations: 5
  human_input: true

Secrets Management

Secure handling of API keys and sensitive configuration:

Dockerfile format:

# Environment variable references
SECRET OPENAI_API_KEY
SECRET ANTHROPIC_API_KEY

# Inline values (for development only)
SECRET DATABASE_URL postgresql://localhost:5432/mydb

# Grouped secrets with multiple values
SECRET CUSTOM_API
API_KEY your_key_here
BASE_URL https://api.example.com
TIMEOUT 30

YAML format:

secrets:
- name: OPENAI_API_KEY
  values: {}  # Environment variable reference
- name: ANTHROPIC_API_KEY
  values: {}
- name: DATABASE_URL
  values:
    DATABASE_URL: postgresql://localhost:5432/mydb
- name: CUSTOM_API
  values:
    API_KEY: your_key_here
    BASE_URL: https://api.example.com
    TIMEOUT: 30

Default Prompt Support

Agentman automatically detects and integrates prompt.txt files, providing zero-configuration default prompts for your agents.

🌟 Key Features

🔍 Automatic Detection: Simply place a prompt.txt file in your project root
🐳 Docker Integration: Automatically copied into containers during build
🔄 Runtime Loading: Agent checks for and loads prompt content at startup
⚡ Zero Configuration: No Agentfile modifications required

📋 How It Works

Build Time: Agentman scans your project directory for prompt.txt
Container Build: If found, the file is automatically copied to the Docker image
Runtime: Generated agent checks for the file and loads its content
Execution: Prompt content is passed to await agent(prompt_content) at startup

📁 Project Structure Example

my-agent/
├── Agentfile                # Agent configuration
├── prompt.txt              # ← Your default prompt (auto-loaded)
└── agent/                  # ← Generated output directory
    ├── agent.py            #   Generated agent with prompt loading logic
    ├── prompt.txt          #   ← Copied during build process
    ├── Dockerfile          #   Contains COPY prompt.txt instruction
    └── requirements.txt    #   Python dependencies

💡 Example Prompts

Task-Specific Prompt:

Analyze the latest GitHub releases for security vulnerabilities and generate a summary report.

User-Specific Prompt:

I am a GitHub user with the username "yeahdongcn" and I need help updating my GitHub profile information.

Complex Workflow Prompt:

Process the following workflow:
1. Clone the repository https://github.com/ollama/ollama
2. Checkout the latest release tag
3. Analyze the changelog for breaking changes
4. Generate a migration guide

🛠️ Generated Logic

When prompt.txt exists, Agentman automatically generates this logic in your agent.py:

import os

# Check for default prompt file
prompt_file = "prompt.txt"
if os.path.exists(prompt_file):
    with open(prompt_file, 'r', encoding='utf-8') as f:
        prompt_content = f.read().strip()
    if prompt_content:
        await agent(prompt_content)

This ensures your agent automatically executes the default prompt when the container starts.

🎯 Example Projects

All example projects in the /examples directory include both Dockerfile-style Agentfile and YAML format Agentfile.yml for comparison and learning. You can use either format to build and run the examples.

1. GitHub Profile Manager (with Default Prompt)

A comprehensive GitHub profile management agent that automatically loads a default prompt.

Project Structure:

github-profile-manager/
├── Agentfile           # Dockerfile format
├── Agentfile.yml       # YAML format (same functionality)
├── prompt.txt          # Default prompt automatically loaded
└── agent/              # Generated files
    ├── agent.py
    ├── prompt.txt      # Copied during build
    └── ...

Build with either format:

# Using Dockerfile format
agentman build -f Agentfile .

# Using YAML format  
agentman build -f Agentfile.yml .

# Auto-detection (picks first available)
agentman build .

prompt.txt:

I am a GitHub user with the username "yeahdongcn" and I need help updating my GitHub profile information.

Key Features:

Multi-agent chain for profile data collection, generation, and updating
Automatic prompt loading from prompt.txt
Integration with GitHub MCP server and fetch capabilities

2. GitHub Repository Maintainer

A specialized agent for maintaining GitHub repositories with automated release management.

Project Structure:

github-maintainer/
├── Agentfile
├── prompt.txt          # Default task: "Clone https://github.com/ollama/ollama and checkout the latest release tag."
└── agent/              # Generated files

Key Features:

Release checking and validation
Repository cloning and management
Automated maintenance workflows

3. URL-to-Social Content Pipeline

A simple yet powerful content processing chain for social media.

Project Structure:

chain-ollama/
├── Agentfile
└── agent/              # Generated files

Key Features:

URL content fetching and summarization
Social media post generation (280 characters, no hashtags)
Sequential agent chain processing

4. Advanced Multi-Agent System

Example of a more complex multi-agent system with routers and orchestrators:

FROM ghcr.io/o3-cloud/agentman/base:main
MODEL anthropic/claude-3-sonnet

MCP_SERVER database
COMMAND uvx
ARGS mcp-server-postgres

AGENT classifier
INSTRUCTION Classify customer inquiries by type and urgency
SERVERS database

AGENT support_agent
INSTRUCTION Provide helpful customer support responses
SERVERS database

AGENT escalation_agent
INSTRUCTION Handle complex issues requiring human intervention
HUMAN_INPUT true

ROUTER support_router
AGENTS support_agent escalation_agent
INSTRUCTION Route based on inquiry complexity and urgency

5. Structured Output Example

Demonstrates JSONSchema validation for agent outputs with both inline and external schema definitions.

Project Structure:

structured-output-example/
├── Agentfile           # Dockerfile format with JSON schema
├── Agentfile.yml       # YAML format with inline schema
├── schemas/            # External schema files
│   ├── extraction_schema.yaml
│   └── simple_schema.json
└── agent/              # Generated files

Key Features:

Inline JSONSchema: Define validation schemas directly in YAML format
External Schema Files: Reference separate .json or .yaml schema files
Type Safety: Validate agent outputs against predefined schemas
Both Format Support: Works with Dockerfile and YAML Agentfiles

Example Agent with Output Format:

agents:
  - name: sentiment_analyzer
    instruction: Analyze sentiment and return structured results
    output_format:
      type: json_schema
      schema:
        type: object
        properties:
          sentiment:
            type: string
            enum: [positive, negative, neutral]
          confidence:
            type: number
            minimum: 0
            maximum: 1
        required: [sentiment, confidence]

6. Parallel Translation Workflow

Demonstrates concurrent agent execution using the @fast.parallel decorator with fan-out/fan-in patterns for multilingual content processing.

Project Structure:

parallel-translation/
├── Agentfile           # Dockerfile format with parallel workflow
├── Agentfile.yml       # YAML format (same functionality)
└── agent/              # Generated files
    ├── agent.py
    └── ...

Key Features:

Concurrent Translation: Parallel execution of multiple translation agents (French, German, Spanish)
Fan-out Pattern: Distributes content to multiple translation agents simultaneously
Chain Integration: Combines URL fetching → social media generation → parallel translation
Both Format Support: Works with Dockerfile and YAML Agentfile formats

Workflow:

URL Fetcher Agent: Summarizes content from provided URLs
Social Media Agent: Creates 280-character social media posts
Parallel Translation: Simultaneously translates to French, German, and Spanish
Chain Coordination: url_fetcher → social_media → translate (parallel workflow)

Example Usage:

# Build and run with auto-detection
agentman build examples/parallel-translation
agentman run --from-agentfile examples/parallel-translation

# Provide a URL when prompted to see the full pipeline in action

This example showcases how parallel workflows can significantly reduce processing time for tasks that can be executed concurrently, while maintaining clean separation of concerns between different agents.

🔧 Advanced Configuration

Custom Base Images

FROM python:3.11-slim
MODEL openai/gpt-4

# Your custom setup...
RUN apt-get update && apt-get install -y curl

AGENT custom_agent
INSTRUCTION Specialized agent with custom environment

Environment Variables

MCP_SERVER api_server
COMMAND python
ARGS -m my_custom_server
ENV API_TIMEOUT 30
ENV RETRY_COUNT 3
ENV DEBUG_MODE false

Multi-Model Setup

AGENT fast_responder
MODEL anthropic/claude-3-haiku
INSTRUCTION Handle quick queries

AGENT deep_thinker
MODEL anthropic/claude-3-opus
INSTRUCTION Handle complex analysis tasks

📁 Project Structure

agentman/
├── src/agentman/           # Core source code
│   ├── __init__.py
│   ├── cli.py             # Command-line interface
│   ├── agent_builder.py   # Agent building logic
│   ├── agentfile_parser.py # Agentfile parsing
│   └── common.py          # Shared utilities
├── examples/              # Example projects
│   ├── github-profile-manager/
│   ├── github-maintainer/
│   ├── chain-ollama/
│   └── chain-aliyun/
├── tests/                 # Comprehensive test suite
├── docker/               # Docker base images
└── README.md             # This file

🏗️ Building from Source

git clone https://github.com/o3-cloud/agentman.git
cd agentman

# Install
make install

🧪 Testing

Agentman includes comprehensive test suites with high coverage:

# Run all tests
make test

# Run tests with coverage
make test-cov

Test Coverage

91%+ overall coverage across core modules
Agent Builder: Comprehensive tests for agent generation and Docker integration
Agentfile Parser: Complete syntax parsing and validation tests
Prompt.txt Support: Full coverage of automatic prompt detection and loading
Dockerfile Generation: Tests for container build optimization

🤝 Contributing

We welcome contributions! This project serves as a showcase of AI-driven development, being almost entirely coded by Claude Sonnet 4 + AI Agents. This demonstrates how AI can handle complex software development tasks including architecture design, implementation, testing, and documentation.

Development Workflow

Fork and clone the repository
Create a feature branch from main
Write tests for new functionality (AI-generated tests achieve 91%+ coverage)
Ensure tests pass with make test
Format code with make format
Submit a pull request with clear description

Areas for Contribution

🔌 New MCP server integrations
🤖 Additional agent workflow patterns
📚 Documentation and examples
🧪 Test coverage improvements
🐛 Bug fixes and optimizations

📋 System Requirements

Python: 3.10+ (supports 3.10, 3.11, 3.12, 3.13)
Docker: Required for containerization and running agents
Operating System: Unix-like systems (Linux, macOS, WSL2)
Memory: 2GB+ RAM recommended for multi-agent workflows
Storage: 1GB+ available space for base images and dependencies

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

🤖 AI-Powered Development: This project showcases the future of software development - almost entirely coded by Claude Sonnet 4 + AI Agents, demonstrating how AI can handle complex architecture design, implementation, comprehensive testing, and documentation
🏗️ Built on FastAgent: Agentman leverages the fast-agent framework as its foundation, providing robust agent infrastructure and seamless MCP integration
🐳 Inspired by Podman: Just as Podman provides a Docker-compatible interface for containers, Agentman brings familiar containerization concepts to AI agent management
🧪 Test-Driven Excellence: Achieved 91%+ test coverage through AI-driven test generation, ensuring reliability and maintainability
🌟 Community-Driven: Built with the vision of making AI agent development accessible to everyone

🚀 Ready to Build the Future of AI?

Transform your ideas into production-ready AI agents in minutes

⚡ Quick Start • 🎯 Examples • 🤝 Contribute • 📚 Docs

Join the AI agent revolution - build smarter, deploy faster ✨

Community & Stats: