Merge pull request #2 from o3-cloud/claude/issue-1-20250714_144116

feat: Add YAML format support for Agentfile configurations

Author: AgentO3

.github/workflows/test.yml

@@ -0,0 +1,77 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Test Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v4
+      with:
+        enable-cache: true
+
+    - name: Install dependencies
+      run: |
+        uv sync --extra dev
+
+    - name: Run tests with coverage
+      run: |
+        uv run pytest --cov=src/agentman --cov-report=xml --cov-report=term-missing
+
+    - name: Upload coverage to Codecov
+      uses: codecov/codecov-action@v4
+      with:
+        file: ./coverage.xml
+        fail_ci_if_error: false
+      env:
+        CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+
+  lint:
+    name: Code Quality
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python 3.11
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.11"
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v4
+      with:
+        enable-cache: true
+
+    - name: Install dependencies
+      run: |
+        uv sync --extra dev
+
+    - name: Run black
+      run: |
+        uv run black --check src tests
+
+    - name: Run isort
+      run: |
+        uv run isort --check-only src tests
+
+    - name: Run pylint
+      run: |
+        uv run pylint src/agentman

.gitignore

@@ -13,4 +13,5 @@ htmlcov/
 .coverage
 
 # Generated files
-agent/
+agent/
+build/

README.md

@@ -101,6 +101,8 @@ mkdir url-to-social && cd url-to-social
 ```
 
 **2. Create an `Agentfile`:**
+
+*Option A: Dockerfile format (traditional)*
 ```dockerfile
 FROM yeahdongcn/agentman-base:latest
 MODEL anthropic/claude-3-sonnet
@@ -126,6 +128,33 @@ SEQUENCE url_analyzer social_writer
 CMD ["python", "agent.py"]
 ```
 
+*Option B: YAML format (recommended for complex workflows)*
+```yaml
+# 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:**
 ```bash
 agentman run --from-agentfile -t url-to-social .
@@ -267,6 +296,47 @@ 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:
+
+```dockerfile
+FROM yeahdongcn/agentman-base:latest
+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`:
+
+```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:
@@ -290,6 +360,7 @@ FRAMEWORK agno        # Alternative: Agno framework
 
 Define external MCP servers that provide tools and capabilities:
 
+**Dockerfile format:**
 ```dockerfile
 MCP_SERVER filesystem
 COMMAND uvx
@@ -298,10 +369,23 @@ TRANSPORT stdio
 ENV PATH_PREFIX /app/data
 ```
 
+**YAML format:**
+```yaml
+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:**
 ```dockerfile
 AGENT assistant
 INSTRUCTION You are a helpful AI assistant specialized in data analysis
@@ -311,23 +395,64 @@ USE_HISTORY true
 HUMAN_INPUT false
 ```
 
+**YAML format:**
+```yaml
+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
+```
+
 ### Workflow Orchestration
 
 **Chains** (Sequential processing):
+
+*Dockerfile format:*
 ```dockerfile
 CHAIN data_pipeline
 SEQUENCE data_loader data_processor data_exporter
 CUMULATIVE true
 ```
 
+*YAML format:*
+```yaml
+chains:
+- name: data_pipeline
+  sequence:
+  - data_loader
+  - data_processor
+  - data_exporter
+  cumulative: true
+```
+
 **Routers** (Conditional routing):
+
+*Dockerfile format:*
 ```dockerfile
 ROUTER query_router
 AGENTS sql_agent api_agent file_agent
 INSTRUCTION Route queries based on data source type
 ```
 
+*YAML format:*
+```yaml
+routers:
+- name: query_router
+  agents:
+  - sql_agent
+  - api_agent
+  - file_agent
+  instruction: Route queries based on data source type
+```
+
 **Orchestrators** (Complex coordination):
+
+*Dockerfile format:*
 ```dockerfile
 ORCHESTRATOR project_manager
 AGENTS developer tester deployer
@@ -336,10 +461,24 @@ PLAN_ITERATIONS 5
 HUMAN_INPUT true
 ```
 
+*YAML format:*
+```yaml
+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:**
 ```dockerfile
 # Environment variable references
 SECRET OPENAI_API_KEY
@@ -355,6 +494,23 @@ BASE_URL https://api.example.com
 TIMEOUT 30
 ```
 
+**YAML format:**
+```yaml
+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.
@@ -426,21 +582,36 @@ This ensures your agent automatically executes the default prompt when the conta
 
 ## 🎯 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
+├── 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:**
+```bash
+# Using Dockerfile format
+agentman build -f Agentfile .
+
+# Using YAML format  
+agentman build -f Agentfile.yml .
+
+# Auto-detection (picks first available)
+agentman build .
+```
+
 **prompt.txt:**
 ```text
 I am a GitHub user with the username "yeahdongcn" and I need help updating my GitHub profile information.