PAIS — Pydantic AI Server

PAIS: Pydantic AI Server

The Python agent framework (PAIS) provides the runtime components for AI agents, built on Pydantic AI as the core agent runtime.

Design Principles

Keep It Simple - Thin wrapper around Pydantic AI, minimal abstractions
HTTP-First - All components communicate via HTTP
OpenAI Compatible - Standard /v1/chat/completions API
Kubernetes Native - Environment variable configuration, health probes

Module Structure

pydantic-ai-server/
├── pais/
│   ├── server.py       # AgentServer, create_agent_server(), HTTP routes
│   ├── serverutils.py  # AgentDeps, AgentCard, RemoteAgent, AgentServerSettings
│   ├── tools.py        # DelegationToolset, string-mode handler
│   ├── memory.py       # LocalMemory, RedisMemory, NullMemory
│   └── telemetry.py    # OpenTelemetry tracing, metrics, context propagation
├── tests/              # Test suite (96+ unit tests)
└── Dockerfile          # Container image

Component Relationships

Key Environment Variables

Variable	Required	Description
`AGENT_NAME`	Yes	Agent name
`MODEL_API_URL`	Yes	LLM API base URL (auto-appends `/v1`)
`MODEL_NAME`	Yes	Model name
`AGENT_INSTRUCTIONS`	No	System prompt
`AGENT_DESCRIPTION`	No	Agent description for A2A card
`MCP_SERVERS`	No	Comma-separated MCP server names
`MCP_SERVER_<NAME>_URL`	No	URL for each MCP server
`PEER_AGENTS`	No	Comma-separated peer agent names
`PEER_AGENT_<NAME>_CARD_URL`	No	URL for each peer agent
`MEMORY_TYPE`	No	`local` (default) or `redis`
`MEMORY_ENABLED`	No	Enable/disable memory (default: true)
`MEMORY_CONTEXT_LIMIT`	No	Max history events (default: 6)
`DEBUG_MOCK_RESPONSES`	No	JSON array for mock testing

Architecture

The KAOS Agent wraps pydantic_ai.Agent to add:

Memory persistence: KAOS memory events bridged to Pydantic AI message_history
Sub-agent delegation: Registered as delegate_to_{name} tool functions
MCP tools: Passed as MCPServerStreamableHTTP toolsets
Telemetry: Custom OTel spans for agent runs, tool calls, delegation
HTTP surface: OpenAI-compatible /v1/chat/completions endpoint

The agentic loop (tool calling, retries, streaming) is handled entirely by Pydantic AI.

PAIS: Pydantic AI Server ​

Design Principles ​

Module Structure ​

Component Relationships ​

Key Environment Variables ​

Architecture ​

Further Reading ​