atomic-schemas
Atomic Agents Schema Design: This skill should be used when the user asks to "create a schema", "define input/output", "add fields", "validate data", "Pydantic schema", "BaseIOSchema", or needs guidance on schema design patterns, field definitions, validators, and type constraints for Atomic Agents applications.
Installation
Details
Usage
After installing, this skill will be available to your AI coding assistant.
Verify installation:
skills listSkill Instructions
description: This skill should be used when the user asks to "create a schema", "define input/output", "add fields", "validate data", "Pydantic schema", "BaseIOSchema", or needs guidance on schema design patterns, field definitions, validators, and type constraints for Atomic Agents applications.
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
- Always provide descriptions - LLMs use them to understand field purpose
- Constrain appropriately - Use ge, le, min_length, max_length, Literal
- Validate business rules - Use field_validator and model_validator
- Use Optional sparingly - Only when truly optional
- Provide sensible defaults - When there's a clear default value
- Document with docstrings - Explain the schema's purpose
- Compose for complexity - Nest schemas for structured data
References
See references/ for:
advanced-patterns.md- Complex schema patternsvalidation-patterns.md- Advanced validator examples
See examples/ for:
common-schemas.py- Ready-to-use schema templates
More by BrainBlend-AI
View allRelease a new version of atomic-agents to PyPI and GitHub. Use when the user asks to "release", "publish", "deploy", or "bump version" for atomic-agents.
Atomic Agents Context Providers: This skill should be used when the user asks to "create context provider", "dynamic context", "inject context", "BaseDynamicContextProvider", "share data between agents", or needs guidance on context providers, dynamic prompt injection, and sharing information across agents in Atomic Agents applications.
Atomic Agents Tool Development: This skill should be used when the user asks to "create a tool", "implement BaseTool", "add tool to agent", "tool orchestration", "external API tool", or needs guidance on tool development, tool configuration, error handling, and integrating tools with agents in Atomic Agents applications.
Atomic Agents System Prompt Design: This skill should be used when the user asks to "write system prompt", "configure SystemPromptGenerator", "prompt engineering", "background steps output_instructions", "improve agent prompt", or needs guidance on structuring system prompts, writing effective instructions, and optimizing agent behavior in Atomic Agents applications.