CopilotKit Python SDK

Common errors

• ModuleNotFoundError: No module named 'copilotkit'

  cause The `copilotkit` package is not installed in your Python environment.
  fix Run `pip install copilotkit`

• TypeError: 'OpenAI' object has no attribute 'api_key'

  cause You are likely using an outdated version of the `openai` library (before v1.0.0) with the `OpenAI(api_key=...)` syntax, which is for v1+.
  fix Upgrade the `openai` library: `pip install --upgrade openai`. If using older OpenAI, initialize with `openai.api_key = os.environ.get("OPENAI_API_KEY")`.

• LLM calls tool incorrectly or generates invalid arguments.

  cause The LLM's understanding of the tool's signature is derived from its Python type hints and docstrings. Missing or ambiguous type hints (e.g., `location: Any` instead of `location: str`) can lead to malformed tool calls.
  fix Ensure all arguments and return values of functions decorated with `@tool` have precise and correct Python type hints, and clear docstrings.

• uvicorn.config.ConfigError: No 'fast_app' attribute in file 'main.py'.

  cause The `uvicorn` command requires a reference to your FastAPI application instance. The example uses `main:fast_app` meaning `fast_app` in `main.py`.
  fix Verify that your application file (e.g., `main.py`) defines a FastAPI instance named `fast_app` (or whatever name you use) and that you're pointing to it correctly in the `uvicorn` command (e.g., `uvicorn your_file_name:your_app_instance_name`).

Warnings

• gotcha The CopilotKit Python SDK (v0.1.x) is at an earlier development stage compared to the JavaScript/TypeScript frontend SDKs (v1.x). This may lead to feature disparities or slower adoption of new features from the broader CopilotKit ecosystem.
  Fix: Refer to the Python SDK's specific documentation and examples on GitHub for supported features. Align expectations with the current Python SDK version.
• gotcha Tool definition relies heavily on Python type hints. Without accurate type hints for function arguments and return types, the underlying LLM may fail to correctly interpret the tool's schema, leading to incorrect or failed tool calls.
  Fix: Always provide precise type hints for all arguments and the return type of functions decorated with `@tool`.
• gotcha The `CopilotKit` app is designed to be integrated into a web framework (like FastAPI), not run as a standalone Python script that serves HTTP requests directly. Attempts to call the `CopilotKit` instance as a server will fail.
  Fix: Use the provided framework integrations, such as `CopilotKitFastAPI` for FastAPI, to expose your CopilotKit app via a standard web server like Uvicorn.
• deprecated Python 3.9 and older versions are not officially supported. The `requires_python` spec is `<3.13,>=3.10`.
  Fix: Ensure your environment uses Python 3.10, 3.11, or 3.12.

Install

• pip install copilotkit Default Install
• pip install "copilotkit[fastapi]" Install with FastAPI integration

Imports

• CopilotKit

  from copilotkit import CopilotKit

• tool

  from copilotkit import tool

• CopilotKitFastAPI

  from copilotkit.fastapi import CopilotKitFastAPI

  Used for FastAPI integration to expose the CopilotKit app as an API.

Quickstart

This quickstart demonstrates how to initialize a `CopilotKit` application, define and register a tool, and expose it via a FastAPI server. It requires `fastapi` and `uvicorn` to be installed (e.g., `pip install "copilotkit[fastapi]"`). The `OPENAI_API_KEY` environment variable is necessary for the underlying OpenAI client.

import os
from openai import OpenAI
from copilotkit import CopilotKit, tool
from copilotkit.fastapi import CopilotKitFastAPI
from fastapi import FastAPI
import uvicorn

# Ensure OPENAI_API_KEY is set in environment or .env file
openai_api_key = os.environ.get("OPENAI_API_KEY", "")

if not openai_api_key:
    print("Warning: OPENAI_API_KEY not found. Please set it as an environment variable.")
    # For demonstration, we'll continue, but real usage would require a key.

# Initialize OpenAI client (requires openai>=1.0.0)
openai_client = OpenAI(api_key=openai_api_key)

# Create a CopilotKit app instance
app = CopilotKit(openai_client=openai_client)

# Define a tool using the @tool decorator
@tool
def get_current_weather(location: str, unit: str = "fahrenheit") -> dict:
    """Get the current weather in a given location.

    Args:
        location (str): The city and state, e.g. "San Francisco, CA"
        unit (str, optional): The unit of temperature. Defaults to "fahrenheit".

    Returns:
        dict: A dictionary containing temperature and unit.
    """
    print(f"Tool called: get_current_weather for {location} in {unit}")
    if "san francisco" in location.lower():
        return {"temperature": "70", "unit": unit}
    elif "new york" in location.lower():
        return {"temperature": "60", "unit": unit}
    else:
        return {"temperature": "unknown", "unit": unit}

# Register the tool with the CopilotKit app
app.register_tool(get_current_weather)

# Integrate with FastAPI to expose the CopilotKit app
fast_app = FastAPI()
fast_app.include_router(CopilotKitFastAPI(app))

@fast_app.get("/health")
async def health_check():
    return {"status": "ok"}

# To run this example:
# 1. Save the code above as `main.py`.
# 2. Install the necessary dependencies: `pip install "copilotkit[fastapi]"`.
# 3. Set your OpenAI API key: `export OPENAI_API_KEY="your_key_here"` (or use a .env file).
# 4. Run the FastAPI application using Uvicorn from your terminal:
#    `uvicorn main:fast_app --reload --port 8000`
# Your CopilotKit backend will then be accessible at http://localhost:8000/copilotkit
print("CopilotKit app configured. Use `uvicorn main:fast_app --reload --port 8000` to run.")