Registry /
llm-agents / agent-framework-chatkit
Install & Compatibility
Where this runs
tested against v1.0.0b260528 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 93.7MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 8.1s · import 0.000s · 92MB
80MB installed
● package 80MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ChatKitClient
✓ from chatkit import ChatKitClient
✗ from agent_framework_chatkit import ChatKitClient
Despite the PyPI package name being `agent-framework-chatkit`, the top-level import path for components is simply `chatkit`.
BasicChatKitAgent
✓ from chatkit.agents import BasicChatKitAgent
✗ from agent_framework_chatkit.agents import BasicChatKitAgent
Similar to `ChatKitClient`, components within submodules also use `chatkit` as the root import path.
This quickstart demonstrates how to initialize the `ChatKitClient`, define and create a simple `BasicChatKitAgent`, and interact with it using text messages. It requires `CHATKIT_API_KEY` and `OPENAI_API_KEY` to be set as environment variables for authentication.
import os
import asyncio
from chatkit import ChatKitClient
from chatkit.agents import BasicChatKitAgent
from chatkit.messages import TextMessage
async def main():
# Ensure CHATKIT_API_KEY and OPENAI_API_KEY are set as environment variables
chatkit_api_key = os.environ.get("CHATKIT_API_KEY", "")
openai_api_key = os.environ.get("OPENAI_API_KEY", "")
if not chatkit_api_key or not openai_api_key:
print("Please set CHATKIT_API_KEY and OPENAI_API_KEY environment variables.")
print("You can obtain these from your respective dashboards (OpenAI and ChatKit). Exiting.")
return
client = ChatKitClient(api_key=chatkit_api_key, openai_api_key=openai_api_key)
agent_name = "my-chatkit-quickstart-agent"
# Create or update a simple agent definition
agent = BasicChatKitAgent(
name=agent_name,
model="gpt-4o", # Recommended to use a recent model
instructions="You are a helpful, concise assistant. Respond briefly to questions."
)
# This method handles creation if the agent doesn't exist, or updates it if it does.
await client.create_agent(agent)
print(f"Agent '{agent_name}' is ready.")
user_message = TextMessage(content="What is the capital of France?")
print(f"\nUser: {user_message.content}")
# Interact with the agent
async for response_message in client.run_agent_message(
agent_name=agent_name,
message=user_message
):
if isinstance(response_message, TextMessage):
print(f"Agent: {response_message.content}")
else:
# Handle other message types like FunctionCallMessage if needed
print(f"Agent sent a non-text message: {type(response_message).__name__}")
if __name__ == "__main__":
asyncio.run(main())
Debug
Known issues
breakingThe `agent-framework-chatkit` library is currently in beta. This means breaking changes to APIs, class structures, and behavior are frequent and may occur without major version bumps (e.g., within `1.0.0bX` releases).fixRegularly check the official documentation and GitHub releases for updates and adjust your code accordingly. For stability, consider pinning specific beta versions (`pip install agent-framework-chatkit==1.0.0bYYYYMMDD`) but be prepared to upgrade.
affects: 1.0.0b onwards
gotchaThe PyPI package name is `agent-framework-chatkit`, but the top-level import for components is `chatkit` (e.g., `from chatkit import ChatKitClient`). Directly importing from `agent_framework_chatkit` will result in a `ModuleNotFoundError`.fixAlways use `from chatkit import ...` for importing library components, not `from agent_framework_chatkit import ...`.
affects: All beta versions
gotchaBoth `CHATKIT_API_KEY` (for ChatKit service) and `OPENAI_API_KEY` (for underlying OpenAI models) are required for full functionality. Misconfigured or missing keys will lead to authentication failures.fixEnsure both environment variables `CHATKIT_API_KEY` and `OPENAI_API_KEY` are correctly set with valid keys obtained from OpenAI and ChatKit, respectively.
affects: All beta versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'agent_framework_chatkit'
Attempted to import library components using the PyPI package name (`agent_framework_chatkit`) instead of the correct import root (`chatkit`).
fixCorrect the import statement. For example, change `from agent_framework_chatkit import ChatKitClient` to `from chatkit import ChatKitClient`.
openai.AuthenticationError: Incorrect API key provided
The `OPENAI_API_KEY` environment variable is either missing, empty, or contains an invalid key.
fixVerify that your `OPENAI_API_KEY` environment variable is correctly set with a valid OpenAI API key. This key is used by the underlying language models.
ChatKit API returned an error: Unauthorized
The `CHATKIT_API_KEY` environment variable is either missing, empty, or contains an invalid key, preventing authentication with the ChatKit service.
fixEnsure your `CHATKIT_API_KEY` environment variable is correctly set with a valid ChatKit API key. This key is for authenticating with the ChatKit service itself.
AttributeError: 'ChatKitClient' object has no attribute 'run_agent_message' (or similar method not found)
The API method being called may have changed or been removed due to the library's beta status, or an outdated version of the library is installed.
fixUpdate to the latest beta version (`pip install --upgrade agent-framework-chatkit`) and consult the official documentation for the current API methods and usage patterns.
Upgrade
Version history
1.0.0b260528latest on PyPI · released May 28, 2026
Audit
Dependencies
agent-frameworkrequiredThis package integrates with the Microsoft Agent Framework; it is a core prerequisite for its intended use.
openairequiredThe library internally uses the OpenAI API for language models, requiring the `openai` package and an API key.
Resources
No resource links recorded.