ChatKit

agent-framework-chatkit converts OpenAI ChatKit thread items into Agent Framework messages and converts streamed agent updates back into ChatKit events. Use it when you want a ChatKit frontend with an Agent Framework Python backend.

The integration provides:

  • ThreadItemConverter for converting ChatKit thread items and attachments.
  • stream_agent_response() for converting streamed agent updates to ChatKit events.
  • simple_to_agent_input() for the default message-conversion path.

Prerequisites

  • Python 3.11 or later.
  • A backend web framework such as FastAPI.
  • Node.js for the ChatKit frontend.
  • A Microsoft Foundry project with a deployed model.
  • Azure CLI authentication (az login).
  • A ChatKit domain key for a production frontend domain.

Install the package

pip install agent-framework-chatkit agent-framework-foundry --pre

Configure the Foundry model

The sample creates the agent with FoundryChatClient and AzureCliCredential. Set the project endpoint and model deployment before you start the backend:

export FOUNDRY_PROJECT_ENDPOINT="https://<account>.services.ai.azure.com/api/projects/<project>"
export FOUNDRY_MODEL="<model-deployment>"

Create a ChatKit server

Subclass ChatKitServer, create the Agent Framework agent, and configure a converter for thread items and attachments.

Convert and stream responses

Load the thread history, convert it to Agent Framework messages, run the agent in streaming mode, and yield ChatKit events.

Call agent.run(..., stream=True) first, then pass that response stream and the ChatKit thread ID to stream_agent_response(...). Don't pass the agent itself to the converter.

ThreadItemConverter preserves StructuredInputItem status and represents each question as answered, skipped, or unanswered in a user message. Override the asynchronous structured_input_to_input() method to customize formatting or redact answers. Return one Message, a list of messages, or None to omit the item.

The converter also preserves completed GeneratedImageItem values as model context on later turns. The default conversion creates a user Message with a short text preface and the generated image URI. Data URIs retain their embedded media type, external URLs use image/*, and unfinished items without an image are skipped.

Override the asynchronous generated_image_to_input() method to customize generated image context, such as resolving a private image URL. Return one Message, a list of messages, or None to omit the item.

The complete sample also demonstrates SQLite-backed threads, file uploads, attachment storage, actions, and interactive widgets.

Warning

The ChatKit frontend is loaded from OpenAI's CDN and makes outbound requests to OpenAI domains. It can't currently be self-hosted and isn't suitable for air-gapped environments.

Next steps