Skip to main content

​
Requirements

TypeAgent requires Python 3.12 or later. Check your Python version: 
python --version
If you need to upgrade, visit python.org.

​
Installation Methods

The simplest way to install TypeAgent:
pip install typeagent
To install with development dependencies:
pip install typeagent[dev]

​
Virtual Environment Setup

It’s strongly recommended to use a virtual environment to isolate TypeAgent dependencies from your system Python.
Using Python’s built-in venv module:
# Create virtual environment
python -m venv .venv

# Activate on Linux/macOS
source .venv/bin/activate

# Activate on Windows
.venv\Scripts\activate

# Install TypeAgent
pip install typeagent

​
Environment Variables

TypeAgent requires API credentials for the LLM provider you’re using. Set these environment variables before running your code.

​
OpenAI Setup

1

Get API Key

Create an API key at OpenAI Platform
2

Set Environment Variables

export OPENAI_API_KEY="your-api-key-here"
export OPENAI_MODEL="gpt-4o"

​
Azure OpenAI Setup

If using Azure-hosted OpenAI: 
export AZURE_OPENAI_API_KEY="your-azure-key"
export AZURE_OPENAI_ENDPOINT="https://YOUR_RESOURCE.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT/chat/completions?api-version=2023-05-15"
export AZURE_OPENAI_ENDPOINT_EMBEDDING="https://YOUR_RESOURCE.openai.azure.com/openai/deployments/YOUR_EMBEDDING_DEPLOYMENT/embeddings?api-version=2024-08-01-preview"
If both OPENAI_API_KEY and AZURE_OPENAI_API_KEY are set, OpenAI (non-Azure) takes precedence.

​
Using .env Files

For convenience, create a .env file in your project directory:
.env
OPENAI_API_KEY=your-api-key-here
OPENAI_MODEL=gpt-4o
Then load it in your Python code: 
from dotenv import load_dotenv

load_dotenv()  # Call this before importing typeagent
The python-dotenv package is automatically installed as a TypeAgent dependency, so you can use it immediately.

​
Core Dependencies

TypeAgent automatically installs these key dependencies:
PackagePurpose
openaiOpenAI API client
pydantic-ai-slim[openai]Provider-agnostic AI model interface
azure-identityAzure authentication
tiktokenToken counting for OpenAI models
typechatType-safe AI interaction
numpyNumerical operations for embeddings
python-dotenvEnvironment variable management

​
Optional Dependencies

​
Logfire (Observability)

For production monitoring and debugging: 
pip install typeagent[logfire]
This adds:
  • logfire: Structured logging and observability
  • opentelemetry-instrumentation-httpx: HTTP tracing

​
Development Tools

For contributors and advanced users: 
pip install typeagent[dev]
This includes:
  • pytest, pytest-asyncio, pytest-mock: Testing
  • pyright: Type checking
  • coverage: Code coverage
  • isort: Import sorting
  • Email ingestion tools (google-api-python-client, msgraph-sdk)

​
Verify Installation

Confirm TypeAgent is installed correctly:
verify.py
import typeagent
import sys

print(f"Python version: {sys.version}")
print(f"TypeAgent imported successfully")
print(f"Available exports: {typeagent.__all__}")
Run it: 
python verify.py
Expected output: 
Python version: 3.12.x ...
TypeAgent imported successfully
Available exports: ['create_conversation']

​
Troubleshooting

Solution: Make sure you’ve activated your virtual environment and installed TypeAgent:
source .venv/bin/activate  # or .venv\Scripts\activate on Windows
pip install typeagent
Error: RuntimeError: This package requires Python 3.12 or laterSolution: Upgrade to Python 3.12+:
Error: openai.AuthenticationError: Incorrect API key providedSolution: Verify your API key is set correctly:
echo $OPENAI_API_KEY  # Should show your key
If empty, set it:
export OPENAI_API_KEY="sk-..."
Issue: Module not found despite installationSolution: Ensure you’re using the correct Python interpreter:
python -m pip install typeagent
python -m pip show typeagent

​
Next Steps

Quickstart Tutorial

Build your first TypeAgent application

API Reference

Explore the complete API documentation

​
Upgrading TypeAgent

To upgrade to the latest version: 
pip install --upgrade typeagent
TypeAgent is under active development. Review the CHANGELOG before upgrading to understand breaking changes.

​
Migration Notes

If you’re upgrading from an earlier version, be aware of these key changes:

​
Version 0.4.0 (Current)

  • Provider-agnostic models: Use provider:model spec strings (e.g., "openai:gpt-4o")
  • New environment variables: OPENAI_MODEL and OPENAI_EMBEDDING_MODEL for overriding defaults
  • Breaking: AsyncEmbeddingModel replaced with IEmbedder/IEmbeddingModel protocols
  • Storage APIs: All storage provider APIs are now async

​
Version 0.3.x

  • Build system: Migrated from setuptools to uv_build
  • Dev dependencies: Install with typeagent[dev] instead of separate package
  • Project structure: Source moved to src/typeagent/
See the full CHANGELOG for detailed migration guidance.

Build docs developers (and LLMs) love

Get started for freeTalk to us