integrations
Bring the systems you use. Psych connects the run.
Connect models, tools, storage, sandboxes, and telemetry through built-in adapters or small ports. Every entry below states what works today and what you need to supply.
- built in an adapter in the package
- extra in the package, behind a pip extra
- compatible works through an existing adapter
- yours a port you implement, or a template you copy
Model providers
Psych speaks the OpenAI-compatible wire protocol rather than depending on a provider SDK. One client reaches anything that speaks it, and the model is a port, so a provider it does not speak is one adapter away.
OpenAIbuilt inpsych_runtime.OpenAICompatibleClient
OpenAICompatibleClient against api.openai.com.
OpenAI-compatible gatewayscompatiblebase_url=
Point base_url at a compatible provider or your own gateway and the same client works.
Your own adapteryourspsych_runtime.ModelClient
Implement ModelClient for a provider with a different wire protocol. The fake model is one such adapter.
Price tablebuilt inpsych_runtime.DEFAULT_PRICES
Curated rates for common models ship in DEFAULT_PRICES. Override or replace them with a PriceResolver.
Stores
Four adapters against one contract suite, run against real databases in CI. The in-memory store is a real Store that keeps nothing across a process.
In memorybuilt inpsych_runtime.InMemoryStore
For tests and the first run. No persistence.
PostgreSQLextrapip install psych-runtime[postgres]
asyncpg, with sequential forward-only migrations.
MySQLextrapip install psych-runtime[mysql]
aiomysql, same contract, its own migrations.
DynamoDBextrapip install psych-runtime[dynamodb]
aioboto3, conditional writes for the append and the claim.
Blob stores
For tool results too large to sit inline in a record. Without one, a result over the limit records an explicit failure rather than a silent truncation.
In memorybuilt inpsych_runtime.InMemoryBlobStore
Tests.
Filesystembuilt inpsych_runtime.store.blob_fs
A directory on disk.
S3built inpsych_runtime.store.blob_s3
Any S3-compatible object store.
Tools and agents
Tools are code, HTTP or MCP. Agents elsewhere are reached over A2A.
MCP serversbuilt inpsych_runtime.McpServer
Streamable HTTP, and the earlier HTTP+SSE transport. Pooled by (scope, server, credential). Deferred catalogue disclosure for large servers. No stdio.
MCP OAuth 2.1built inpsych_runtime.McpOAuth
client_credentials and authorization_code with PKCE, dynamic client registration, scope step-up on a 403. You supply the redirect port; Psych runs no browser.
HTTP endpointsbuilt inpsych_runtime.HttpTool
A URL, a method, a JSON schema and a credential name. Creatable at runtime by end users.
Agent2Agentbuilt inpsych_runtime.A2APeer
Expose a Run as an A2A Task, or call a remote agent as a tool source.
Code execution
In-process sandboxing is rejected, because RestrictedPython, trimmed builtins and AST filtering are all escapable. A separate process is the floor, not a ceiling: how much the two backends contain differs, and the difference matters.
Subprocessbuilt inpsych_runtime.sandbox.SubprocessSandbox
A fresh interpreter under CPU, memory and file-size rlimits, dropped to an unprivileged uid. It shares the host filesystem, and its network denial is a self-report rather than enforcement.
Containerbuilt inpsych_runtime.sandbox.ContainerSandbox
One container per program. Filesystem and network isolation are the kernel's, not a promise the program can break.
Observability
The library calls the OpenTelemetry API only. The [otel] extra installs the SDK for you to configure, and never an exporter: that is a deployment's decision.
OpenTelemetryextrapip install psych-runtime[otel]
Eight declared spans under gen_ai.* conventions, with conformance tests.
Your loggercompatiblelogging
Psych attaches a NullHandler and configures nothing else.
Your application
Psych refuses to own an HTTP server, so these are patterns the public API documents rather than integrations it ships.
FastAPIyourspsych new api --template fastapi
A template: routes plus a separate Worker process, sharing a Store.
Djangoyoursdocs: The public API
Calling the async API from synchronous code.
Celery and worker queuesyoursdocs: The public API
Where a Worker lives when you already have a worker process.
Coding agentsbuilt inpsych skills install
26 guides covering the runtime's features, installable into your project.
Writing your own. A Store or BlobStore adapter is correct when it passes the shared contract suite, the same tests the shipped four pass. A model provider with a different wire protocol is one port.