Pydantic AI

Available for: Python agents (configured via a TypeScript helper).

Pydantic AI is a Python-only agent framework, but the helper for it lives in @zespan/sdk (TypeScript). There’s no Python-side zespan.integrations.pydantic_ai module and no wrapper function to call from your agent code — getPydanticAIConfig() is a one-off config generator, not a runtime integration.

How this integration works

Pydantic AI instruments itself with Logfire, which is OpenTelemetry-native. Instead of wrapping calls in your agent code, you point Logfire’s OTel exporter at Zespan’s ingest endpoint using environment variables. getPydanticAIConfig(otlpEndpoint) builds that exact set of environment variables for you from a single OTLP endpoint argument, so you don’t have to hand-write Logfire’s variable names yourself. Because it’s a config generator rather than something that runs inside your Python process, you typically call it once — from wherever you already provision the Python agent’s environment (a Node/TS setup script, an internal deploy tool, a Dockerfile build stage, a CI job) — and then apply the resulting values to that process.

Installation

# Wherever you generate the env vars (Node/TS tooling)
npm install @zespan/sdk

# In the Python environment that runs the Pydantic AI agent
pip install pydantic-ai logfire

Usage

Call getPydanticAIConfig() with the OTLP endpoint you want the agent to export to. It returns a plain Record<string, string> — it only builds the values, it does not set them in any environment for you.

import { getPydanticAIConfig } from "@zespan/sdk";

const config = getPydanticAIConfig("http://localhost:4318");

console.log(config);
// {
//   OTEL_EXPORTER_OTLP_ENDPOINT: "http://localhost:4318",
//   OTEL_EXPORTER_OTLP_PROTOCOL: "http/protobuf",
//   OTEL_SERVICE_NAME: "pydantic-ai-agent",
//   LOGFIRE_SEND_TO_LOGFIRE: "false",
// }

What it generates

Variable	Value	Purpose
`OTEL_EXPORTER_OTLP_ENDPOINT`	The `otlpEndpoint` argument you pass in	Where the OTLP exporter sends spans
`OTEL_EXPORTER_OTLP_PROTOCOL`	`http/protobuf`	Wire protocol used for the OTLP export
`OTEL_SERVICE_NAME`	`pydantic-ai-agent`	Service name attached to every exported span
`LOGFIRE_SEND_TO_LOGFIRE`	`false`	Stops Logfire from also forwarding spans to Logfire’s own cloud, so Zespan is the only export destination

Applying the config to your Python process

getPydanticAIConfig() only produces the four values above — getting them into the environment the Python process reads from is a separate step. A few common ways to do that: Write a .env file the Python process loads on startup:

import { writeFileSync } from "node:fs";
import { getPydanticAIConfig } from "@zespan/sdk";

const config = getPydanticAIConfig("http://localhost:4318");

const envFile = Object.entries(config)
  .map(([key, value]) => `${key}=${value}`)
  .join("\n");

writeFileSync(".env", envFile);

Pass them directly when spawning the Python process:

import { spawn } from "node:child_process";
import { getPydanticAIConfig } from "@zespan/sdk";

const config = getPydanticAIConfig("http://localhost:4318");

spawn("python", ["agent.py"], {
  env: { ...process.env, ...config },
});

Or set them manually in whatever mechanism configures the Python environment — these four keys are the entire contract; nothing else needs to change in your Pydantic AI code:

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_SERVICE_NAME=pydantic-ai-agent
export LOGFIRE_SEND_TO_LOGFIRE=false

Once those variables are set, Pydantic AI’s own Logfire integration picks them up automatically:

import logfire
from pydantic_ai import Agent

logfire.configure(send_to_logfire=False)  # OTel export only, no Logfire cloud
logfire.instrument_pydantic_ai()

agent = Agent("openai:gpt-4o", instructions="Be concise.")

result = agent.run_sync("What is the capital of France?")
print(result.output)

There’s no Python-side zespan package involved in this flow. Zespan’s role is limited to generating the right OTel/Logfire environment variables from the TypeScript SDK — everything else is standard Pydantic AI and Logfire instrumentation.

Overview

TypeScript SDK

Python SDK

Advanced SDK Configuration

Integrations

LLM Providers

Agent Frameworks

RAG Frameworks

Vector Databases

Custom / Other

Guides

How this integration works

Installation

Usage

What it generates

Applying the config to your Python process

​How this integration works

​Installation

​Usage

​What it generates

​Applying the config to your Python process

How this integration works

Installation

Usage

What it generates

Applying the config to your Python process