Atomic Agents Schema Design

Schemas are the foundation of Atomic Agents applications. They define the contracts between agents, tools, and external systems using Pydantic models.

Core Principle: Always Use BaseIOSchema

from atomic_agents.lib.base.base_io_schema import BaseIOSchema
from pydantic import Field

class MySchema(BaseIOSchema):
    """Schema description."""
    field: str = Field(..., description="Field description")

Never use plain BaseModel - BaseIOSchema provides Atomic Agents integration features.

Field Definitions

Required Fields

name: str = Field(..., description="The user's full name")

Optional Fields

from typing import Optional
nickname: Optional[str] = Field(default=None, description="Optional nickname")

Fields with Defaults

count: int = Field(default=10, description="Number of items to return")

Constrained Fields

# Numeric constraints
age: int = Field(..., ge=0, le=150, description="Age in years")
score: float = Field(..., ge=0.0, le=1.0, description="Score between 0 and 1")

# String constraints
name: str = Field(..., min_length=1, max_length=100, description="Name")

# List constraints
tags: List[str] = Field(default_factory=list, max_length=10, description="Tags")

Literal Types (Fixed Options)

from typing import Literal
status: Literal["pending", "approved", "rejected"] = Field(..., description="Status")

Enums

from enum import Enum

class Priority(str, Enum):
    LOW = "low"
    MEDIUM = "medium"
    HIGH = "high"

priority: Priority = Field(default=Priority.MEDIUM, description="Priority level")

Validators

Field Validators

from pydantic import field_validator

class EmailSchema(BaseIOSchema):
    email: str = Field(..., description="Email address")

    @field_validator("email")
    @classmethod
    def validate_email(cls, v: str) -> str:
        if "@" not in v:
            raise ValueError("Invalid email format")
        return v.lower()

Model Validators

from pydantic import model_validator

class DateRangeSchema(BaseIOSchema):
    start: str = Field(..., description="Start date")
    end: str = Field(..., description="End date")

    @model_validator(mode="after")
    def validate_range(self) -> "DateRangeSchema":
        if self.end < self.start:
            raise ValueError("end must be after start")
        return self

Common Patterns

Chat Input/Output

class ChatInputSchema(BaseIOSchema):
    """User message input."""
    message: str = Field(..., min_length=1, description="User's message")

class ChatOutputSchema(BaseIOSchema):
    """Agent response output."""
    response: str = Field(..., description="Agent's response")

Structured Analysis Output

class AnalysisOutputSchema(BaseIOSchema):
    """Structured analysis result."""
    summary: str = Field(..., description="Brief summary")
    findings: List[str] = Field(default_factory=list, description="Key findings")
    confidence: float = Field(..., ge=0, le=1, description="Confidence score")
    recommendations: List[str] = Field(default_factory=list, description="Recommendations")

Tool Schemas

class ToolInputSchema(BaseIOSchema):
    """Tool input parameters."""
    query: str = Field(..., description="Search query")

class ToolOutputSchema(BaseIOSchema):
    """Successful tool result."""
    result: str = Field(..., description="Tool result")

class ToolErrorSchema(BaseIOSchema):
    """Tool error result."""
    error: str = Field(..., description="Error message")
    code: Optional[str] = Field(default=None, description="Error code")

Nested Schemas

class AddressSchema(BaseIOSchema):
    """Mailing address."""
    street: str = Field(..., description="Street address")
    city: str = Field(..., description="City")
    country: str = Field(..., description="Country code")

class PersonSchema(BaseIOSchema):
    """Person with address."""
    name: str = Field(..., description="Full name")
    address: AddressSchema = Field(..., description="Mailing address")

Union Types

from typing import Union

class TextContent(BaseIOSchema):
    type: Literal["text"] = "text"
    text: str = Field(..., description="Text content")

class ImageContent(BaseIOSchema):
    type: Literal["image"] = "image"
    url: str = Field(..., description="Image URL")

class MessageSchema(BaseIOSchema):
    content: Union[TextContent, ImageContent] = Field(..., description="Content")

Best Practices

1. Always provide descriptions - LLMs use them to understand field purpose
2. Constrain appropriately - Use ge, le, min_length, max_length, Literal
3. Validate business rules - Use field_validator and model_validator
4. Use Optional sparingly - Only when truly optional
5. Provide sensible defaults - When there's a clear default value
6. Document with docstrings - Explain the schema's purpose
7. Compose for complexity - Nest schemas for structured data

References

See references/ for:

• advanced-patterns.md - Complex schema patterns
• validation-patterns.md - Advanced validator examples

See examples/ for:

• common-schemas.py - Ready-to-use schema templates