agentomatic 0.3.0

Drop agents, not code — zero-code multi-agent API platform framework

⚡ Agentomatic

Drop agents, not code

Zero-code multi-agent API platform framework. Create production-ready AI agent APIs with auto-discovery, auto-routing, streaming, A2A protocol, and full observability — in 3 lines of code.

Documentation · Quick Start · CLI Reference · Templates · Contributing

---

✨ Features

Feature	Description
🔍 Auto-Discovery	Drop an agent folder → endpoints appear automatically
🚀 25+ Endpoints Per Agent	invoke, stream, chat, A2A, health, config, threads, memory, feedback
🗄️ Pluggable Storage	MemoryStore, SQLAlchemy, or bring your own
🔐 Middleware Pipeline	Auth, rate limiting, Prometheus metrics — all toggleable
🎨 Built-in Debug UI	ChatGPT-like interface via Chainlit
📦 5 Scaffolding Templates	basic, full, rag, chatbot, custom
🤖 A2A Protocol	Agent-to-agent communication out of the box
🔌 Framework Agnostic	LangGraph, LangChain, or raw Python
🩺 Rich CLI	Beautiful terminal experience with doctor, inspect, test
⚡ Prompt Optimizer	DSPy-inspired prompt optimization (7 strategies)
🧪 Data Synthesizer	Auto-generate & augment eval datasets via LLM
📊 HTML Reports	SVG charts, prompt diffs, experiment tracking
🚦 Human-in-the-Loop	Suspend/resume execution with human approval gates
🌳 Thread Lineage	First-class parent/child tracking with ancestry traversal
⏰ HITL TTL Expiry	Auto-cleanup of stale suspended states (7-day default)
🛡️ LLM Failover	Multi-provider fallback chains with telemetry
🧬 Thread Forking	Clone conversations at any message index
🔀 A/B Prompt Routing	Weight-based prompt version selection
🪝 State Hooks	Before/after node interceptors for audit & telemetry
🧠 Conversation Memory	Automatic session + long-term memory with windowing
📝 Auto-Summarization	LLM-powered compression of long conversations
📋 Thread CRUD	Full thread lifecycle management (create/update/delete/clear)
💬 Message Persistence	Every turn auto-saved — history survives restarts

🚀 Quick Start

Install

pip install agentomatic[all]

Create an Agent

agentomatic init my_agent --template basic

Build & Run

# main.py
from agentomatic import AgentPlatform

platform = AgentPlatform.from_folder("agents/")
app = platform.build()

uvicorn main:app --reload

Test

# CLI
agentomatic test my_agent

# curl
curl -X POST http://localhost:8000/api/v1/my_agent/invoke \
  -H "Content-Type: application/json" \
  -d '{"query": "Hello!"}'

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                    AgentPlatform                            │
│                                                             │
│  ┌──────────┐  ┌──────────────┐  ┌───────────────────────┐ │
│  │ Registry │  │ Middleware   │  │ Storage               │ │
│  │          │  │ ├─ Auth      │  │ ├─ MemoryStore        │ │
│  │ agent_a  │  │ ├─ RateLimit │  │ ├─ SQLAlchemyStore   │ │
│  │ agent_b  │  │ ├─ Metrics   │  │ └─ YourStore(ABC)    │ │
│  │ agent_c  │  │ └─ Logging   │  │                       │ │
│  └──────────┘  └──────────────┘  └───────────────────────┘ │
│                                                             │
│  Per Agent: POST /invoke, /stream, /chat, /a2a/tasks ...   │
└─────────────────────────────────────────────────────────────┘

📂 Agent Structure

Only __init__.py is required. Everything else is optional overrides:

agents/my_agent/
├── __init__.py      ← REQUIRED: manifest + node_fn
├── graph.py         ← Optional: LangGraph StateGraph
├── nodes.py         ← Optional: node functions
├── config.py        ← Optional: Pydantic config
├── schemas.py       ← Optional: custom request/response models
├── tools.py         ← Optional: LangChain tools
├── api.py           ← Optional: custom router (REPLACES auto-gen)
├── prompts.json     ← Optional: versioned prompt templates
├── langgraph.json   ← Optional: LangGraph Studio config
├── .env.example     ← Optional: environment variables
└── README.md        ← Optional: agent documentation

📦 Templates

agentomatic init my_agent --template <template>

Template	Files	Description
basic	7	Minimal agent — quick start
full	11	All override files — config, schemas, api, tools
rag	9	Retrieve → Generate pipeline
chatbot	8	Conversational with memory
custom	4	Framework-agnostic — no LangGraph

🖥️ CLI

⚡ Agentomatic — Drop agents, not code

  init <name>      Scaffold a new agent from template
  run              Start the platform server
  list             List discovered agents (Rich table)
  test <name>      Interactive terminal testing
  inspect <name>   Show agent structure + config
  doctor           Environment health check
  ui               Launch Chainlit debug UI

⚙️ Configuration

from agentomatic import AgentPlatform
from agentomatic.storage import MemoryStore  # or SQLAlchemyStore

platform = AgentPlatform.from_folder(
    "agents/",
    # Storage
    store=MemoryStore(),
    # Auth
    enable_auth=True,
    auth_api_key="your-secret-key",
    # Rate limiting
    enable_rate_limit=True,
    rate_limit_requests=100,
    rate_limit_window=60,
    # Prometheus metrics
    enable_metrics=True,
    # Custom middleware
    middleware=[(MyMiddleware, {"arg": "value"})],
)
app = platform.build()

🗄️ Storage Backends

# Development
from agentomatic.storage import MemoryStore
store = MemoryStore()

# Production (PostgreSQL)
from agentomatic.storage import SQLAlchemyStore
store = SQLAlchemyStore("postgresql+asyncpg://user:pass@localhost/db")

# Custom
from agentomatic.storage import BaseStore
class RedisStore(BaseStore):
    async def create_thread(self, ...): ...
    async def get_thread(self, ...): ...

🎨 Debug UI

Built-in ChatGPT-like interface powered by Chainlit:

pip install agentomatic[ui]
agentomatic run --with-ui
# → http://localhost:8000/chat

Features: agent selector, streaming, tool call visualization, chain-of-thought, feedback collection.

📊 Auto-Generated Endpoints

Every agent gets 12+ endpoints automatically:

Method	Path	Description
POST	/api/v1/{agent}/invoke	Synchronous invocation
POST	/api/v1/{agent}/invoke/stream	SSE streaming
POST	/api/v1/{agent}/chat	Session-aware chat
GET	/api/v1/{agent}/health	Per-agent health
GET	/api/v1/{agent}/card	A2A agent card
POST	/api/v1/{agent}/a2a/tasks	A2A task submission
GET	/api/v1/{agent}/threads	List threads
POST	/api/v1/{agent}/threads/{id}/approve	HITL: approve suspended state
POST	/api/v1/{agent}/threads/{id}/reject	HITL: reject suspended state
GET	/api/v1/{agent}/threads/{id}/pending	HITL: list pending approvals
POST	/api/v1/{agent}/threads/{id}/fork	Fork thread at message index
GET	/api/v1/{agent}/threads/{id}/lineage	Thread ancestry/descendant tree
...	...	+ config, prompts, thread messages

🛠️ Development

# Install
git clone https://github.com/UnicoLab/agentomatic.git
cd agentomatic
make dev  # Installs all deps + pre-commit hooks

# Quality
make lint          # Ruff linter
make format        # Auto-format
make typecheck     # Mypy
make test          # All tests
make test-cov      # With coverage
make check-all     # lint + typecheck + test

# Docs
make docs-serve    # Local docs server
make docs-build    # Build static site

# Build
make build         # Package
make publish       # PyPI

📜 License

MIT — see LICENSE.

👥 Authors

UnicoLab — Building the future of AI agent platforms.

---

⭐ Star us on GitHub — it helps!

Made with ❤️ by UnicoLab