Scaffolding Templates¶

Agent Scaffolding and Project Generation

Agentomatic ships with 16 templates for rapid agent and component creation. They generate the appropriate runnable package or workflow artefact for the selected use case.

🚀 Quick Start¶

Interactive (Recommended)Non-Interactive

# Launches a guided questionnaire to pick template and configure
agentomatic init my_agent

Requires questionary

Install with pip install questionary for the interactive prompt experience.

# Specify template directly
agentomatic init my_agent --template basic

For agent templates, both commands create agents/my_agent/. Integration and pipeline templates use their own auto-discovered directories; see Component and integration templates.

📊 Template Comparison¶

Template	Framework	Graph	Config	Tools	Custom API	Best For
`basic`	Built-in	✅	❌	❌	❌	Quick prototyping and learning
`class`	Built-in	✅	❌	❌	❌	Alias for `basic`
`full`	Built-in	✅	✅	✅	✅	Production agents with all overrides
`coordinator`	Built-in	✅	✅	❌	❌	Delegating work to specialist agents
`pipeline`	YAML	—	—	—	—	Multi-step workflows across components
`rag`	Built-in	✅	❌	❌	❌	Knowledge bases, Q&A over documents
`chatbot`	Built-in	✅	❌	❌	❌	Conversational agents with memory
`deepagent`	LangGraph	❌¹	❌	✅	❌	Autonomous planning with sub-agents
`custom`	Custom	❌	❌	❌	❌	Framework-agnostic, minimal deps
`legacy_dict`	LangGraph	✅	❌	❌	❌	Legacy functional agent (3 files)
`langchain`	LangChain	✅	❌	❌	❌	LangChain-native prompt and message workflows
`plugin`	Plugin	—	—	—	✅	ML model plugins with REST endpoints
`endpoint`	HTTP	—	—	—	✅	Wrapping an external model or service
`connection`	Connection	—	—	—	—	Per-agent database and HTTP connections
`ingestion`	Ingestion	—	—	—	✅	Packaging document ingestion as a task
`extraction`	Built-in	✅	❌	❌	❌	Parallel markdown extraction workflows

¹ Deep agent uses agent.py with create_deep_agent() instead of build_graph()

Core class-agent templates use AgentGraph

The basic, full, rag, chatbot, coordinator, and extraction templates generate BaseGraphAgent subclasses backed by agentomatic's built-in AgentGraph runtime — no LangGraph dependency required.

📁 Generated Files by Template¶

`basic` — Minimal Agent¶

The simplest starting point — a class-owned BaseGraphAgent (also available as --template class).

agentomatic init my_agent --template basic
# or: agentomatic init my_agent --template class

agents/my_agent/
├── __init__.py          # AgentManifest card
├── agent.py             # BaseGraphAgent subclass
├── llm.py               # Stack-aware LLM helpers
├── prompts.json         # v1/v2 prompt templates
├── langgraph.json       # LangGraph Studio config
├── .env.example         # Environment variable template
└── README.md            # Agent documentation

Class-agent layout

basic / class emit agent.py + llm.py — not the legacy graph.py / nodes.py layout (use --template legacy_dict for that).

`full` — All Override Files¶

Includes every possible override file. Ideal for production agents that need full control.

agentomatic init my_agent --template full

agents/my_agent/
├── __init__.py          # AgentManifest card
├── agent.py             # BaseGraphAgent subclass (+ get_graph export)
├── llm.py               # Stack-aware LLM helpers
├── config.py            # Pydantic config (MyAgentConfig)
├── schemas.py           # Custom request/response models
├── tools.py             # Tool definitions
├── api.py               # Optional custom FastAPI router
├── dataset.jsonl        # Sample train/eval data
├── train.py / eval.py / optimize.py / predict.py
├── search_space.yaml    # PromptFitter search space
├── Makefile
├── prompts.json
├── langgraph.json       # Points at ./agent.py:get_graph
├── .env.example
└── README.md

Generated config.py

"""Configuration for My Agent agent."""
from pydantic import BaseModel, Field

class MyAgentConfig(BaseModel):
    """Agent-specific configuration."""
    prompt_version: str = Field("v1", description="Active prompt version")
    temperature: float = Field(0.1, ge=0.0, le=2.0)
    max_tokens: int = Field(2048, ge=1)
    enable_memory: bool = Field(True, description="Enable conversation memory")

Generated schemas.py

"""Custom schemas for my_agent."""
from pydantic import BaseModel, Field

class MyAgentRequest(BaseModel):
    """Custom request model."""
    query: str = Field(..., description="User query")
    context: dict = Field(default_factory=dict)

class MyAgentResponse(BaseModel):
    """Custom response model."""
    answer: str
    confidence: float = Field(0.0, ge=0.0, le=1.0)
    sources: list[str] = Field(default_factory=list)

Generated api.py

"""Custom API router for my_agent.

If this file exports a `router`, it REPLACES the auto-generated endpoints.
Remove this file to use auto-generated endpoints instead.
"""
from fastapi import APIRouter

router = APIRouter()

@router.get("/status")
async def status() -> dict:
    """Custom status endpoint."""
    return {"agent": "my_agent", "custom_router": True}

Custom Router Override

When api.py is present and exports a router, the generated per-agent API is replaced by that router. Remove api.py to restore the default REST API.

`rag` — Retrieval-Augmented Generation¶

A two-stage pipeline (retrieve → generate) pre-configured for knowledge-base Q&A.

agentomatic init knowledge_bot --template rag

agents/knowledge_bot/
├── __init__.py          # AgentManifest with RAG keywords
├── agent.py             # BaseGraphAgent: retrieve → generate
├── llm.py               # Stack-aware LLM helpers
├── config.py            # Pydantic config
├── tools.py             # Search tool stubs
├── prompts.json
├── langgraph.json       # ./agent.py:get_graph
├── .env.example
└── README.md

Class-agent RAG

The rag template is a BaseGraphAgent with retrieve + generate nodes — not the legacy graph.py / nodes.py layout.

`chatbot` — Conversational Agent¶

Optimized for multi-turn conversations with memory support.

agentomatic init assistant --template chatbot

agents/assistant/
├── __init__.py          # AgentManifest with chat keywords
├── agent.py             # BaseGraphAgent conversational agent
├── llm.py               # Stack-aware LLM helpers
├── config.py            # Pydantic config
├── prompts.json
├── langgraph.json       # ./agent.py:get_graph
├── .env.example
└── README.md

Class-agent chatbot

The chatbot template is a BaseGraphAgent subclass with prompt-backed conversation, not the legacy graph.py / nodes.py layout.

`deepagent` — Deep Agent with Planning¶

Uses the deepagents package for autonomous planning, tool usage, and sub-agent delegation.

agentomatic init researcher --template deepagent

agents/researcher/
├── __init__.py          # Manifest + graph_fn + node_fn
├── agent.py             # Deep agent definition with tools
├── llm.py               # Stack-aware LLM helpers
├── config.py            # Pydantic config
├── prompts.json         # v1/v2 prompt templates
├── .env.example         # Environment variable template
└── README.md            # Agent documentation

Generated agent.py

"""Deep Agent definition for researcher.

Uses LangChain's `deepagents` harness for planning, tools,
subagent delegation, and context management.
"""
from functools import lru_cache

def internet_search(query: str, max_results: int = 5) -> str:
    """Search the internet for information."""
    # TODO: Replace with real search (Tavily, SerpAPI, etc.)
    return f"Search results for: {query} ({max_results} results)"

@lru_cache(maxsize=1)
def create_agent():
    """Create and compile the deep agent."""
    from deepagents import create_deep_agent

    return create_deep_agent(
        model="openai:gpt-4o",
        system_prompt=(
            "You are Researcher, "
            "an expert AI assistant. Be thorough and accurate."
        ),
        tools=[internet_search],
    )

Dependency

The deepagent template requires the deepagents package: pip install deepagents

`custom` — Framework-Agnostic¶

The most minimal template. Pure Python with no LangGraph dependency — ideal for simple API wrappers or custom frameworks.

agentomatic init simple --template custom

agents/simple/
├── __init__.py          # Manifest + node_fn (framework="custom")
├── prompts.json         # v1/v2 prompt templates
├── .env.example         # Environment variable template
└── README.md            # Agent documentation

Generated custom __init__.py

"""Agent: simple (framework-agnostic)."""
from __future__ import annotations
from typing import Any
from agentomatic import AgentManifest

manifest = AgentManifest(
    name="simple",
    slug="agent-simple",
    description="Simple agent",
    intent_keywords=["simple"],
    framework="custom",
)

async def node_fn(state: dict[str, Any]) -> dict[str, Any]:
    """Process the request directly — no graph framework needed."""
    query = state.get("current_query", "")
    return {
        "response": f"Hello from simple! You asked: {query}",
        "agent_type": "agent-simple",
    }

`legacy_dict` — Legacy Functional Agent¶

The classic agentomatic pattern using __init__.py with manifest + node_fn. Ideal for quick utilities or migrating existing LangGraph code.

agentomatic init helper --template legacy_dict

agents/helper/
├── __init__.py          # Manifest + graph-invoking node_fn
├── graph.py             # Compiled LangGraph definition
├── nodes.py             # Async graph node functions
├── prompts.json         # Prompt templates
├── langgraph.json       # LangGraph Studio configuration
├── .env.example         # Environment config
└── README.md            # Agent documentation

Generated __init__.py

"""Agent: helper (legacy functional pattern)."""
from __future__ import annotations
from typing import Any
from agentomatic import AgentManifest

manifest = AgentManifest(
    name="helper",
    slug="agent-helper",
    description="Helper agent",
    intent_keywords=["helper", "assist"],
    framework="langgraph",
)

async def node_fn(state: dict[str, Any]) -> dict[str, Any]:
    from .graph import get_graph
    return await get_graph().ainvoke(state)

When to use legacy_dict

Use this template when you need the established module-level LangGraph layout (manifest, graph.py, and nodes.py) rather than a class-based agent. It is useful for migrating existing LangGraph code.

`plugin` — ML Model Plugin¶

Wrap a classical ML model (scikit-learn, XGBoost, etc.) as a REST endpoint using BaseMLPlugin.

agentomatic init my_classifier --template plugin

plugins/my_classifier/
├── __init__.py          # Plugin package marker
├── plugin.py            # BaseMLPlugin subclass
├── dataset.jsonl        # Sample train/eval data
├── train.py / eval.py / optimize.py / predict.py
├── Makefile             # Training and evaluation shortcuts
└── README.md            # Plugin documentation

Generated plugin.py

"""ML Plugin: my_classifier."""
from __future__ import annotations
from typing import Any
from pydantic import BaseModel, Field
from agentomatic.plugins import BaseMLPlugin

class PredictInput(BaseModel):
    features: list[float] = Field(..., description="Input feature vector")

class PredictOutput(BaseModel):
    prediction: float = Field(..., description="Model prediction")
    confidence: float = Field(0.0, description="Prediction confidence")

class MyClassifierPlugin(BaseMLPlugin[PredictInput, PredictOutput]):
    plugin_name = "my_classifier"
    plugin_description = "Classification model plugin"
    plugin_version = "1.0.0"

    def load_model(self) -> Any:
        """Load and return the trained model."""
        # Example: return joblib.load("model.pkl")
        return None

    def predict(self, model: Any, input_data: PredictInput) -> PredictOutput:
        """Run prediction on the loaded model."""
        return PredictOutput(
            prediction=0.0,
            confidence=0.95,
        )

ML Plugin Features

Plugins get automatic REST endpoints (/predict, /health, /model-card) and can be deployed alongside agents in the same platform. See ML Plugins for the full guide.

Component and integration templates¶

These templates scaffold platform components rather than a conventional agent. When no --dir is supplied, plugin, endpoint, ingestion, and pipeline are written to their auto-discovered top-level directories; connection stays under agents/ because it belongs to one agent.

Template	Default location	Main file	Purpose
`endpoint`	`endpoints/<name>/`	`endpoint.py`	Call and aggregate external model services
`connection`	`agents/<name>/`	`connections.py`	Define authenticated database and HTTP connections
`ingestion`	`ingestion/<name>/`	`ingestor.py`	Package an ingestion workflow as a task job
`pipeline`	`pipelines/<name>/`	`pipeline.yaml`	Compose agents and components into a workflow
`extraction`	`agents/<name>/`	`agent.py`	Extract scoped markdown and provide a companion pipeline

`langchain` — LangChain-native agent¶

Use this when the agent should own LangChain prompt and message primitives while remaining discoverable through Agentomatic's standard REST and Studio paths.

agentomatic init support_agent --template langchain

The generated package includes agent.py, llm.py, prompts.json, and langgraph.json. See LangChain / LangGraph Adapter for the runtime bridge and message conversion helpers.

This is the basic template pattern

The tree below is the complete output of agentomatic init analyzer --template basic. Other class-agent templates add files specific to their capabilities.

agentomatic init analyzer --template basic

agents/analyzer/
├── __init__.py          # AgentManifest card
├── agent.py             # BaseGraphAgent subclass with build_graph()
├── llm.py               # Stack-aware LLM helpers
├── prompts.json         # Prompt templates
├── langgraph.json       # LangGraph Studio configuration
├── .env.example         # Environment config
└── README.md            # Agent documentation

Example agent.py customization

This illustrates extending the generated class agent; the exact scaffold is intentionally smaller and contains only the process node.

"""Class-based agent: analyzer."""
from __future__ import annotations

from dataclasses import dataclass, field
from typing import Any

from agentomatic.agents import BaseGraphAgent


@dataclass
class AnalyzerState:
    """Agent state — per-run transient data."""

    request: str = ""
    context: list[str] = field(default_factory=list)
    output: dict[str, Any] = field(default_factory=dict)


class AnalyzerAgent(BaseGraphAgent[AnalyzerState]):
    """ML-like class agent for analyzer.

    Usage::

        agent = AnalyzerAgent(llm=my_llm)
        result = agent.transform({"request": "Hello"})
    """

    agent_name = "analyzer"
    agent_description = "Analyzer agent"

    def __init__(self, *, llm: Any = None) -> None:
        super().__init__()
        self.llm = llm
        self.system_prompt = "You are a helpful assistant."

    # --- Graph Definition ---

    def build_graph(self):
        """Wire the execution graph."""
        g = self.new_graph()
        g.add_node("process", self.process)
        g.add_node("generate", self.generate)
        g.set_entry_point("process")
        g.add_edge("process", "generate")
        g.set_finish_point("generate")
        return g.compile()

    # --- Node Methods ---

    def process(self, state: AnalyzerState) -> AnalyzerState:
        """Process the input request."""
        state.context = [f"Processed: {state.request}"]
        return state

    def generate(
        self, state: AnalyzerState,
    ) -> AnalyzerState:
        """Generate the final output."""
        state.output = {
            "response": f"Result for: {state.request}",
            "agent_type": "analyzer",
        }
        return state

    # --- State Conversion ---

    def input_to_state(
        self, input_data: dict[str, Any],
    ) -> AnalyzerState:
        return AnalyzerState(
            request=input_data.get("request", ""),
        )

    def state_to_output(
        self, state: AnalyzerState,
    ) -> dict[str, Any]:
        return state.output

No LangGraph Required

Class agents use the built-in AgentGraph runtime. Wire your graph in build_graph() using new_graph() — no need for langgraph or StateGraph.

🤔 Which Template Should I Use?¶

flowchart TD
    A["What are you building?"] --> B["Simple API wrapper<br/>or utility?"]
    A --> C["Multi-step pipeline?"]
    A --> D["Conversational<br/>chatbot?"]
    A --> E["Knowledge base<br/>Q&A?"]
    A --> F["Autonomous<br/>researcher?"]
    A --> G2["Wrap an ML model?"]
    A --> H2["Legacy LangGraph<br/>code?"]

    B -->|Yes| G["custom"]
    C -->|Simple pipeline| H["basic"]
    C -->|Need all overrides| I["full"]
    D -->|Yes| J["chatbot"]
    E -->|Yes| K["rag"]
    F -->|Yes| L["deepagent"]
    G2 -->|Yes| N["plugin"]
    H2 -->|Yes| O["legacy_dict"]

    style G fill:#f3e5f5
    style H fill:#e8f5e9
    style I fill:#e3f2fd
    style J fill:#fff3e0
    style K fill:#fce4ec
    style L fill:#e0f2f1
    style N fill:#fbe9e7
    style O fill:#f1f8e9

If you need...	Use template
Quick prototype, minimum files	`basic`
Full control over API, schemas, tools	`full`
Document retrieval + answer generation	`rag`
Multi-turn conversation with memory	`chatbot`
Autonomous planning with tools	`deepagent`
No framework dependency, pure Python	`custom`
Legacy functional agent (dict-based)	`legacy_dict`
Wrap a classical ML model	`plugin`

📁 Common Files¶

Most agent templates include these common files (component and pipeline templates intentionally have a smaller, purpose-specific layout):

File	Purpose
`prompts.json`	Two prompt versions (`v1` concise, `v2` detailed) with system and user templates
`langgraph.json`	LangGraph Studio config (`./agent.py:get_graph` for class agents, `./graph.py:get_graph` for legacy)
`.env.example`	Template for agent-specific env vars (LLM settings, feature flags)
`README.md`	Auto-generated documentation with quick start commands and file reference

Common `prompts.json` Content¶

{
  "v1": {
    "system": "You are a helpful AI assistant. Be concise and accurate.",
    "user_template": "{query}"
  },
  "v2": {
    "system": "You are an advanced AI assistant. Provide detailed, well-structured responses with examples when helpful.",
    "user_template": "Please help with the following: {query}"
  }
}

Common `.env.example` Content¶

# my_agent agent configuration
# Copy to .env and fill in values

# LLM Settings
MY_AGENT_LLM_PROVIDER=ollama
MY_AGENT_LLM_MODEL=mistral:7b
MY_AGENT_TEMPERATURE=0.1
MY_AGENT_MAX_TOKENS=2048

# Feature Flags
MY_AGENT_ENABLE_MEMORY=true
MY_AGENT_ENABLE_STREAMING=true

🧪 After Scaffolding¶

Once your agent is generated, start the platform and test:

# Start the platform
agentomatic run

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

# Check health
curl http://localhost:8000/api/v1/my_agent/health

# View in Swagger docs
open http://localhost:8000/docs

Scaffolding Templates¶

Agent Scaffolding and Project Generation

🚀 Quick Start¶

📊 Template Comparison¶

📁 Generated Files by Template¶

basic — Minimal Agent¶

full — All Override Files¶

rag — Retrieval-Augmented Generation¶

chatbot — Conversational Agent¶

deepagent — Deep Agent with Planning¶

custom — Framework-Agnostic¶

legacy_dict — Legacy Functional Agent¶

plugin — ML Model Plugin¶