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

• [⚡ Quick Start](#-quick-start)
• [🧠 Framework Support](#-framework-support)
• [🏗️ Build Your First Agent](#️-build-your-first-agent)
• [🎯 Why Choose Agentman?](#-why-choose-agentman)
• [🚀 Quick Demo](#-quick-demo)
• [📖 Detailed Usage](#-detailed-usage)
• [🏗️ Agentfile Reference](#️-agentfile-reference)
• [🎯 Example Projects](#-example-projects)
• [🔧 Advanced Configuration](#-advanced-configuration)
• [🧪 Testing](#-testing)
• [🤝 Contributing](#-contributing)
• [📋 System Requirements](#-system-requirements)

> [!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
pip install 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:

FROM yeahdongcn/agentman-base:latest
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"]

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 | [](https://www.youtube.com/watch?v=P4bRllSbNX8) | | Agno | GitHub Profile Analysis | [](https://www.youtube.com/watch?v=UP3Vmij89Yo) |

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 |

🌟 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 yeahdongcn/agentman-base:latest   # 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

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:

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

Agent Definitions

Create individual agents with specific roles and capabilities:

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

Workflow Orchestration

Chains (Sequential processing):

CHAIN data_pipeline
SEQUENCE data_loader data_processor data_exporter
CUMULATIVE true

Routers (Conditional routing):

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

Orchestrators (Complex coordination):

ORCHESTRATOR 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:

# 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

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

1. Build Time: Agentman scans your project directory for prompt.txt
2. Container Build: If found, the file is automatically copied to the Docker image
3. Runtime: Generated agent checks for the file and loads its content
4. 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

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
├── prompt.txt          # Default prompt automatically loaded
└── agent/              # Generated files
    ├── agent.py
    ├── prompt.txt      # Copied during 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 yeahdongcn/agentman-base:latest
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

🔧 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/cla

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [yeahdongcn](https://github.com/yeahdongcn)
- **Source:** [yeahdongcn/agentman](https://github.com/yeahdongcn/agentman)
- **License:** MIT

Install and usage instructions live in the source repository linked above.