Deploy Pydantic AI

Deploy and Host Pydantic AI on Railway

Pydantic AI is a typed Python framework for building reliable AI agents with structured outputs, multi-provider model support, tool integration, and production-focused application patterns.

This Railway template deploys a ready-to-use Pydantic AI agent runtime with a built-in web chat interface and PostgreSQL-backed persistent conversation memory.

About Hosting Pydantic AI

This template provides a lightweight production-oriented Pydantic AI deployment that runs as a FastAPI application.

The application includes a browser-based chat interface, REST API endpoints, multi-provider model configuration, persistent conversation history, and PostgreSQL storage.

Unlike a stateless demo chatbot, conversations are stored in PostgreSQL using Pydantic AI's native message history format, allowing conversations to survive application restarts and redeployments.

Common Use Cases

• Build and host AI assistants
• Create persistent AI chat applications
• Build internal AI tools
• Prototype Pydantic AI agents
• Expose AI agents through REST APIs
• Run multi-provider AI applications
• Build typed AI backends
• Experiment with structured AI agent workflows
• Add persistent conversation memory to AI applications
• Self-host an AI chat interface with your own provider credentials

Dependencies for Pydantic AI Hosting

This template includes:

• Pydantic AI — Typed AI agent runtime
• FastAPI — HTTP API and web application layer
• PostgreSQL — Persistent conversation history
• Railway Private Networking — Internal database connectivity

Redis is not required.

The Pydantic AI application itself does not require a persistent volume because conversation state is stored in PostgreSQL.

Features

• Built-in web chat interface
• Persistent multi-turn conversations
• PostgreSQL-backed conversation history
• OpenAI support
• Anthropic support
• Google Gemini support
• Groq support
• Configurable system prompt
• FastAPI REST API
• OpenAPI documentation
• Health checks
• Optional Bearer-token API protection
• Configurable PostgreSQL connection pool
• Non-root Docker runtime
• Reproducible builds using uv.lock

Persistent Conversation Memory

Conversation history is stored in PostgreSQL using Pydantic AI's native message representation.

Each conversation is assigned a UUID and stores:

• User messages
• Assistant responses
• Pydantic AI message metadata
• Creation timestamp
• Last update timestamp

When the browser reloads, the application restores the active conversation from PostgreSQL automatically.

This means chat history survives:

• Browser refreshes
• Application restarts
• Railway redeployments
• Container replacement

The Pydantic AI service itself remains stateless.

Supported AI Providers

The template supports multiple model providers.

Select the provider using:

MODEL_PROVIDER

and configure the model using:

MODEL_NAME

Only the API key for the selected provider is required for chat requests.

Important Environment Variables

Database

DATABASE_URL

Required PostgreSQL connection string used for persistent conversation history.

This template automatically references the PostgreSQL service through Railway service variables.

Model Configuration

MODEL_PROVIDER

Selects the active AI provider.

Supported values:

• openai
• anthropic
• google
• groq

MODEL_NAME

Defines the model used by the selected provider.

Provider Credentials

Depending on the selected provider, configure one of:

• OPENAI_API_KEY
• ANTHROPIC_API_KEY
• GOOGLE_API_KEY
• GROQ_API_KEY

Provider keys are optional at application startup, but chat requests require the key corresponding to the selected provider.

System Prompt

SYSTEM_PROMPT

Optional instructions applied to every agent run.

API Protection

APP_API_KEY

Optional Bearer token used to protect chat and conversation API endpoints.

If left empty, the built-in browser chat works without API authentication.

If configured, API clients must send:

Authorization: Bearer YOUR_API_KEY

Database Pool

Optional PostgreSQL tuning variables:

• DB_POOL_MIN_SIZE
• DB_POOL_MAX_SIZE
• DB_POOL_TIMEOUT

The defaults are suitable for small Railway deployments.

Web Interface

The built-in web interface is available at:

/

After Railway assigns a public domain, open:

https://your-pydantic-ai-domain.up.railway.app/

The interface includes:

• Persistent chat history
• New Chat button
• Active provider and model display
• Conversation restoration after refresh
• Mobile-responsive layout
• Error handling for missing provider keys and backend failures

No separate frontend service is required.

API Endpoints

Health

GET /health

Healthy response:

{
  "status": "ok",
  "database": "ok"
}

The health endpoint checks PostgreSQL connectivity but does not call an LLM provider.

Configuration

GET /api/config

Returns the active provider and model configuration without exposing API keys.

Chat

POST /api/chat

Example request:

{
  "message": "Hello"
}

Example response:

{
  "response": "Hello! How can I help?",
  "conversation_id": "11111111-2222-3333-4444-555555555555",
  "model": "gpt-4o-mini",
  "provider": "openai"
}

To continue an existing conversation:

{
  "message": "What did I ask you earlier?",
  "conversation_id": "11111111-2222-3333-4444-555555555555"
}

Create Conversation

POST /api/conversations

Get Conversation

GET /api/conversations/{conversation_id}

Delete Conversation

DELETE /api/conversations/{conversation_id}

OpenAPI Documentation

FastAPI automatically provides interactive API documentation at:

/docs

Example:

https://your-pydantic-ai-domain.up.railway.app/docs

Railway Deployment

This template deploys two services:

Internet
   │
   ▼
Railway HTTPS
   │
   ▼
Pydantic AI
   :8000
      │
      │ Railway Private Network
      ▼
PostgreSQL
   :5432

Pydantic AI

Recommended settings:

• Public Domain: enabled
• Port: 8000
• Health Check: /health
• Persistent Volume: not required
• Custom Start Command: not required
• RAILWAY_RUN_UID: not required

PostgreSQL

Recommended settings:

• Public Domain: disabled
• Private networking: enabled
• Port: 5432
• Persistent volume: required

The Pydantic AI service connects to PostgreSQL using:

${{Postgres.DATABASE_URL}}

After Deployment

1. Wait for PostgreSQL to become available.
2. Wait for the Pydantic AI service to become healthy.
3. Generate a public domain for the Pydantic AI service on port 8000.
4. Configure your preferred MODEL_PROVIDER.
5. Configure MODEL_NAME.
6. Add the API key for the selected model provider.
7. Open the public URL.
8. Send your first message.
9. Refresh the browser and verify that the conversation is restored.
10. Optionally configure APP_API_KEY for external API clients.

Security Notes

For production deployments:

• Keep PostgreSQL private
• Never expose provider API keys to frontend applications
• Do not expose DATABASE_URL
• Use APP_API_KEY when external clients need protected API access
• Rotate credentials if exposed
• Use scoped provider credentials where supported
• Review persisted conversations before storing sensitive information
• Keep detailed application logs free of secrets

The built-in browser UI intentionally uses safe text rendering rather than injecting model output as raw HTML.

Pydantic AI vs Alternatives

Pydantic AI is especially well suited for developers who want strongly typed AI applications using Python and Pydantic-style validation.

Why Deploy Pydantic AI on Railway?

Railway provides a straightforward environment for running both the application runtime and PostgreSQL persistence layer.

Deploying Pydantic AI on Railway provides:

• Automatic HTTPS domains
• Persistent PostgreSQL storage
• Private database networking
• Simple environment variable management
• Built-in deployment logs
• Easy redeployments
• No application volume requirement
• No Redis dependency
• A ready-to-use web chat interface
• Persistent multi-turn AI conversations
• Multi-provider model flexibility