Skip to main content

Installation

This guide covers how to install the CAIP Agents SDK and configure your environment to start building AI agents.

Prerequisites​

  • Python 3.12 or 3.13 (Download)

  • Linux or macOS operating system (the SDK only supports these platforms)

  • CAIP API Key - Required for LLM API & Agents API access

  • UV Dependency Manager (Optional)(Download)

  • CAIP Space ID (available from the CAIP Portal overview page)

LLM API Integration

The Agents SDK leverages the CAIP LLM API infrastructure, providing unified access to multiple LLM providers through a standardized interface. All agent conversations route through the /v1/chat/completions endpoint.

Platform Support

This SDK only supports Linux and macOS with Python 3.12 or 3.13. Windows is not supported.

1. Create a Virtual Environment​

It is recommended to use a virtual environment to isolate your project dependencies.

uv venv .venv
source .venv/bin/activate
Verify Python Version in venv

After activating the virtual environment, make sure it uses Python 3.12 or Python 3.13 before installing the SDK.

python --version
python -c "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')"

Expected output should show 3.12 or 3.13.

2. Install the SDK​

  1. Add the following configuration to your pyproject.toml:
[tool.uv]
index-url = "https://packages.orbit.bmwgroup.net/artifactory/api/pypi/connected-ai-platform-pypi-local-public/simple"
extra-index-url = ["https://pypi.org/simple"]
  1. Install the SDK:
uv add caip-agents-sdk

3. Environment Configuration​

Create a .env file in your project root directory:

touch .env

Add the following variables:

# Required: Your API key ( Works for both Agents API & LLM API)
CAIP_API_KEY=your_actual_agents_api_key_here

# Required: Your Space ID (from the CAIP Portal overview page)
CAIP_SPACE_ID=your_space_id_here

# Required: Your Agent ID (Obtain after creating agent metadata through the self service portal)
CAIP_AGENT_ID=your_agent_id_here

# Optional: Region for SDK routing. Supported values: ROW or CN
# Default is ROW when not set.
CAIP_REGION=ROW

# Optional: If you need to disable SSL verification (not recommended for production)
CAIP_VERIFY_SSL=false

# Optional: Langfuse Observability is enabled by default.
# Provide keys to send traces to your Langfuse project.
LANGFUSE_SECRET_KEY="sk-lf-..."
LANGFUSE_PUBLIC_KEY="pk-lf-..."
LANGFUSE_BASE_URL="https://langfuse.caip.bmw.cloud"

# Optional: Disable Langfuse Observability if you do not want to emit traces
# CAIP_LANGFUSE_OBSERVABILITY=false
tip

If you don't have a Space ID yet, you can use the CAIP Team shared space for testing: 68ac3e29dfac1aaeaa3c6e1f. ⚠️ Do not use this for production workloads.

4. Verify the Installation​

Run the following command to verify that the SDK is installed correctly:

python -c "from caip_agents_sdk import CAIPAgentsClient; print('CAIP Agents SDK installed successfully')"

Next Steps​