ChatKit

agent-framework-chatkit konverterar OpenAI ChatKit-trådobjekt till Agent Framework-meddelanden och konverterar strömmade agentuppdateringar tillbaka till ChatKit-händelser. Använd den när du vill ha en ChatKit-klientdel med en Agent Framework-Python serverdel.

Integreringen ger:

  • ThreadItemConverter för konvertering av ChatKit-trådobjekt och bifogade filer.
  • stream_agent_response() för att konvertera strömmade agentuppdateringar till ChatKit-händelser.
  • simple_to_agent_input() för standardsökvägen för meddelandekonvertering.

Förutsättningar

  • Python 3.11 eller senare.
  • Ett webbramverk för backend såsom FastAPI.
  • Node.js för ChatKit-klientdelen.
  • Ett Microsoft Foundry-projekt med en distribuerad modell.
  • Azure CLI autentisering (az login).
  • En ChatKit-domännyckel för en klientdelsdomän för produktion.

Installera paketet

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

Konfigurera Foundry-modellen

Exemplet skapar agenten med FoundryChatClient och AzureCliCredential. Ange projektets slutpunkt och modelldistributionen innan du startar serverdelen:

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

Skapa en ChatKit-server

Underklass ChatKitServer, skapa Agent Framework-agenten och konfigurera en konverterare för trådobjekt och bifogade filer.


This server integrates Agent Framework agents with ChatKit's server protocol,
providing weather information with interactive widgets and time queries through Azure OpenAI.
"""

def __init__(self, data_store: SQLiteStore, attachment_store: FileBasedAttachmentStore):
    super().__init__(data_store, attachment_store)

    logger.info("Initializing WeatherChatKitServer")

    # Create Agent Framework agent with Azure OpenAI
    # For authentication, run `az login` command in terminal
    try:
        self.weather_agent = Agent(
            client=FoundryChatClient(credential=AzureCliCredential()),
            instructions=(
                "You are a helpful weather assistant with image analysis capabilities. "
                "You can provide weather information for any location, tell the current time, "
                "and analyze images that users upload. Be friendly and informative in your responses.\n\n"
                "If a user asks to see a list of cities or wants to choose from available cities, "
                "use the show_city_selector tool to display an interactive city selector.\n\n"
                "When users upload images, you will automatically receive them and can analyze their content. "
                "Describe what you see in detail and be helpful in answering questions about the images."
            ),
            tools=[get_weather, get_time, show_city_selector],
        )
        logger.info("Weather agent initialized successfully with Azure OpenAI")
    except Exception as e:
        logger.error(f"Failed to initialize weather agent: {e}")
        raise

    # Create ThreadItemConverter with attachment data fetcher
    self.converter = ThreadItemConverter(
        attachment_data_fetcher=self._fetch_attachment_data,
    )

    logger.info("WeatherChatKitServer initialized")

Konvertera och strömma svar

Läs in trådhistoriken, konvertera den till Agent Framework-meddelanden, kör agenten i strömningsläge och ge ChatKit-händelser.

    thread: ThreadMetadata,
    input_user_message: UserMessageItem | None,
    context: dict[str, Any],
) -> AsyncIterator[ThreadStreamEvent]:
    """Handle incoming user messages and generate responses.

    This method converts ChatKit messages to Agent Framework format using ThreadItemConverter,
    runs the agent, converts the response back to ChatKit events using stream_agent_response,
    and creates interactive weather widgets when weather data is queried.
    """
    if input_user_message is None:
        logger.debug("Received None user message, skipping")
        return

    logger.info(f"Processing message for thread: {thread.id}")

    try:
        # Collect weather data from get_weather and track the city selector flag for this request
        weather_results: list[WeatherData] = []
        show_city_selector = False

        # Load full thread history from the store
        thread_items_page = await self.store.load_thread_items(
            thread_id=thread.id,
            after=None,
            limit=1000,
            order="asc",
            context=context,
        )
        thread_items = thread_items_page.data

        # Convert ALL thread items to Agent Framework ChatMessages using ThreadItemConverter
        # This ensures the agent has the full conversation context
        agent_messages = await self.converter.to_agent_input(thread_items)

        if not agent_messages:
            logger.warning("No messages after conversion")
            return

        logger.info(f"Running agent with {len(agent_messages)} message(s)")

        # Run the Agent Framework agent with streaming. get_weather appends to weather_results.
        agent_stream = self.weather_agent.run(
            agent_messages,
            stream=True,
            function_invocation_kwargs={"weather_results": weather_results},
        )

        # Create an intercepting stream that detects the city selector marker while passing through updates
        async def intercept_stream() -> AsyncIterator[AgentResponseUpdate]:
            nonlocal show_city_selector
            async for update in agent_stream:
                # Check for the city selector marker in function results
                for content in update.contents:
                    if content.type == "function_result" and content.result == "__SHOW_CITY_SELECTOR__":
                        show_city_selector = True
                        logger.info("City selector flag detected")
                yield update

        # Stream updates as ChatKit events with interception
        async for event in stream_agent_response(
            intercept_stream(),
            thread_id=thread.id,
        ):
            yield event

        # If weather data was collected during the tool call, create a widget
        if weather_results:
            weather_data = weather_results[-1]
            logger.info(f"Creating weather widget for location: {weather_data.location}")
            # Create weather widget
            widget = render_weather_widget(weather_data)
            copy_text = weather_widget_copy_text(weather_data)

            # Stream the widget
            async for widget_event in stream_widget(thread_id=thread.id, widget=widget, copy_text=copy_text):

Anropa agent.run(..., stream=True) först och skicka sedan svarsströmmen och ChatKit-tråd-ID:t till stream_agent_response(...). Skicka inte själva agenten vidare till konverteraren.

ThreadItemConverter bevarar StructuredInputItem status och representerar varje fråga som besvarad, överhoppad eller obesvarad i ett användarmeddelande. Åsidosätt den asynkrona structured_input_to_input() metoden för att anpassa formatering eller redigera svar. Returnera en Message, en lista med meddelanden eller None för att utelämna objektet.

Konverteraren bevarar också ifyllda GeneratedImageItem-värden som modellkontext i senare omgångar. Standardkonverteringen skapar en användare Message med ett kort textförord och den genererade bild-URI:n. Data-URI:er behåller sin inbäddade medietyp, externa URL:er använder image/*, och ofullständiga poster utan bild utelämnas.

Åsidosätt den asynkrona generated_image_to_input() metoden för att anpassa den genererade bildkontexten, till exempel att matcha en privat bild-URL. Returnera en Message, en lista med meddelanden eller None för att utelämna objektet.

Det fullständiga exemplet visar även SQLite-backade trådar, filuppladdningar, lagring av bifogade filer, åtgärder och interaktiva widgetar.

Varning

ChatKit-klientdelen läses in från OpenAI:s CDN och skickar utgående begäranden till OpenAI-domäner. Den kan för närvarande inte vara lokalt installerad och är inte lämplig för luftgapade miljöer.

Nästa steg