Configuration

NOMOS provides flexible configuration options through both Python API and YAML files, supporting a spectrum from no-code to full-code development.

Python API Configuration

Basic Agent Setup

from nomos import Agent, AgentConfig
from nomos.models.agent import Step, Route
from nomos.models.flow import FlowConfig
from nomos.llms import LLMConfig
from math import sqrt, pow

def get_time():
    """Get the current time.

    Returns:
        str: The current time in string format.
    """
    from datetime import datetime
    return f"Current time: {datetime.now()}"

steps = [
    Step(
        step_id="start",
        description="Greet and offer to tell the time or perform calculations.",
        available_tools=["get_time", "sqrt"],
        routes=[Route(target="calculation", condition="User wants to do math"),
                Route(target="end", condition="User is done")],
    ),
    Step(
        step_id="calculation",
        description="Perform mathematical calculations for the user.",
        available_tools=["sqrt", "pow"],
        routes=[Route(target="end", condition="Calculation is complete")],
    ),
    Step(
        step_id="end",
        description="Say goodbye.",
    ),
]

# Define flows for better organization
flows = [
    FlowConfig(
        flow_id="math_workflow",
        description="Handle mathematical calculations",
        enters=["calculation"],
        exits=["end"],
        components={
            "memory": {
                "llm": {"provider": "openai", "model": "gpt-4o-mini"},
                "retriever": {"method": "embedding", "kwargs": {"k": 3}}
            }
        }
    )
]

config = AgentConfig(
    name="clockbot",
    llm=LLMConfig(provider="openai", model="gpt-4o-mini"),
    steps=steps,
    flows=flows,
    start_step_id="start",
    persona="You are a friendly assistant that can tell time and perform calculations.",
    max_errors=3,
    max_iter=10,
)

agent = Agent.from_config(config, tools=[get_time, sqrt, pow])
session = agent.create_session()
# ... interact with session.next(user_input)

YAML Configuration

Basic YAML Config

name: utility-bot
persona: You are a helpful utility bot that can perform various calculations and data operations.

# External schema definitions (optional)
schemas:
  user_profile: 'schemas/user_profile.json'
  order_schema: 'models/order.py'

steps:
  - step_id: start
    description: Handle user requests for mathematical operations or data processing.
    available_tools:
      - sqrt
      - load_json
      - combinations
    routes:
      - target: end
        condition: User is done with calculations
  - step_id: end
    description: Say goodbye to the user.
start_step_id: start
max_errors: 3  # Maximum consecutive errors before stopping
max_iter: 10  # Maximum iterations per interaction

# Server configuration (optional)
server:
  port: 8000
  host: "0.0.0.0"
  workers: 1
  security:
    # Authentication
    enable_auth: false
    auth_type: jwt  # or "api_key"
    jwt_secret_key: "$JWT_SECRET_KEY"

    # Rate limiting
    enable_rate_limiting: false
    redis_url: "$REDIS_URL"  # Redis URL for rate limiting
    rate_limit_times: 100  # Number of allowed requests
    rate_limit_seconds: 60  # Time period for rate limiting in seconds

    # CSRF protection
    enable_csrf_protection: false
    csrf_secret_key: "$CSRF_SECRET_KEY"

    # CORS configuration
    allowed_origins:
      - "*"  # Use specific domains in production

Schema Configuration

Define reusable schemas for structured responses in your agent:

schemas:
  user_profile: 'schemas/user_profile.json'
  order_schema: 'models/order.py'
  validation_rules: 'schemas/validation.json'

Schema File Formats

JSON Schema Files

Create structured data models using JSON Schema:

// schemas/user_profile.json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "User's full name"
    },
    "email": {
      "type": "string",
      "description": "User's email address",
      "format": "email"
    },
    "preferences": {
      "type": "object",
      "properties": {
        "theme": {
          "type": "string",
          "enum": ["light", "dark", "auto"]
        }
      }
    }
  },
  "required": ["name", "email"]
}

Python Schema Files

Define models using Pydantic classes:

# models/order.py
from pydantic import BaseModel, EmailStr
from typing import List, Optional
from enum import Enum

class OrderStatus(str, Enum):
    PENDING = "pending"
    CONFIRMED = "confirmed"
    SHIPPED = "shipped"

class OrderItem(BaseModel):
    product_id: str
    name: str
    quantity: int
    price: float

class Order(BaseModel):
    order_id: str
    customer_email: EmailStr
    items: List[OrderItem]
    status: OrderStatus = OrderStatus.PENDING
    total_amount: float

Schema Referencing

Reference schemas in your step configurations:

steps:
  - step_id: collect_profile
    description: Collect user profile information
    answer_model: user_profile  # References JSON schema

  - step_id: process_order
    description: Process customer order
    answer_model: order_schema.Order  # Specific Python model

  - step_id: validate_data
    description: Validate input data
    answer_model: validation_rules  # Main schema model

Schema Benefits

Reusability

Use schemas across multiple agents and steps

Maintainability

Update schemas without changing agent configuration

Type Safety

Full validation with detailed error messages

Version Control

Track schema changes separately

Advanced YAML Configuration

Barista Agent Example

See a comprehensive configuration example

Server Configuration

Configure the FastAPI server settings and security features:

server:
  port: 8000
  host: "0.0.0.0"
  workers: 1

  security:
    # Authentication configuration
    enable_auth: true
    auth_type: jwt  # Options: "jwt", "api_key"
    jwt_secret_key: "$JWT_SECRET_KEY"
    # api_key_url: "https://your-api.com/validate-key"  # For API key auth

    # Rate limiting configuration
    enable_rate_limiting: true
    redis_url: "$REDIS_URL"  # Redis URL for rate limiting
    rate_limit_times: 100  # Number of allowed requests
    rate_limit_seconds: 60  # Time period for rate limiting in seconds

    # CSRF protection configuration
    enable_csrf_protection: true
    csrf_secret_key: "$CSRF_SECRET_KEY"

    # CORS configuration
    allowed_origins:
      - "https://your-frontend.com"
      - "http://localhost:3000"  # For development

  # Session store configuration
  session:
    store_type: "memory"  # Options: "memory", "production"
    default_ttl: 3600
    cache_ttl: 3600
    # For production session store:
    # database_url: "$DATABASE_URL"
    # redis_url: "$REDIS_URL"
    # kafka_brokers: "$KAFKA_BROKERS"
    # events_enabled: true

Security Configuration Examples

server:
  security:
    enable_auth: true
    auth_type: jwt
    jwt_secret_key: "$JWT_SECRET_KEY"
    enable_rate_limiting: true
    rate_limit: "100/minute"

Important Security Warning: Token Generation EndpointThe /auth/token endpoint is automatically exposed when JWT authentication is enabled. This endpoint allows generating JWT tokens for testing purposes and should never be available in production environments.Security measures in place:

It requires the enable_token_endpoint configuration option to be set to true in development or testing configurations.
It should be disabled or removed in production deployments

For production JWT authentication, implement your own secure token generation service that:

Validates user credentials properly
Uses secure session management
Implements proper user authentication flows
Issues tokens with appropriate expiration times
Logs authentication attempts for security monitoring

LLM Configuration

Supported Providers

from nomos.llms import LLMConfig
llm = LLMConfig(provider="openai", model="gpt-4o-mini")

YAML LLM Configuration

llm:
  provider: openai
  model: gpt-4o-mini

Generate YAML Schema

Create a JSON schema for your configuration to enable editor validation and autocompletion:

nomos schema --output agent.schema.json

Include the schema in your YAML file:

# yaml-language-server: $schema=./agent.schema.json

Tool Configuration

New in v0.2.4: You can now specify tools directly in your agent configuration file

name: my-agent
persona: A helpful assistant
steps:
  - step_id: start
    # ... step configuration
start_step_id: start

# Tool configuration - NEW in v0.2.4
tools:
  tool_files:
    - "barista_tools.py"    # Python module
    - "tools.my_tools"      # File path
  external_tools:
    - tag: "@pkg/itertools.combinations"
      name: "combinations"
    - tag: "@crewai/FileReadTool"
      name: "file_read_tool"
    - tag: "@langchain/google_search"
      name: "google_search"
  tool_arg_descriptions:
    add_to_cart:
      coffee_type: "Coffee type (e.g., Espresso, Latte, Cappuccino)"
      size: "Size of the coffee (Small, Medium, Large)"

Custom Tool Files

You can organize your own tools in Python modules:

# tools/my_tools.py
def greet(name: str) -> str:
    """Return a simple greeting."""
    return f"Hello {name}!"

tools = [greet]

Tool Loading Options

Configuration File (Recommended)
CLI Flags (Legacy)

# In config.agent.yaml
tools:
  tool_files:
    - "my_tools"              # Load as module
    - "tools/custom_tools.py" # Load as file path

Step Examples

You can provide decision examples for any step. Each example contains the user context and the expected decision. NOMOS retrieves relevant examples using embeddings and includes them in the system prompt to guide the model.

steps:
  - step_id: start
    description: Initial step
    examples:
      - context: "User asks for the time"
        decision: "Answer with the current time."
        visibility: always
      - context: "sqrt 4"
        decision: "Call sqrt tool"
        visibility: dynamic

Use the max_examples and threshold settings in AgentConfig to control how many examples are displayed and the minimum similarity required.

Error Handling Configuration

name: my-agent
# ... other config
max_errors: 3  # Maximum consecutive errors before stopping
max_iter: 10   # Maximum iterations per interaction

Environment Variables

Common environment variables for NOMOS agents:

Variable	Description	Required
`OPENAI_API_KEY`	OpenAI API key	If using OpenAI
`MISTRAL_API_KEY`	Mistral API key	If using Mistral
`GOOGLE_API_KEY`	Google API key	If using Gemini
`HUGGINGFACE_API_TOKEN`	HuggingFace token	If using HuggingFace
`ANTHROPIC_API_KEY`	Anthropic API key	If using Anthropic
`JWT_SECRET_KEY`	JWT secret key	If using JWT authentication
`CSRF_SECRET_KEY`	CSRF secret key	If using CSRF protection
`API_KEY_VALIDATION_URL`	API key validation endpoint URL	If using API key authentication
`DATABASE_URL`	Database connection URL	If using production session store
`REDIS_URL`	Redis connection URL	If using Redis for sessions
`KAFKA_BROKERS`	Kafka broker URLs	If using Kafka for events

Using Environment Variables in Configuration

You can reference environment variables in your YAML configuration using the $ prefix:

name: my-secure-agent
llm:
  provider: openai
  api_key: "$OPENAI_API_KEY"  # References environment variable

server:
  security:
    jwt_secret_key: "$JWT_SECRET_KEY"
    csrf_secret_key: "$CSRF_SECRET_KEY"
  session:
    database_url: "$DATABASE_URL"
    redis_url: "$REDIS_URL"

Variable	Description	Required
`OPENAI_API_KEY`	OpenAI API key	If using OpenAI
`MISTRAL_API_KEY`	Mistral API key	If using Mistral
`GOOGLE_API_KEY`	Google API key	If using Gemini
`HUGGINGFACE_API_TOKEN`	HuggingFace token	If using HuggingFace
`ANTHROPIC_API_KEY`	Anthropic API key	If using Anthropic

Complete Configuration Example

Here’s a comprehensive configuration example that includes all security features:

name: "secure-production-agent"
persona: "You are a secure AI assistant with comprehensive security features enabled."

# Agent steps
steps:
  - step_id: "start"
    description: "Initial greeting and task identification"
    available_tools: ["get_time", "calculator"]
    routes:
      - target: "end"
        condition: "Task is complete"
  - step_id: "end"
    description: "Final response and goodbye"

start_step_id: "start"
max_errors: 3
max_iter: 10

# LLM configuration
llm:
  provider: "openai"
  model: "gpt-4o-mini"
  temperature: 0.7
  max_tokens: 1000
  api_key: "$OPENAI_API_KEY"

# Server configuration with JWT security
server:
  port: 8000
  host: "0.0.0.0"
  workers: 4

  security:
    # JWT Authentication
    enable_auth: true
    auth_type: "jwt"
    jwt_secret_key: "$JWT_SECRET_KEY"

    # Rate limiting
    enable_rate_limiting: true
    rate_limit: "100/minute"

    # CSRF protection
    enable_csrf_protection: true
    csrf_secret_key: "$CSRF_SECRET_KEY"

    # CORS configuration
    allowed_origins:
      - "https://your-frontend.com"
      - "https://admin.your-domain.com"

  # Production session store
  session:
    store_type: "production"
    default_ttl: 3600
    cache_ttl: 1800
    database_url: "$DATABASE_URL"
    redis_url: "$REDIS_URL"
    kafka_brokers: "$KAFKA_BROKERS"
    events_enabled: true

# Tools configuration
tools:
  files:
    - "custom_tools.py"
  ext:
    - tag: "@pkg/math.sqrt"
      name: "sqrt"
    - tag: "@langchain/calculator"
      name: "calculator"

# Logging configuration
logging:
  enable: true
  handlers:
    - type: "stderr"
      level: "INFO"
      format: "{time:YYYY-MM-DD HH:mm:ss} | {level} | {message}"
    - type: "file"
      level: "DEBUG"
      format: "{time:YYYY-MM-DD HH:mm:ss} | {level} | {file}:{line} | {message}"

Configuration Examples

More configuration examples are available in the cookbook:

Secure Agent Example

Production-ready secure configuration

Barista Agent

Complete coffee ordering workflow

Financial Advisor

Budget planning and financial advice

General Bot

Basic conversational agent

Travel Planner

Travel planning assistant

Getting Started

Why NOMOS?

Building Blocks

Tools

Development & Deployment

Quality Assurance

Examples & Guides

​Python API Configuration

​Basic Agent Setup

​YAML Configuration

​Basic YAML Config

​Schema Configuration

​Schema File Formats

​JSON Schema Files

​Python Schema Files

​Schema Referencing

​Schema Benefits

Reusability

Maintainability

Type Safety

Version Control

​Advanced YAML Configuration

Barista Agent Example

​Server Configuration

​Security Configuration Examples

​LLM Configuration

​Supported Providers

​YAML LLM Configuration

​Generate YAML Schema

​Tool Configuration

​Custom Tool Files

​Tool Loading Options

​Step Examples

​Error Handling Configuration

​Environment Variables

​Using Environment Variables in Configuration

​Complete Configuration Example

​Configuration Examples

Secure Agent Example

Barista Agent

Financial Advisor

General Bot

Travel Planner

Python API Configuration

Basic Agent Setup

YAML Configuration

Basic YAML Config

Schema Configuration

Schema File Formats

JSON Schema Files

Python Schema Files

Schema Referencing

Schema Benefits

Advanced YAML Configuration

Server Configuration

Security Configuration Examples

LLM Configuration

Supported Providers

YAML LLM Configuration

Generate YAML Schema

Tool Configuration

Custom Tool Files

Tool Loading Options

Step Examples

Error Handling Configuration

Environment Variables

Using Environment Variables in Configuration

Complete Configuration Example

Configuration Examples