Templates Module

Import: from selectools.templates import load_template Stability: beta

from selectools.templates import load_template, list_templates
from selectools.providers.stubs import LocalProvider

# List available templates
print(list_templates())
# ['code_reviewer', 'customer_support', 'data_analyst', 'rag_chatbot', 'research_assistant']

# Load a template
agent = load_template("customer_support", provider=LocalProvider())
result = agent.run("I need help resetting my password")
print(result.content)

!!! tip "See Also" - Serve Module -- deploy template-based agents as HTTP APIs - Agent Module -- the Agent class and AgentConfig

Added in: v0.19.0 Package: src/selectools/templates/ Functions: from_yaml(), from_dict(), load_template(), list_templates()

Table of Contents

1. Overview
2. Quick Start
3. from_yaml()
4. from_dict()
5. load_template()
6. Built-in Templates
7. YAML Config Reference
8. Tool Resolution
9. Custom Templates
10. Integration with Serve
11. API Reference
12. Examples

---

Overview

The templates module provides two ways to create agents without writing Python:

1. YAML configuration files -- define an agent's model, tools, system prompt, and behavior in a YAML file. Load it with from_yaml().
2. Pre-built templates -- 5 ready-to-use agent configurations for common use cases. Load them with load_template().

Why Templates?

	Python Code	YAML Config	Built-in Template
Lines	10-30	5-15	1
Requires Python?	Yes	No (CLI: selectools serve agent.yaml)	No (CLI: selectools serve customer_support)
Customizable?	Full control	Full control	Overrides only
Best for	Production apps	Config-driven deployments	Demos, prototyping

Design Philosophy

• No magic. YAML keys map 1:1 to AgentConfig fields. If you know the Python API, you know the YAML format.
• Batteries included. Five templates cover the most common agent patterns. Each includes purpose-built tools and a tuned system prompt.
• Composable with serve. Both YAML configs and template names work directly with selectools serve.

---

Quick Start

From YAML

from selectools.templates import from_yaml

agent = from_yaml("agent.yaml")
result = agent.run("Hello!")
print(result.content)

From Template

from selectools.templates import load_template
from selectools.providers.openai_provider import OpenAIProvider

agent = load_template("customer_support", provider=OpenAIProvider())
result = agent.run("I can't log into my account")
print(result.content)

From CLI

# YAML config
selectools serve agent.yaml

# Built-in template (auto-detects API key)
selectools serve research_assistant

---

from_yaml()

Create an Agent from a YAML configuration file.

from selectools.templates import from_yaml

# Basic usage -- provider auto-detected from YAML "provider" field
agent = from_yaml("agent.yaml")

# Override provider
from selectools.providers.anthropic_provider import AnthropicProvider
agent = from_yaml("agent.yaml", provider=AnthropicProvider())

Example YAML

provider: openai
model: gpt-4o
system_prompt: "You are a helpful coding assistant."
temperature: 0.7
max_iterations: 5

tools:
  - selectools.toolbox.file_tools.read_file
  - selectools.toolbox.file_tools.write_file
  - ./my_custom_tool.py

retry:
  max_retries: 3

budget:
  max_cost_usd: 0.50

Parameters

Parameter	Type	Default	Description
path	str	(required)	Path to the YAML config file.
provider	Optional[Provider]	None	Override the provider. If None, created from the provider field in YAML.

Requirements

Requires PyYAML: pip install pyyaml. Raises ImportError with instructions if not installed.

---

from_dict()

Create an Agent from a Python dictionary. Same format as the YAML config but as a dict -- useful when configs come from a database, API, or environment variables.

from selectools.templates import from_dict

config = {
    "provider": "openai",
    "model": "gpt-4o-mini",
    "system_prompt": "You are a helpful assistant.",
    "tools": ["selectools.toolbox.file_tools.read_file"],
    "budget": {"max_cost_usd": 0.25},
}

agent = from_dict(config)
result = agent.run("Read the README")

Parameters

Parameter	Type	Default	Description
config	Dict[str, Any]	(required)	Configuration dictionary.
provider	Optional[Provider]	None	Override the provider.

---

load_template()

Load a pre-built agent template by name. Each template includes purpose-built tools and a tuned system prompt for its use case.

from selectools.templates import load_template
from selectools.providers.openai_provider import OpenAIProvider

provider = OpenAIProvider()

# Load with defaults
agent = load_template("customer_support", provider=provider)

# Override specific config fields
agent = load_template(
    "research_assistant",
    provider=provider,
    model="gpt-4o",           # override default model
    max_iterations=12,         # override default iteration limit
)

Parameters

Parameter	Type	Default	Description
name	str	(required)	Template name. See Built-in Templates.
provider	Provider	(required)	LLM provider instance.
**overrides	Any	--	Override any AgentConfig field.

Listing Available Templates

from selectools.templates import list_templates

print(list_templates())
# ['code_reviewer', 'customer_support', 'data_analyst', 'rag_chatbot', 'research_assistant']

---

Built-in Templates

customer_support

A friendly customer support agent with account lookup, knowledge base search, and ticket escalation.

Tools: lookup_customer, search_help_articles, create_ticket Default model: gpt-4o-mini Max iterations: 5

agent = load_template("customer_support", provider=provider)
result = agent.run("I can't reset my password")

The agent will look up the customer's account, search help articles for password reset instructions, and only create a support ticket if it cannot resolve the issue directly.

research_assistant

A thorough research agent that searches the web, reads sources, and organizes findings with citations.

Tools: web_search, read_url, save_notes Default model: gpt-4o-mini Max iterations: 8

agent = load_template("research_assistant", provider=provider)
result = agent.run("What are the latest advances in quantum computing?")

The agent searches broadly first, dives into relevant sources, and distinguishes facts from opinions.

data_analyst

An agent for data exploration, SQL queries, and visualization.

Tools: Data querying and analysis tools Default model: gpt-4o-mini

agent = load_template("data_analyst", provider=provider)
result = agent.run("Show me monthly revenue trends for Q4")

code_reviewer

An agent that reviews code for bugs, style issues, and security vulnerabilities.

Tools: Code analysis and review tools Default model: gpt-4o-mini

agent = load_template("code_reviewer", provider=provider)
result = agent.run("Review this pull request for security issues")

rag_chatbot

A retrieval-augmented chatbot that searches a knowledge base before answering.

Tools: RAG search and retrieval tools Default model: gpt-4o-mini

agent = load_template("rag_chatbot", provider=provider)
result = agent.run("How do I configure SSL certificates?")

---

YAML Config Reference

Every field in AgentConfig is configurable via YAML. Fields map directly -- no translation layer.

Top-Level Fields

Field	Type	Default	Description
provider	str	"openai"	Provider name: openai, anthropic, gemini, ollama, local.
model	str	Provider default	Model identifier (e.g. gpt-4o, claude-sonnet-4-20250514).
temperature	float	Provider default	Sampling temperature.
max_tokens	int	Provider default	Maximum response tokens.
max_iterations	int	10	Maximum agent loop iterations.
system_prompt	str	""	System prompt for the agent.
verbose	bool	False	Enable verbose logging.
stream	bool	False	Enable streaming by default.
reasoning_strategy	str	None	Reasoning strategy: react, cot.

tools

A list of tool specifications. Each entry can be:

• Dotted import path: selectools.toolbox.file_tools.read_file
• Relative file path: ./my_custom_tool.py (resolved relative to the YAML file)

tools:
  - selectools.toolbox.file_tools.read_file
  - selectools.toolbox.file_tools.write_file
  - selectools.toolbox.web_tools.web_search
  - ./custom_tools/my_tool.py

retry

Retry configuration for LLM API calls.

retry:
  max_retries: 3

budget

Token and cost budget limits.

budget:
  max_cost_usd: 1.00
  max_tokens: 50000

coherence

Coherence checking configuration.

coherence:
  enabled: true

compress

Prompt compression configuration.

compress:
  enabled: true
  threshold: 10000

trace

Trace configuration.

trace:
  enabled: true

Full Example

provider: openai
model: gpt-4o
temperature: 0.3
max_iterations: 8
system_prompt: |
  You are a senior software engineer reviewing code.
  Focus on security, performance, and maintainability.
  Always explain your reasoning.

tools:
  - selectools.toolbox.file_tools.read_file
  - selectools.toolbox.file_tools.list_dir
  - ./project_tools/run_tests.py

retry:
  max_retries: 2

budget:
  max_cost_usd: 2.00

coherence:
  enabled: true

compress:
  enabled: true
  threshold: 8000

---

Tool Resolution

Tools specified in YAML or dicts are resolved at load time through two mechanisms:

Dotted Import Paths

Reference any tool by its full Python import path. The module is imported and the tool object is extracted.

tools:
  - selectools.toolbox.file_tools.read_file     # Built-in tool
  - mypackage.tools.custom_search               # Your own tool

Relative File Paths

Reference a Python file containing @tool-decorated functions. The file is loaded via ToolLoader.from_file() and all tools discovered in it are registered.

tools:
  - ./my_tool.py          # Relative to YAML file location
  - ../shared/utils.py    # Parent directory

File paths are resolved relative to the YAML config file's directory. Path traversal outside the config directory is rejected for security.

No Tools

If no tools are specified, the template builds a pure conversational agent (no tools) — a normal use case. The provider is simply called with no tools.

---

Custom Templates

Create your own reusable templates by following the built-in pattern:

Template Module Structure

# my_templates/sales_agent.py

from selectools.agent.config import AgentConfig
from selectools.agent.core import Agent
from selectools.tools.decorators import tool


@tool(description="Look up product details by SKU or name")
def product_lookup(query: str) -> str:
    """Search the product catalog."""
    return f"Product info for '{query}': ..."


@tool(description="Check inventory levels for a product")
def check_inventory(sku: str) -> str:
    """Check current stock levels."""
    return f"SKU {sku}: 142 units in stock"


SYSTEM_PROMPT = """You are a knowledgeable sales assistant.
Help customers find the right products and check availability."""


def build(provider, **overrides):
    """Build a sales agent."""
    config_kwargs = {
        "model": overrides.pop("model", "gpt-4o-mini"),
        "max_iterations": overrides.pop("max_iterations", 5),
        "system_prompt": overrides.pop("system_prompt", SYSTEM_PROMPT),
        **overrides,
    }
    return Agent(
        provider=provider,
        tools=[product_lookup, check_inventory],
        config=AgentConfig(**config_kwargs),
    )

Using Custom Templates

from my_templates.sales_agent import build

agent = build(provider=provider, model="gpt-4o")

The key convention is a build(provider, **overrides) function that returns a configured Agent.

---

Integration with Serve

Templates and YAML configs work directly with the serve module:

# Serve from YAML
selectools serve agent.yaml

# Serve a built-in template by name
selectools serve customer_support
selectools serve research_assistant
selectools serve data_analyst
selectools serve code_reviewer
selectools serve rag_chatbot

When serving a template by name, the CLI auto-detects an available API key from environment variables (checking OPENAI_API_KEY, then ANTHROPIC_API_KEY, then GOOGLE_API_KEY in order).

---

API Reference

from_yaml()

Parameter	Type	Default	Description
path	str	(required)	Path to YAML config file.
provider	Optional[Provider]	None	Override provider. Auto-resolved from YAML if None.

Returns: Agent

from_dict()

Parameter	Type	Default	Description
config	Dict[str, Any]	(required)	Configuration dictionary. Same schema as YAML.
provider	Optional[Provider]	None	Override provider. Auto-resolved from dict if None.

Returns: Agent

load_template()

Parameter	Type	Default	Description
name	str	(required)	Template name.
provider	Provider	(required)	LLM provider instance.
**overrides	Any	--	Override any AgentConfig field.

Returns: Agent

list_templates()

Returns: List[str] -- sorted list of available template names.

Supported Providers (YAML)

Name	Class	Required Env Var
openai	OpenAIProvider	OPENAI_API_KEY
anthropic	AnthropicProvider	ANTHROPIC_API_KEY
gemini	GeminiProvider	GOOGLE_API_KEY or GEMINI_API_KEY
ollama	OllamaProvider	None (local)
local	LocalProvider	None (stub)

---

Examples

Example	File	Description
62	62_yaml_config.py	Load an agent from YAML config
63	63_agent_templates.py	Use all 5 built-in templates

---

Related Examples

#	File	Description
62	62_yaml_config.py	Load an agent from a YAML config file
63	63_agent_templates.py	Use all 5 built-in agent templates

---

Further Reading

• Serve Module -- Deploy agents as HTTP APIs
• Agent Module -- The Agent class and AgentConfig
• Tools Module -- Custom tool creation with @tool
• Dynamic Tools -- ToolLoader for runtime tool discovery

---

Next Steps: Learn about deploying agents as HTTP APIs in the Serve Module.