Atomic Agents Schema Design

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