Skip to main content

Recipe: Create an Agent

The Problem​

"We want to spin up an AI agent — a name, a model, a system prompt, some default parameters — without building our own backend to store that configuration or our own plumbing to call an LLM provider. We want an Agent ID we can reference from code, and a Python client we can drop into our application."

Ingredients​

  • A CAIP Space (Space ID) — every agent belongs to a space
  • CAIP Portal access — to register the agent's backend configuration
  • CAIP Agents SDK (caip-agents-sdk) — Python 3.12/3.13, Linux or macOS only
  • A unified CAIP API Key (CAIP_API_KEY) for both Agents API and LLM API

The Recipe​

1. Get a Space ID​

  • Your own Space — find the Space ID on the Space Overview page in the CAIP Portal.
  • CAIP Team Space (testing only) — 68ac3e29dfac1aaeaa3c6e1f. ⚠️ Do not use this for production workloads.

2. Create the agent's backend configuration in the CAIP Portal​

Open https://caip.bmw.cloud/, select your Space, and go to Agent Management. Configure:

PropertyDescriptionExample
nameHuman-readable agent name"Customer Support Agent"
modelLLM model to use"gpt-4", "claude-3-sonnet"
providerModel provider"openai", "anthropic"
instructionsSystem instructions for behavior"You are a helpful assistant..."
descriptionAgent description/system prompt"AI assistant for customer support"
outputFormatResponse format"text", "json"
defaultParametersModel parameters{"temperature": 0.7, "max_tokens": 1024}
metadataCustom metadata{"type": "conversational"}

Click Create — you'll receive an Agent ID (e.g., 507f1f77bcf86cd799439011). This is the backend half of the agent; the SDK client you set up next is the other half.

3. Install the CAIP Agents SDK​

python -m venv .venv
source .venv/bin/activate

pip install caip-agents-sdk \
  --index-url https://packages.orbit.bmwgroup.net/artifactory/api/pypi/connected-ai-platform-pypi-local-public/simple \
  --extra-index-url https://pypi.org/simple

4. Configure your environment​

.env
CAIP_API_KEY=your_actual_api_key_here
CAIP_SPACE_ID=your_space_id_here
CAIP_AGENT_ID=your_agent_id_here
CAIP_REGION=ROW
# Optional: development | test | int | production
# CAIP_ENV=development

Use ROW unless your deployment and data residency require China routing, in which case set CAIP_REGION=CN.

5. Connect, initialize, and run​

import asyncio, os
from dotenv import load_dotenv
from caip_agents_sdk import CAIPAgentsClient
from caip_agents_sdk.exceptions import APIError, AuthenticationError

async def main():
    load_dotenv()
    client = CAIPAgentsClient()

    # Framework-specific client: "pydantic_ai" or "langchain"
    agent = client.create_agent(
        framework="pydantic_ai",
        agent_id=os.getenv("CAIP_AGENT_ID"),
    )

    # Fetches config from CAIP Agents API, wires up the LLM client, registers pending tools
    await agent.initialize()

    # Production pattern: create an explicit thread before first run.
    thread = await client.create_thread(
        agent_id=os.getenv("CAIP_AGENT_ID"),
        thread_data={"title": "Bootstrap Session", "status": "open"},
    )
    agent.thread_id = thread.threadId

    try:
        response = await agent.run("Hello! How can you help me?")
        print(response)
    except AuthenticationError:
        raise RuntimeError("Invalid CAIP_API_KEY or missing permissions")
    except APIError as e:
        raise RuntimeError(f"Agent run failed: {e.status_code} {e.message}")

if __name__ == "__main__":
    asyncio.run(main())

initialize() must run before run()/stream(). You can override the portal's model at runtime with model_name_override="gpt-4-turbo" on create_agent().

from caip_agents_sdk import CAIPAgentsClient

client = CAIPAgentsClient()
settings = client.settings

print("env:", settings.env)
print("region:", settings.region)
print("agents_base_url:", settings.agents_base_url)
print("llm_base_url:", settings.llm_base_url)

Enterprise Hardening Checklist​

  • Store CAIP_API_KEY in your enterprise secret manager, never in source control.
  • Use separate API keys per environment (test, int, production).
  • Keep agent instructions and default parameters under change control (PR-reviewed).
  • Create one thread per end-user session or business conversation boundary.
  • Validate initialization and first-run success in CI smoke tests before rollout.