agent-as-code

🚀 Agent-as-Code: The Docker for AI Agents

Build, deploy, and manage AI agents using declarative configuration - now with enterprise-grade performance and comprehensive binary distribution.

························································································································ : █████████ █████ █████████ █████ : : ███░░░░░███ ░░███ ███░░░░░███ ░░███ : : ░███ ░███ ███████ ██████ ████████ ███████ ██████ █████ ███ ░░░ ██████ ███████ ██████ : : ░███████████ ███░░███ ███░░███░░███░░███ ░░░███░ ░░░░░███ ███░░ ░███ ███░░███ ███░░███ ███░░███: : ░███░░░░░███ ░███ ░███░███████ ░███ ░███ ░███ ███████ ░░█████ ░███ ░███ ░███░███ ░███ ░███████ : : ░███ ░███ ░███ ░███░███░░░ ░███ ░███ ░███ ███ ███░░███ ░░░░███ ░░███ ███░███ ░███░███ ░███ ░███░░░ : : █████ █████░░███████░░██████ ████ █████ ░░█████ ░░████████ ██████ ░░█████████ ░░██████ ░░████████░░██████ : :░░░░░ ░░░░░ ░░░░░███ ░░░░░░ ░░░░ ░░░░░ ░░░░░ ░░░░░░░░ ░░░░░░ ░░░░░░░░░ ░░░░░░ ░░░░░░░░ ░░░░░░ : : ███ ░███ : : ░░██████ : : ░░░░░░ : ························································································································

Just like Docker revolutionized application deployment, Agent-as-Code revolutionizes AI agent deployment with declarative configurations and enterprise-grade tooling.

---

🎯 What Makes Agent-as-Code Special

🔧 Declarative Configuration

Define your AI agents using simple, version-controlled agent.yaml files - no complex setup required.

⚡ Hybrid Performance Architecture

• Go Core: 5x faster CLI operations and binary distribution
• Python Runtime: Full AI/ML ecosystem compatibility
• Universal Access: Available via PyPI, Homebrew, direct download

🌍 Local + Cloud Ready

• Local LLMs: Complete offline capability with Ollama integration
• Cloud LLMs: Seamless OpenAI, Azure, AWS integration
• Multi-Cloud Deployment: Deploy anywhere with one command

---

⚡ Quick Start

Installation

Choose your preferred installation method:

# Python Package (Recommended for developers)
pip install agent-as-code

# Direct Binary Download (Fastest)
curl -L https://api.myagentregistry.com/install.sh | sh

# Homebrew (macOS/Linux)
brew install agent-as-code

Create Your First Agent

# Create a new chatbot agent
agent init my-chatbot --template chatbot
cd my-chatbot

# Build the agent
agent build -t my-chatbot:latest .

# Run it locally
agent run my-chatbot:latest

# Test it
curl -X POST http://localhost:8080/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello! How can you help me?"}'

Deploy to Production

# Push to registry
agent push my-chatbot:latest

# Deploy to cloud (AWS/Azure/GCP)
agent deploy my-chatbot:latest --cloud aws --replicas 3

---

🏗️ Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                    Agent-as-Code Framework                      │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐  │
│  │   Go Binary     │  │  Python Wrapper │  │  Binary API     │  │
│  │  (Performance)  │  │  (Ecosystem)    │  │  (Distribution) │  │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘  │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐  │
│  │  agent.yaml     │  │  Templates      │  │  Multi-Runtime  │  │
│  │  (Config)       │  │  (Examples)     │  │  (Deployment)   │  │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

🎯 Core Features

📋 CLI Commands

Command	Description	Example
agent init	Create new agent project	agent init my-bot --template chatbot
agent build	Build agent container	agent build -t my-bot:latest .
agent run	Run agent locally	agent run my-bot:latest
agent push/pull	Registry operations	agent push my-bot:latest
agent deploy	Deploy to cloud	agent deploy my-bot:latest --cloud aws

🛠️ Templates

Pre-built templates for common use cases:

• 🤖 Chatbot: Customer support with conversation memory
• 📊 Sentiment: Social media sentiment analysis
• 📝 Summarizer: Document summarization
• 🌐 Translator: Multi-language translation
• 📈 Data Analyzer: Business intelligence
• ✨ Content Generator: Creative content creation

🌐 Local LLM Support

Complete offline AI capability with Ollama:

# Setup local LLM environment
agent llm setup

# Pull and use local models
agent llm pull llama2
agent init my-agent --template chatbot --model local/llama2

---

🎮 Example: agent.yaml

apiVersion: agent.dev/v1
kind: Agent
metadata:
  name: customer-support-bot
  version: 1.0.0
  description: AI customer support agent with escalation handling
spec:
  runtime: python:3.11
  model:
    provider: openai  # or 'ollama' for local
    name: gpt-4
    config:
      temperature: 0.7
      max_tokens: 500
  capabilities:
    - conversation
    - customer-support
    - escalation
  dependencies:
    - openai==1.0.0
    - fastapi==0.104.0
    - uvicorn==0.24.0
  ports:
    - container: 8080
      host: 8080
  environment:
    - name: OPENAI_API_KEY
      from: secret
    - name: LOG_LEVEL
      value: INFO
  healthCheck:
    command: ["curl", "-f", "http://localhost:8080/health"]
    interval: 30s
    timeout: 10s
    retries: 3

---

🚀 Binary Distribution System

Agent-as-Code uses a Terraform-style binary distribution API for installing the CLI itself:

Installation Methods

# Method 1: Direct installation (recommended)
curl -L https://api.myagentregistry.com/install.sh | sh

# Method 2: Python package 
pip install agent-as-code

# Method 3: Manual download
curl -L https://api.myagentregistry.com/binary/releases/agent-as-code/1/2/agent_as_code_1.2.3_linux_amd64.zip

Binary API (for CLI distribution)

• GET /binary/releases/agent-as-code/versions - List available CLI versions
• GET /binary/releases/agent-as-code/{major}/{minor}/ - List platform binaries
• GET /binary/releases/agent-as-code/{major}/{minor}/{filename} - Download CLI binary
• POST /binary/releases/agent-as-code/{major}/{minor}/upload - Upload CLI binary (maintainers only)

For Maintainers: Release Process

# Build and upload new CLI version
make release VERSION=1.2.3

# This makes the agent CLI available for users to install via:
# curl -L https://api.myagentregistry.com/install.sh | sh

---

🎯 Real-World Examples

Production Chatbot

agent init support-bot --template chatbot
cd support-bot

# Configure for production
export OPENAI_API_KEY="your-key"
export ESCALATION_KEYWORDS="human,manager,supervisor"

# Deploy with high availability
agent build -t support-bot:v1.0.0 .
agent deploy support-bot:v1.0.0 --cloud aws --replicas 5 --auto-scale

Local Development

# Setup local environment
agent llm setup
agent llm pull llama2

# Create offline agent
agent init offline-assistant --template chatbot --model local/llama2
agent run offline-assistant:latest

CI/CD Integration

# .github/workflows/agent-deploy.yml
name: Deploy Agent
on:
  push:
    tags: ['v*']
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Build and Deploy
        run: |
          agent build -t ${{ github.repository }}:${{ github.ref_name }} .
          agent push ${{ github.repository }}:${{ github.ref_name }}
          agent deploy ${{ github.repository }}:${{ github.ref_name }} --cloud aws

---

📚 Documentation

Complete Guides

• 📖 Full Documentation - Comprehensive guides and references
• 🚀 Getting Started - Step-by-step tutorial
• 📋 CLI Reference - All commands and options
• 🎯 Examples - Real-world usage examples

Advanced Topics

• 🔧 Template Creation - Build custom templates
• 🌐 Local LLM Setup - Ollama integration guide
• 📦 Binary API - Distribution system details
• 🚀 Deployment Guide - Production deployment strategies

---

🛠️ Development

Build from Source

# Clone and build
git clone https://github.com/pxkundu/agent-as-code
cd agent-as-code

# Build all components
make build

# Install locally
make install

# Run tests
make test

# Create release
make release VERSION=1.2.3

Project Structure

agent-as-code/
├── cmd/agent/           # Go CLI source
├── internal/            # Go internal packages
│   ├── api/            # Binary API client
│   ├── builder/        # Agent building
│   ├── cmd/            # CLI commands
│   ├── parser/         # Config parsing
│   ├── registry/       # Registry operations
│   ├── runtime/        # Agent execution
│   └── templates/      # Template management
├── python/             # Python wrapper package
├── templates/          # Agent templates
├── examples/           # Real-world examples
├── scripts/            # Build and release scripts
└── docs/               # Documentation

---

🌟 Why Agent-as-Code?

For Developers

• ⚡ Fast: 5x performance improvement over pure Python solutions
• 🔧 Simple: Declarative configuration, familiar Docker-like commands
• 🐍 Compatible: Full Python ecosystem access for AI/ML libraries
• 📦 Portable: Deploy anywhere - local, cloud, edge

For Teams

• 👥 Collaborative: Version-controlled agent definitions
• 🔄 Reusable: Share templates and configurations
• 📊 Scalable: Production-ready deployment patterns
• 🔒 Secure: Enterprise-grade secret management

For Organizations

• 💰 Cost-Effective: Local LLM support reduces API costs
• 🌍 Multi-Cloud: Avoid vendor lock-in
• 📈 Scalable: Handle enterprise workloads
• 🔐 Compliant: Secure, auditable deployments

---

🤝 Community

Get Involved

• 💬 Discussions - Community forum
• 🐛 Issues - Bug reports and feature requests

Resources

• 🌐 Website - Official website
• 📚 Documentation - Complete docs

---

📊 Benchmarks

Performance Comparison

Operation	Pure Python	Go + Python	Improvement
agent init	2.3s	0.4s	5.8x faster
agent build	45s	12s	3.8x faster
agent deploy	8.2s	1.6s	5.1x faster
Binary size	50MB+ deps	15MB single	70% smaller

---

🎯 Roadmap

Current (v1.0)

• ✅ Hybrid Go + Python architecture
• ✅ Complete CLI functionality
• ✅ Template system
• ✅ Local LLM support (Ollama)
• ✅ Binary API distribution

Next (v1.1)

• 🔄 Kubernetes operator
• 🔄 Advanced monitoring and metrics
• 🔄 Multi-agent orchestration
• 🔄 Plugin system

Future (v2.0)

• 📋 Visual agent builder
• 📋 Enterprise management console
• 📋 Advanced AI optimization
• 📋 Edge deployment support

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🏆 Recognition

Agent-as-Code is revolutionizing how developers build and deploy AI agents. Join thousands of developers who are already using Agent-as-Code to power their AI applications.

⭐ Star us on GitHub | 📦 Try it now | 🤝 Contribute

---

Ready to revolutionize your AI agent deployment? Get started now and experience the future of AI agent development!