Python: Introducing the Anthropic Client (#1819)

* initial version of anthropic connector

* updated implementation and added tests

* fix type and readme

* mypy fix and int tests enabled

* add integration test setup

* updated based on comments

* improved function result handling

* added extra unordered test

* updated from review

* fix tool choice handling

* same fix for chat client

python/packages/anthropic/LICENSE

@@ -0,0 +1,21 @@
+    MIT License
+
+    Copyright (c) Microsoft Corporation.
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all
+    copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+    SOFTWARE

python/packages/anthropic/README.md

@@ -0,0 +1,18 @@
+# Get Started with Microsoft Agent Framework Anthropic
+
+Please install this package via pip:
+
+```bash
+pip install agent-framework-anthropic --pre
+```
+
+## Anthropic Integration
+
+The Anthropic integration enables communication with the Anthropic API, allowing your Agent Framework applications to leverage Anthropic's capabilities.
+
+### Basic Usage Example
+
+See the [Anthropic agent examples](https://github.com/microsoft/agent-framework/tree/main/python/samples/getting_started/agents/anthropic/) which demonstrate:
+
+- Connecting to a Anthropic endpoint with an agent
+- Streaming and non-streaming responses

python/packages/anthropic/agent_framework_anthropic/__init__.py

@@ -0,0 +1,15 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import importlib.metadata
+
+from ._chat_client import AnthropicClient
+
+try:
+    __version__ = importlib.metadata.version(__name__)
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "0.0.0"  # Fallback for development mode
+
+__all__ = [
+    "AnthropicClient",
+    "__version__",
+]

python/packages/anthropic/agent_framework_anthropic/_chat_client.py

@@ -0,0 +1,658 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from collections.abc import AsyncIterable, MutableMapping, MutableSequence, Sequence
+from typing import Any, ClassVar, Final, TypeVar
+
+from agent_framework import (
+    AGENT_FRAMEWORK_USER_AGENT,
+    AIFunction,
+    Annotations,
+    BaseChatClient,
+    ChatMessage,
+    ChatOptions,
+    ChatResponse,
+    ChatResponseUpdate,
+    CitationAnnotation,
+    Contents,
+    FinishReason,
+    FunctionCallContent,
+    FunctionResultContent,
+    HostedCodeInterpreterTool,
+    HostedMCPTool,
+    HostedWebSearchTool,
+    Role,
+    TextContent,
+    TextReasoningContent,
+    TextSpanRegion,
+    ToolProtocol,
+    UsageContent,
+    UsageDetails,
+    get_logger,
+    prepare_function_call_results,
+    use_chat_middleware,
+    use_function_invocation,
+)
+from agent_framework._pydantic import AFBaseSettings
+from agent_framework.exceptions import ServiceInitializationError
+from agent_framework.observability import use_observability
+from anthropic import AsyncAnthropic
+from anthropic.types.beta import (
+    BetaContentBlock,
+    BetaMessage,
+    BetaMessageDeltaUsage,
+    BetaRawContentBlockDelta,
+    BetaRawMessageStreamEvent,
+    BetaTextBlock,
+    BetaUsage,
+)
+from pydantic import SecretStr, ValidationError
+
+logger = get_logger("agent_framework.anthropic")
+
+ANTHROPIC_DEFAULT_MAX_TOKENS: Final[int] = 1024
+BETA_FLAGS: Final[list[str]] = ["mcp-client-2025-04-04", "code-execution-2025-08-25"]
+
+ROLE_MAP: dict[Role, str] = {
+    Role.USER: "user",
+    Role.ASSISTANT: "assistant",
+    Role.SYSTEM: "user",
+    Role.TOOL: "user",
+}
+
+FINISH_REASON_MAP: dict[str, FinishReason] = {
+    "stop_sequence": FinishReason.STOP,
+    "max_tokens": FinishReason.LENGTH,
+    "tool_use": FinishReason.TOOL_CALLS,
+    "end_turn": FinishReason.STOP,
+    "refusal": FinishReason.CONTENT_FILTER,
+    "pause_turn": FinishReason.STOP,
+}
+
+
+class AnthropicSettings(AFBaseSettings):
+    """Anthropic Project settings.
+
+    The settings are first loaded from environment variables with the prefix 'ANTHROPIC_'.
+    If the environment variables are not found, the settings can be loaded from a .env file
+    with the encoding 'utf-8'. If the settings are not found in the .env file, the settings
+    are ignored; however, validation will fail alerting that the settings are missing.
+
+    Keyword Args:
+        api_key: The Anthropic API key.
+        chat_model_id: The Anthropic chat model ID.
+        env_file_path: If provided, the .env settings are read from this file path location.
+        env_file_encoding: The encoding of the .env file, defaults to 'utf-8'.
+
+    Examples:
+        .. code-block:: python
+
+            from agent_framework.anthropic import AnthropicSettings
+
+            # Using environment variables
+            # Set ANTHROPIC_API_KEY=your_anthropic_api_key
+            # ANTHROPIC_CHAT_MODEL_ID=claude-sonnet-4-5-20250929
+
+            # Or passing parameters directly
+            settings = AnthropicSettings(chat_model_id="claude-sonnet-4-5-20250929")
+
+            # Or loading from a .env file
+            settings = AnthropicSettings(env_file_path="path/to/.env")
+    """
+
+    env_prefix: ClassVar[str] = "ANTHROPIC_"
+
+    api_key: SecretStr | None = None
+    chat_model_id: str | None = None
+
+
+TAnthropicClient = TypeVar("TAnthropicClient", bound="AnthropicClient")
+
+
+@use_function_invocation
+@use_observability
+@use_chat_middleware
+class AnthropicClient(BaseChatClient):
+    """Anthropic Chat client."""
+
+    OTEL_PROVIDER_NAME: ClassVar[str] = "anthropic"  # type: ignore[reportIncompatibleVariableOverride, misc]
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        model_id: str | None = None,
+        anthropic_client: AsyncAnthropic | None = None,
+        env_file_path: str | None = None,
+        env_file_encoding: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """Initialize an Anthropic Agent client.
+
+        Keyword Args:
+            api_key: The Anthropic API key to use for authentication.
+            model_id: The ID of the model to use.
+            anthropic_client: An existing Anthropic client to use. If not provided, one will be created.
+                This can be used to further configure the client before passing it in.
+                For instance if you need to set a different base_url for testing or private deployments.
+            env_file_path: Path to environment file for loading settings.
+            env_file_encoding: Encoding of the environment file.
+            kwargs: Additional keyword arguments passed to the parent class.
+
+        Examples:
+            .. code-block:: python
+
+                from agent_framework.anthropic import AnthropicClient
+                from azure.identity.aio import DefaultAzureCredential
+
+                # Using environment variables
+                # Set ANTHROPIC_API_KEY=your_anthropic_api_key
+                # ANTHROPIC_CHAT_MODEL_ID=claude-sonnet-4-5-20250929
+
+                # Or passing parameters directly
+                client = AnthropicClient(
+                    model_id="claude-sonnet-4-5-20250929",
+                    api_key="your_anthropic_api_key",
+                )
+
+                # Or loading from a .env file
+                client = AnthropicClient(env_file_path="path/to/.env")
+
+                # Or passing in an existing client
+                from anthropic import AsyncAnthropic
+
+                anthropic_client = AsyncAnthropic(
+                    api_key="your_anthropic_api_key", base_url="https://custom-anthropic-endpoint.com"
+                )
+                client = AnthropicClient(
+                    model_id="claude-sonnet-4-5-20250929",
+                    anthropic_client=anthropic_client,
+                )
+
+        """
+        try:
+            anthropic_settings = AnthropicSettings(
+                api_key=api_key,  # type: ignore[arg-type]
+                chat_model_id=model_id,
+                env_file_path=env_file_path,
+                env_file_encoding=env_file_encoding,
+            )
+        except ValidationError as ex:
+            raise ServiceInitializationError("Failed to create Anthropic settings.", ex) from ex
+
+        if anthropic_client is None:
+            if not anthropic_settings.api_key:
+                raise ServiceInitializationError(
+                    "Anthropic API key is required. Set via 'api_key' parameter "
+                    "or 'ANTHROPIC_API_KEY' environment variable."
+                )
+
+            anthropic_client = AsyncAnthropic(
+                api_key=anthropic_settings.api_key.get_secret_value(),
+                default_headers={"User-Agent": AGENT_FRAMEWORK_USER_AGENT},
+            )
+
+        # Initialize parent
+        super().__init__(**kwargs)
+
+        # Initialize instance variables
+        self.anthropic_client = anthropic_client
+        self.model_id = anthropic_settings.chat_model_id
+        # streaming requires tracking the last function call ID and name
+        self._last_call_id_name: tuple[str, str] | None = None
+
+    # region Get response methods
+
+    async def _inner_get_response(
+        self,
+        *,
+        messages: MutableSequence[ChatMessage],
+        chat_options: ChatOptions,
+        **kwargs: Any,
+    ) -> ChatResponse:
+        # Extract necessary state from messages and options
+        run_options = self._create_run_options(messages, chat_options, **kwargs)
+        message = await self.anthropic_client.beta.messages.create(**run_options, stream=False)
+        return self._process_message(message)
+
+    async def _inner_get_streaming_response(
+        self,
+        *,
+        messages: MutableSequence[ChatMessage],
+        chat_options: ChatOptions,
+        **kwargs: Any,
+    ) -> AsyncIterable[ChatResponseUpdate]:
+        # Extract necessary state from messages and options
+        run_options = self._create_run_options(messages, chat_options, **kwargs)
+        async for chunk in await self.anthropic_client.beta.messages.create(**run_options, stream=True):
+            parsed_chunk = self._process_stream_event(chunk)
+            if parsed_chunk:
+                yield parsed_chunk
+
+    # region Create Run Options and Helpers
+
+    def _create_run_options(
+        self,
+        messages: MutableSequence[ChatMessage],
+        chat_options: ChatOptions,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        """Create run options for the Anthropic client based on messages and chat options.
+
+        Args:
+            messages: The list of chat messages.
+            chat_options: The chat options.
+            kwargs: Additional keyword arguments.
+
+        Returns:
+            A dictionary of run options for the Anthropic client.
+        """
+        run_options: dict[str, Any] = {
+            "model": chat_options.model_id or self.model_id,
+            "messages": self._convert_messages_to_anthropic_format(messages),
+            "max_tokens": chat_options.max_tokens or ANTHROPIC_DEFAULT_MAX_TOKENS,
+            "extra_headers": {"User-Agent": AGENT_FRAMEWORK_USER_AGENT},
+            "betas": BETA_FLAGS,
+        }
+
+        # Add any additional options from chat_options or kwargs
+        if chat_options.temperature is not None:
+            run_options["temperature"] = chat_options.temperature
+        if chat_options.top_p is not None:
+            run_options["top_p"] = chat_options.top_p
+        if chat_options.stop is not None:
+            run_options["stop_sequences"] = chat_options.stop
+        if messages and isinstance(messages[0], ChatMessage) and messages[0].role == Role.SYSTEM:
+            # first system message is passed as instructions
+            run_options["system"] = messages[0].text
+        if chat_options.tool_choice is not None:
+            match (
+                chat_options.tool_choice if isinstance(chat_options.tool_choice, str) else chat_options.tool_choice.mode
+            ):
+                case "auto":
+                    run_options["tool_choice"] = {"type": "auto"}
+                    if chat_options.allow_multiple_tool_calls is not None:
+                        run_options["tool_choice"][  # type:ignore[reportArgumentType]
+                            "disable_parallel_tool_use"
+                        ] = not chat_options.allow_multiple_tool_calls
+                case "required":
+                    if chat_options.tool_choice.required_function_name:
+                        run_options["tool_choice"] = {
+                            "type": "tool",
+                            "name": chat_options.tool_choice.required_function_name,
+                        }
+                        if chat_options.allow_multiple_tool_calls is not None:
+                            run_options["tool_choice"][  # type:ignore[reportArgumentType]
+                                "disable_parallel_tool_use"
+                            ] = not chat_options.allow_multiple_tool_calls
+                    else:
+                        run_options["tool_choice"] = {"type": "any"}
+                        if chat_options.allow_multiple_tool_calls is not None:
+                            run_options["tool_choice"][  # type:ignore[reportArgumentType]
+                                "disable_parallel_tool_use"
+                            ] = not chat_options.allow_multiple_tool_calls
+                case "none":
+                    run_options["tool_choice"] = {"type": "none"}
+                case _:
+                    logger.debug(f"Ignoring unsupported tool choice mode: {chat_options.tool_choice.mode} for now")
+        if tools_and_mcp := self._convert_tools_to_anthropic_format(chat_options.tools):
+            run_options.update(tools_and_mcp)
+        if chat_options.additional_properties:
+            run_options.update(chat_options.additional_properties)
+        run_options.update(kwargs)
+        return run_options
+
+    def _convert_messages_to_anthropic_format(self, messages: MutableSequence[ChatMessage]) -> list[dict[str, Any]]:
+        """Convert a list of ChatMessages to the format expected by the Anthropic client.
+
+        This skips the first message if it is a system message,
+        as Anthropic expects system instructions as a separate parameter.
+        """
+        # first system message is passed as instructions
+        if messages and isinstance(messages[0], ChatMessage) and messages[0].role == Role.SYSTEM:
+            return [self._convert_message_to_anthropic_format(msg) for msg in messages[1:]]
+        return [self._convert_message_to_anthropic_format(msg) for msg in messages]
+
+    def _convert_message_to_anthropic_format(self, message: ChatMessage) -> dict[str, Any]:
+        """Convert a ChatMessage to the format expected by the Anthropic client.
+
+        Args:
+            message: The ChatMessage to convert.
+
+        Returns:
+            A dictionary representing the message in Anthropic format.
+        """
+        a_content: list[dict[str, Any]] = []
+        for content in message.contents:
+            match content.type:
+                case "text":
+                    a_content.append({"type": "text", "text": content.text})
+                case "data":
+                    if content.has_top_level_media_type("image"):
+                        a_content.append({
+                            "type": "image",
+                            "source": {"data": content.uri, "media_type": content.media_type},
+                        })
+                case "uri":
+                    if content.has_top_level_media_type("image"):
+                        a_content.append({"type": "image", "source": {"type": "url", "url": content.uri}})
+                case "function_call":
+                    a_content.append({
+                        "type": "tool_use",
+                        "id": content.call_id,
+                        "name": content.name,
+                        "input": content.parse_arguments(),
+                    })
+                case "function_result":
+                    a_content.append({
+                        "type": "tool_result",
+                        "tool_use_id": content.call_id,
+                        "content": prepare_function_call_results(content.result),
+                        "is_error": content.exception is not None,
+                    })
+                case "text_reasoning":
+                    a_content.append({"type": "thinking", "thinking": content.text})
+                case _:
+                    logger.debug(f"Ignoring unsupported content type: {content.type} for now")
+
+        return {
+            "role": ROLE_MAP.get(message.role, "user"),
+            "content": a_content,
+        }
+
+    def _convert_tools_to_anthropic_format(
+        self, tools: list[ToolProtocol | MutableMapping[str, Any]] | None
+    ) -> dict[str, Any] | None:
+        if not tools:
+            return None
+        tool_list: list[MutableMapping[str, Any]] = []
+        mcp_server_list: list[MutableMapping[str, Any]] = []
+        for tool in tools:
+            match tool:
+                case MutableMapping():
+                    tool_list.append(tool)
+                case AIFunction():
+                    tool_list.append({
+                        "type": "custom",
+                        "name": tool.name,
+                        "description": tool.description,
+                        "input_schema": tool.parameters(),
+                    })
+                case HostedWebSearchTool():
+                    search_tool: dict[str, Any] = {
+                        "type": "web_search_20250305",
+                        "name": "web_search",
+                    }
+                    if tool.additional_properties:
+                        search_tool.update(tool.additional_properties)
+                    tool_list.append(search_tool)
+                case HostedCodeInterpreterTool():
+                    code_tool: dict[str, Any] = {
+                        "type": "code_execution_20250825",
+                        "name": "code_interpreter",
+                    }
+                    tool_list.append(code_tool)
+                case HostedMCPTool():
+                    server_def: dict[str, Any] = {
+                        "type": "url",
+                        "name": tool.name,
+                        "url": str(tool.url),
+                    }
+                    if tool.allowed_tools:
+                        server_def["tool_configuration"] = {"allowed_tools": list(tool.allowed_tools)}
+                    if tool.headers and (auth := tool.headers.get("authorization")):
+                        server_def["authorization_token"] = auth
+                    mcp_server_list.append(server_def)
+                case _:
+                    logger.debug(f"Ignoring unsupported tool type: {type(tool)} for now")
+
+        all_tools: dict[str, list[MutableMapping[str, Any]]] = {}
+        if tool_list:
+            all_tools["tools"] = tool_list
+        if mcp_server_list:
+            all_tools["mcp_servers"] = mcp_server_list
+        return all_tools
+
+    # region Response Processing Methods
+
+    def _process_message(self, message: BetaMessage) -> ChatResponse:
+        """Process the response from the Anthropic client.
+
+        Args:
+            message: The message returned by the Anthropic client.
+
+        Returns:
+            A ChatResponse object containing the processed response.
+        """
+        return ChatResponse(
+            response_id=message.id,
+            messages=[
+                ChatMessage(
+                    role=Role.ASSISTANT,
+                    contents=self._parse_message_contents(message.content),
+                    raw_representation=message,
+                )
+            ],
+            usage_details=self._parse_message_usage(message.usage),
+            model_id=message.model,
+            finish_reason=FINISH_REASON_MAP.get(message.stop_reason) if message.stop_reason else None,
+            raw_response=message,
+        )
+
+    def _process_stream_event(self, event: BetaRawMessageStreamEvent) -> ChatResponseUpdate | None:
+        """Process a streaming event from the Anthropic client.
+
+        Args:
+            event: The streaming event returned by the Anthropic client.
+
+        Returns:
+            A ChatResponseUpdate object containing the processed update.
+        """
+        match event.type:
+            case "message_start":
+                usage_details: list[UsageContent] = []
+                if event.message.usage and (details := self._parse_message_usage(event.message.usage)):
+                    usage_details.append(UsageContent(details=details))
+
+                return ChatResponseUpdate(
+                    response_id=event.message.id,
+                    contents=[*self._parse_message_contents(event.message.content), *usage_details],
+                    model_id=event.message.model,
+                    finish_reason=FINISH_REASON_MAP.get(event.message.stop_reason)
+                    if event.message.stop_reason
+                    else None,
+                    raw_response=event,
+                )
+            case "message_delta":
+                usage = self._parse_message_usage(event.usage)
+                return ChatResponseUpdate(
+                    contents=[UsageContent(details=usage, raw_representation=event.usage)] if usage else [],
+                    raw_response=event,
+                )
+            case "message_stop":
+                logger.debug("Received message_stop event; no content to process.")
+            case "content_block_start":
+                contents = self._parse_message_contents([event.content_block])
+                return ChatResponseUpdate(
+                    contents=contents,
+                    raw_response=event,
+                )
+            case "content_block_delta":
+                contents = self._parse_message_contents([event.delta])
+                return ChatResponseUpdate(
+                    contents=contents,
+                    raw_response=event,
+                )
+            case "content_block_stop":
+                logger.debug("Received content_block_stop event; no content to process.")
+            case _:
+                logger.debug(f"Ignoring unsupported event type: {event.type}")
+        return None
+
+    def _parse_message_usage(self, usage: BetaUsage | BetaMessageDeltaUsage | None) -> UsageDetails | None:
+        """Parse usage details from the Anthropic message usage."""
+        if not usage:
+            return None
+        usage_details = UsageDetails(output_token_count=usage.output_tokens)
+        if usage.input_tokens is not None:
+            usage_details.input_token_count = usage.input_tokens
+        if usage.cache_creation_input_tokens is not None:
+            usage_details.additional_counts["anthropic.cache_creation_input_tokens"] = usage.cache_creation_input_tokens
+        if usage.cache_read_input_tokens is not None:
+            usage_details.additional_counts["anthropic.cache_read_input_tokens"] = usage.cache_read_input_tokens
+        return usage_details
+
+    def _parse_message_contents(
+        self, content: Sequence[BetaContentBlock | BetaRawContentBlockDelta | BetaTextBlock]
+    ) -> list[Contents]:
+        """Parse contents from the Anthropic message."""
+        contents: list[Contents] = []
+        for content_block in content:
+            match content_block.type:
+                case "text" | "text_delta":
+                    contents.append(
+                        TextContent(
+                            text=content_block.text,
+                            raw_representation=content_block,
+                            annotations=self._parse_citations(content_block),
+                        )
+                    )
+                case "tool_use":
+                    self._last_call_id_name = (content_block.id, content_block.name)
+                    contents.append(
+                        FunctionCallContent(
+                            call_id=content_block.id,
+                            name=content_block.name,
+                            arguments=content_block.input,
+                            raw_representation=content_block,
+                        )
+                    )
+                case "mcp_tool_use" | "server_tool_use":
+                    self._last_call_id_name = (content_block.id, content_block.name)
+                    contents.append(
+                        FunctionCallContent(
+                            call_id=content_block.id,
+                            name=content_block.name,
+                            arguments=content_block.input,
+                            raw_representation=content_block,
+                        )
+                    )
+                case "mcp_tool_result":
+                    call_id, name = self._last_call_id_name or (None, None)
+                    contents.append(
+                        FunctionResultContent(
+                            call_id=content_block.tool_use_id,
+                            name=name if name and call_id == content_block.tool_use_id else "mcp_tool",
+                            result=self._parse_message_contents(content_block.content)
+                            if isinstance(content_block.content, list)
+                            else content_block.content,
+                            raw_representation=content_block,
+                        )
+                    )
+                case "web_search_tool_result" | "web_fetch_tool_result":
+                    call_id, name = self._last_call_id_name or (None, None)
+                    contents.append(
+                        FunctionResultContent(
+                            call_id=content_block.tool_use_id,
+                            name=name if name and call_id == content_block.tool_use_id else "web_tool",
+                            result=content_block.content,
+                            raw_representation=content_block,
+                        )
+                    )
+                case (
+                    "code_execution_tool_result"
+                    | "bash_code_execution_tool_result"
+                    | "text_editor_code_execution_tool_result"
+                ):
+                    call_id, name = self._last_call_id_name or (None, None)
+                    contents.append(
+                        FunctionResultContent(
+                            call_id=content_block.tool_use_id,
+                            name=name if name and call_id == content_block.tool_use_id else "code_execution_tool",
+                            result=content_block.content,
+                            raw_representation=content_block,
+                        )
+                    )
+                case "input_json_delta":
+                    call_id, name = self._last_call_id_name if self._last_call_id_name else ("", "")
+                    contents.append(
+                        FunctionCallContent(
+                            call_id=call_id,
+                            name=name,
+                            arguments=content_block.partial_json,
+                            raw_representation=content_block,
+                        )
+                    )
+                case "thinking" | "thinking_delta":
+                    contents.append(TextReasoningContent(text=content_block.thinking, raw_representation=content_block))
+                case _:
+                    logger.debug(f"Ignoring unsupported content type: {content_block.type} for now")
+        return contents
+
+    def _parse_citations(
+        self, content_block: BetaContentBlock | BetaRawContentBlockDelta | BetaTextBlock
+    ) -> list[Annotations] | None:
+        content_citations = getattr(content_block, "citations", None)
+        if not content_citations:
+            return None
+        annotations: list[Annotations] = []
+        for citation in content_citations:
+            cit = CitationAnnotation(raw_representation=citation)
+            match citation.type:
+                case "char_location":
+                    cit.title = citation.title
+                    cit.snippet = citation.cited_text
+                    if citation.file_id:
+                        cit.file_id = citation.file_id
+                    if not cit.annotated_regions:
+                        cit.annotated_regions = []
+                    cit.annotated_regions.append(
+                        TextSpanRegion(start_index=citation.start_char_index, end_index=citation.end_char_index)
+                    )
+                case "page_location":
+                    cit.title = citation.document_title
+                    cit.snippet = citation.cited_text
+                    if citation.file_id:
+                        cit.file_id = citation.file_id
+                    if not cit.annotated_regions:
+                        cit.annotated_regions = []
+                    cit.annotated_regions.append(
+                        TextSpanRegion(
+                            start_index=citation.start_page_number,
+                            end_index=citation.end_page_number,
+                        )
+                    )
+                case "content_block_location":
+                    cit.title = citation.document_title
+                    cit.snippet = citation.cited_text
+                    if citation.file_id:
+                        cit.file_id = citation.file_id
+                    if not cit.annotated_regions:
+                        cit.annotated_regions = []
+                    cit.annotated_regions.append(
+                        TextSpanRegion(start_index=citation.start_block_index, end_index=citation.end_block_index)
+                    )
+                case "web_search_result_location":
+                    cit.title = citation.title
+                    cit.snippet = citation.cited_text
+                    cit.url = citation.url
+                case "search_result_location":
+                    cit.title = citation.title
+                    cit.snippet = citation.cited_text
+                    cit.url = citation.source
+                    if not cit.annotated_regions:
+                        cit.annotated_regions = []
+                    cit.annotated_regions.append(
+                        TextSpanRegion(start_index=citation.start_block_index, end_index=citation.end_block_index)
+                    )
+                case _:
+                    logger.debug(f"Unknown citation type encountered: {citation.type}")
+            annotations.append(cit)
+        return annotations or None
+
+    def service_url(self) -> str:
+        """Get the service URL for the chat client.
+
+        Returns:
+            The service URL for the chat client, or None if not set.
+        """
+        return str(self.anthropic_client.base_url)

python/packages/anthropic/pyproject.toml

@@ -0,0 +1,88 @@
+[project]
+name = "agent-framework-anthropic"
+description = "Anthropic integration for Microsoft Agent Framework."
+authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
+readme = "README.md"
+requires-python = ">=3.10"
+version = "1.0.0b251028"
+license-files = ["LICENSE"]
+urls.homepage = "https://aka.ms/agent-framework"
+urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
+urls.release_notes = "https://github.com/microsoft/agent-framework/releases?q=tag%3Apython-1&expanded=true"
+urls.issues = "https://github.com/microsoft/agent-framework/issues"
+classifiers = [
+  "License :: OSI Approved :: MIT License",
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+dependencies = [
+    "agent-framework-core",
+    "anthropic>=0.70.0,<1",
+]
+
+[tool.uv]
+prerelease = "if-necessary-or-explicit"
+environments = [
+    "sys_platform == 'darwin'",
+    "sys_platform == 'linux'",
+    "sys_platform == 'win32'"
+]
+
+[tool.uv-dynamic-versioning]
+fallback-version = "0.0.0"
+[tool.pytest.ini_options]
+testpaths = 'tests'
+addopts = "-ra -q -r fEX"
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+filterwarnings = [
+    "ignore:Support for class-based `config` is deprecated:DeprecationWarning:pydantic.*"
+]
+timeout = 120
+
+[tool.ruff]
+extend = "../../pyproject.toml"
+
+[tool.coverage.run]
+omit = [
+    "**/__init__.py"
+]
+
+[tool.pyright]
+extends = "../../pyproject.toml"
+exclude = ['tests']
+
+[tool.mypy]
+plugins = ['pydantic.mypy']
+strict = true
+python_version = "3.10"
+ignore_missing_imports = true
+disallow_untyped_defs = true
+no_implicit_optional = true
+check_untyped_defs = true
+warn_return_any = true
+show_error_codes = true
+warn_unused_ignores = false
+disallow_incomplete_defs = true
+disallow_untyped_decorators = true
+
+[tool.bandit]
+targets = ["agent_framework_anthropic"]
+exclude_dirs = ["tests"]
+
+[tool.poe]
+executor.type = "uv"
+include = "../../shared_tasks.toml"
+[tool.poe.tasks]
+mypy = "mypy --config-file $POE_ROOT/pyproject.toml agent_framework_anthropic"
+test = "pytest --cov=agent_framework_anthropic --cov-report=term-missing:skip-covered tests"
+
+[build-system]
+requires = ["flit-core >= 3.11,<4.0"]
+build-backend = "flit_core.buildapi"

python/packages/anthropic/tests/conftest.py

@@ -0,0 +1,56 @@
+# Copyright (c) Microsoft. All rights reserved.
+from typing import Any
+from unittest.mock import AsyncMock, MagicMock
+
+from pytest import fixture
+
+
+@fixture
+def exclude_list(request: Any) -> list[str]:
+    """Fixture that returns a list of environment variables to exclude."""
+    return request.param if hasattr(request, "param") else []
+
+
+@fixture
+def override_env_param_dict(request: Any) -> dict[str, str]:
+    """Fixture that returns a dict of environment variables to override."""
+    return request.param if hasattr(request, "param") else {}
+
+
+@fixture
+def anthropic_unit_test_env(monkeypatch, exclude_list, override_env_param_dict):  # type: ignore
+    """Fixture to set environment variables for AnthropicSettings."""
+    if exclude_list is None:
+        exclude_list = []
+
+    if override_env_param_dict is None:
+        override_env_param_dict = {}
+
+    env_vars = {
+        "ANTHROPIC_API_KEY": "test-api-key-12345",
+        "ANTHROPIC_CHAT_MODEL_ID": "claude-3-5-sonnet-20241022",
+    }
+
+    env_vars.update(override_env_param_dict)  # type: ignore
+
+    for key, value in env_vars.items():
+        if key in exclude_list:
+            monkeypatch.delenv(key, raising=False)  # type: ignore
+            continue
+        monkeypatch.setenv(key, value)  # type: ignore
+
+    return env_vars
+
+
+@fixture
+def mock_anthropic_client() -> MagicMock:
+    """Fixture that provides a mock AsyncAnthropic client."""
+    mock_client = MagicMock()
+    mock_client.base_url = "https://api.anthropic.com"
+
+    # Mock beta.messages property
+    mock_client.beta = MagicMock()
+    mock_client.beta.messages = MagicMock()
+    mock_client.beta.messages.create = AsyncMock()
+
+    return mock_client

python/packages/anthropic/tests/test_anthropic_client.py

@@ -0,0 +1,777 @@
+# Copyright (c) Microsoft. All rights reserved.
+import os
+from typing import Annotated
+from unittest.mock import MagicMock, patch
+
+import pytest
+from agent_framework import (
+    ChatClientProtocol,
+    ChatMessage,
+    ChatOptions,
+    ChatResponseUpdate,
+    FinishReason,
+    FunctionCallContent,
+    FunctionResultContent,
+    HostedCodeInterpreterTool,
+    HostedMCPTool,
+    HostedWebSearchTool,
+    Role,
+    TextContent,
+    TextReasoningContent,
+    ai_function,
+)
+from agent_framework.exceptions import ServiceInitializationError
+from anthropic.types.beta import (
+    BetaMessage,
+    BetaTextBlock,
+    BetaToolUseBlock,
+    BetaUsage,
+)
+from pydantic import Field, ValidationError
+
+from agent_framework_anthropic import AnthropicClient
+from agent_framework_anthropic._chat_client import AnthropicSettings
+
+skip_if_anthropic_integration_tests_disabled = pytest.mark.skipif(
+    os.getenv("RUN_INTEGRATION_TESTS", "false").lower() != "true"
+    or os.getenv("ANTHROPIC_API_KEY", "") in ("", "test-api-key-12345"),
+    reason="No real ANTHROPIC_API_KEY provided; skipping integration tests."
+    if os.getenv("RUN_INTEGRATION_TESTS", "false").lower() == "true"
+    else "Integration tests are disabled.",
+)
+
+
+def create_test_anthropic_client(
+    mock_anthropic_client: MagicMock,
+    model_id: str | None = None,
+    anthropic_settings: AnthropicSettings | None = None,
+) -> AnthropicClient:
+    """Helper function to create AnthropicClient instances for testing, bypassing normal validation."""
+    if anthropic_settings is None:
+        anthropic_settings = AnthropicSettings(api_key="test-api-key-12345", chat_model_id="claude-3-5-sonnet-20241022")
+
+    # Create client instance directly
+    client = object.__new__(AnthropicClient)
+
+    # Set attributes directly
+    client.anthropic_client = mock_anthropic_client
+    client.model_id = model_id or anthropic_settings.chat_model_id
+    client._last_call_id_name = None
+    client.additional_properties = {}
+    client.middleware = None
+
+    return client
+
+
+# Settings Tests
+
+
+def test_anthropic_settings_init(anthropic_unit_test_env: dict[str, str]) -> None:
+    """Test AnthropicSettings initialization."""
+    settings = AnthropicSettings()
+
+    assert settings.api_key is not None
+    assert settings.api_key.get_secret_value() == anthropic_unit_test_env["ANTHROPIC_API_KEY"]
+    assert settings.chat_model_id == anthropic_unit_test_env["ANTHROPIC_CHAT_MODEL_ID"]
+
+
+def test_anthropic_settings_init_with_explicit_values() -> None:
+    """Test AnthropicSettings initialization with explicit values."""
+    settings = AnthropicSettings(
+        api_key="custom-api-key",
+        chat_model_id="claude-3-opus-20240229",
+    )
+
+    assert settings.api_key is not None
+    assert settings.api_key.get_secret_value() == "custom-api-key"
+    assert settings.chat_model_id == "claude-3-opus-20240229"
+
+
+@pytest.mark.parametrize("exclude_list", [["ANTHROPIC_API_KEY"]], indirect=True)
+def test_anthropic_settings_missing_api_key(anthropic_unit_test_env: dict[str, str]) -> None:
+    """Test AnthropicSettings when API key is missing."""
+    settings = AnthropicSettings()
+    assert settings.api_key is None
+    assert settings.chat_model_id == anthropic_unit_test_env["ANTHROPIC_CHAT_MODEL_ID"]
+
+
+# Client Initialization Tests
+
+
+def test_anthropic_client_init_with_client(mock_anthropic_client: MagicMock) -> None:
+    """Test AnthropicClient initialization with existing anthropic_client."""
+    chat_client = create_test_anthropic_client(mock_anthropic_client, model_id="claude-3-5-sonnet-20241022")
+
+    assert chat_client.anthropic_client is mock_anthropic_client
+    assert chat_client.model_id == "claude-3-5-sonnet-20241022"
+    assert isinstance(chat_client, ChatClientProtocol)
+
+
+def test_anthropic_client_init_auto_create_client(anthropic_unit_test_env: dict[str, str]) -> None:
+    """Test AnthropicClient initialization with auto-created anthropic_client."""
+    client = AnthropicClient(
+        api_key=anthropic_unit_test_env["ANTHROPIC_API_KEY"],
+        model_id=anthropic_unit_test_env["ANTHROPIC_CHAT_MODEL_ID"],
+    )
+
+    assert client.anthropic_client is not None
+    assert client.model_id == anthropic_unit_test_env["ANTHROPIC_CHAT_MODEL_ID"]
+
+
+def test_anthropic_client_init_missing_api_key() -> None:
+    """Test AnthropicClient initialization when API key is missing."""
+    with patch("agent_framework_anthropic._chat_client.AnthropicSettings") as mock_settings:
+        mock_settings.return_value.api_key = None
+        mock_settings.return_value.chat_model_id = "claude-3-5-sonnet-20241022"
+
+        with pytest.raises(ServiceInitializationError, match="Anthropic API key is required"):
+            AnthropicClient()
+
+
+def test_anthropic_client_init_validation_error() -> None:
+    """Test that ValidationError in AnthropicSettings is properly handled."""
+    with patch("agent_framework_anthropic._chat_client.AnthropicSettings") as mock_settings:
+        mock_settings.side_effect = ValidationError.from_exception_data("test", [])
+
+        with pytest.raises(ServiceInitializationError, match="Failed to create Anthropic settings"):
+            AnthropicClient()
+
+
+def test_anthropic_client_service_url(mock_anthropic_client: MagicMock) -> None:
+    """Test service_url method."""
+    chat_client = create_test_anthropic_client(mock_anthropic_client)
+    assert chat_client.service_url() == "https://api.anthropic.com"
+
+
+# Message Conversion Tests
+
+
+def test_convert_message_to_anthropic_format_text(mock_anthropic_client: MagicMock) -> None:
+    """Test converting text message to Anthropic format."""
+    chat_client = create_test_anthropic_client(mock_anthropic_client)
+    message = ChatMessage(role=Role.USER, text="Hello, world!")
+
+    result = chat_client._convert_message_to_anthropic_format(message)
+
+    assert result["role"] == "user"
+    assert len(result["content"]) == 1
+    assert result["content"][0]["type"] == "text"
+    assert result["content"][0]["text"] == "Hello, world!"
+
+
+def test_convert_message_to_anthropic_format_function_call(mock_anthropic_client: MagicMock) -> None:
+    """Test converting function call message to Anthropic format."""
+    chat_client = create_test_anthropic_client(mock_anthropic_client)
+    message = ChatMessage(
+        role=Role.ASSISTANT,
+        contents=[
+            FunctionCallContent(
+                call_id="call_123",
+                name="get_weather",
+                arguments={"location": "San Francisco"},
+            )
+        ],
+    )
+
+    result = chat_client._convert_message_to_anthropic_format(message)
+
+    assert result["role"] == "assistant"
+    assert len(result["content"]) == 1
+    assert result["content"][0]["type"] == "tool_use"
+    assert result["content"][0]["id"] == "call_123"
+    assert result["content"][0]["name"] == "get_weather"
+    assert result["content"][0]["input"] == {"location": "San Francisco"}
+
+
+def test_convert_message_to_anthropic_format_function_result(mock_anthropic_client: MagicMock) -> None:
+    """Test converting function result message to Anthropic format."""
+    chat_client = create_test_anthropic_client(mock_anthropic_client)
+    message = ChatMessage(
+        role=Role.TOOL,
+        contents=[
+            FunctionResultContent(
+                call_id="call_123",
+                name="get_weather",
+                result="Sunny, 72°F",
+            )
+        ],
+    )
+
+    result = chat_client._convert_message_to_anthropic_format(message)
+
+    assert result["role"] == "user"
+    assert len(result["content"]) == 1
+    assert result["content"][0]["type"] == "tool_result"
+    assert result["content"][0]["tool_use_id"] == "call_123"
+    # The degree symbol might be escaped differently depending on JSON encoder
+    assert "Sunny" in result["content"][0]["content"]
+    assert "72" in result["content"][0]["content"]
+    assert result["content"][0]["is_error"] is False
+
+
+def test_convert_message_to_anthropic_format_text_reasoning(mock_anthropic_client: MagicMock) -> None:
+    """Test converting text reasoning message to Anthropic format."""
+    chat_client = create_test_anthropic_client(mock_anthropic_client)
+    message = ChatMessage(
+        role=Role.ASSISTANT,
+        contents=[TextReasoningContent(text="Let me think about this...")],
+    )
+
+    result = chat_client._convert_message_to_anthropic_format(message)
+
+    assert result["role"] == "assistant"
+    assert len(result["content"]) == 1
+    assert result["content"][0]["type"] == "thinking"
+    assert result["content"][0]["thinking"] == "Let me think about this..."
+
+
+def test_convert_messages_to_anthropic_format_with_system(mock_anthropic_client: MagicMock) -> None:
+    """Test converting messages list with system message."""
+    chat_client = create_test_anthropic_client(mock_anthropic_client)
+    messages = [
+        ChatMessage(role=Role.SYSTEM, text="You are a helpful assistant."),
+        ChatMessage(role=Role.USER, text="Hello!"),
+    ]
+
+    result = chat_client._convert_messages_to_anthropic_format(messages)
+
+    # System message should be skipped
+    assert len(result) == 1
+    assert result[0]["role"] == "user"
+    assert result[0]["content"][0]["text"] == "Hello!"
+
+
+def test_convert_messages_to_anthropic_format_without_system(mock_anthropic_client: MagicMock) -> None:
+    """Test converting messages list without system message."""
+    chat_client = create_test_anthropic_client(mock_anthropic_client)
+    messages = [
+        ChatMessage(role=Role.USER, text="Hello!"),
+        ChatMessage(role=Role.ASSISTANT, text="Hi there!"),
+    ]
+
+    result = chat_client._convert_messages_to_anthropic_format(messages)
+
+    assert len(result) == 2
+    assert result[0]["role"] == "user"
+    assert result[1]["role"] == "assistant"
+
+
+# Tool Conversion Tests
+
+
+def test_convert_tools_to_anthropic_format_ai_function(mock_anthropic_client: MagicMock) -> None:
+    """Test converting AIFunction to Anthropic format."""
+    chat_client = create_test_anthropic_client(mock_anthropic_client)
+
+    @ai_function
+    def get_weather(location: Annotated[str, Field(description="Location to get weather for")]) -> str:
+        """Get weather for a location."""
+        return f"Weather for {location}"
+
+    tools = [get_weather]
+
+    result = chat_client._convert_tools_to_anthropic_format(tools)
+
+    assert result is not None
+    assert "tools" in result
+    assert len(result["tools"]) == 1
+    assert result["tools"][0]["type"] == "custom"
+    assert result["tools"][0]["name"] == "get_weather"
+    assert "Get weather for a location" in result["tools"][0]["description"]
+
+
+def test_convert_tools_to_anthropic_format_web_search(mock_anthropic_client: MagicMock) -> None:
+    """Test converting HostedWebSearchTool to Anthropic format."""
+    chat_client = create_test_anthropic_client(mock_anthropic_client)
+    tools = [HostedWebSearchTool()]
+
+    result = chat_client._convert_tools_to_anthropic_format(tools)
+
+    assert result is not None
+    assert "tools" in result
+    assert len(result["tools"]) == 1
+    assert result["tools"][0]["type"] == "web_search_20250305"
+    assert result["tools"][0]["name"] == "web_search"
+
+
+def test_convert_tools_to_anthropic_format_code_interpreter(mock_anthropic_client: MagicMock) -> None:
+    """Test converting HostedCodeInterpreterTool to Anthropic format."""
+    chat_client = create_test_anthropic_client(mock_anthropic_client)
+    tools = [HostedCodeInterpreterTool()]
+
+    result = chat_client._convert_tools_to_anthropic_format(tools)
+
+    assert result is not None
+    assert "tools" in result
+    assert len(result["tools"]) == 1
+    assert result["tools"][0]["type"] == "code_execution_20250825"
+    assert result["tools"][0]["name"] == "code_interpreter"
+
+
+def test_convert_tools_to_anthropic_format_mcp_tool(mock_anthropic_client: MagicMock) -> None:
+    """Test converting HostedMCPTool to Anthropic format."""
+    chat_client = create_test_anthropic_client(mock_anthropic_client)
+    tools = [HostedMCPTool(name="test-mcp", url="https://example.com/mcp")]
+
+    result = chat_client._convert_tools_to_anthropic_format(tools)
+
+    assert result is not None
+    assert "mcp_servers" in result
+    assert len(result["mcp_servers"]) == 1
+    assert result["mcp_servers"][0]["type"] == "url"
+    assert result["mcp_servers"][0]["name"] == "test-mcp"
+    assert result["mcp_servers"][0]["url"] == "https://example.com/mcp"
+
+
+def test_convert_tools_to_anthropic_format_mcp_with_auth(mock_anthropic_client: MagicMock) -> None:
+    """Test converting HostedMCPTool with authorization headers."""
+    chat_client = create_test_anthropic_client(mock_anthropic_client)
+    tools = [
+        HostedMCPTool(
+            name="test-mcp",
+            url="https://example.com/mcp",
+            headers={"authorization": "Bearer token123"},
+        )
+    ]
+
+    result = chat_client._convert_tools_to_anthropic_format(tools)
+
+    assert result is not None
+    assert "mcp_servers" in result
+    # The authorization header is converted to authorization_token
+    assert "authorization_token" in result["mcp_servers"][0]
+    assert result["mcp_servers"][0]["authorization_token"] == "Bearer token123"
+
+
+def test_convert_tools_to_anthropic_format_dict_tool(mock_anthropic_client: MagicMock) -> None:
+    """Test converting dict tool to Anthropic format."""
+    chat_client = create_test_anthropic_client(mock_anthropic_client)
+    tools = [{"type": "custom", "name": "custom_tool", "description": "A custom tool"}]
+
+    result = chat_client._convert_tools_to_anthropic_format(tools)
+
+    assert result is not None
+    assert "tools" in result
+    assert len(result["tools"]) == 1
+    assert result["tools"][0]["name"] == "custom_tool"
+
+
+def test_convert_tools_to_anthropic_format_none(mock_anthropic_client: MagicMock) -> None:
+    """Test converting None tools."""
+    chat_client = create_test_anthropic_client(mock_anthropic_client)
+
+    result = chat_client._convert_tools_to_anthropic_format(None)
+
+    assert result is None
+
+
+# Run Options Tests
+
+
+async def test_create_run_options_basic(mock_anthropic_client: MagicMock) -> None:
+    """Test _create_run_options with basic ChatOptions."""
+    chat_client = create_test_anthropic_client(mock_anthropic_client)
+
+    messages = [ChatMessage(role=Role.USER, text="Hello")]
+    chat_options = ChatOptions(max_tokens=100, temperature=0.7)
+
+    run_options = chat_client._create_run_options(messages, chat_options)
+
+    assert run_options["model"] == chat_client.model_id
+    assert run_options["max_tokens"] == 100
+    assert run_options["temperature"] == 0.7
+    assert "messages" in run_options
+
+
+async def test_create_run_options_with_system_message(mock_anthropic_client: MagicMock) -> None:
+    """Test _create_run_options with system message."""
+    chat_client = create_test_anthropic_client(mock_anthropic_client)
+
+    messages = [
+        ChatMessage(role=Role.SYSTEM, text="You are helpful."),
+        ChatMessage(role=Role.USER, text="Hello"),
+    ]
+    chat_options = ChatOptions()
+
+    run_options = chat_client._create_run_options(messages, chat_options)
+
+    assert run_options["system"] == "You are helpful."
+    assert len(run_options["messages"]) == 1  # System message not in messages list
+
+
+async def test_create_run_options_with_tool_choice_auto(mock_anthropic_client: MagicMock) -> None:
+    """Test _create_run_options with auto tool choice."""
+    chat_client = create_test_anthropic_client(mock_anthropic_client)
+
+    messages = [ChatMessage(role=Role.USER, text="Hello")]
+    chat_options = ChatOptions(tool_choice="auto")
+
+    run_options = chat_client._create_run_options(messages, chat_options)
+
+    assert run_options["tool_choice"]["type"] == "auto"
+
+
+async def test_create_run_options_with_tool_choice_required(mock_anthropic_client: MagicMock) -> None:
+    """Test _create_run_options with required tool choice."""
+    chat_client = create_test_anthropic_client(mock_anthropic_client)
+
+    messages = [ChatMessage(role=Role.USER, text="Hello")]
+    # For required with specific function, need to pass as dict
+    chat_options = ChatOptions(tool_choice={"mode": "required", "required_function_name": "get_weather"})
+
+    run_options = chat_client._create_run_options(messages, chat_options)
+
+    assert run_options["tool_choice"]["type"] == "tool"
+    assert run_options["tool_choice"]["name"] == "get_weather"
+
+
+async def test_create_run_options_with_tool_choice_none(mock_anthropic_client: MagicMock) -> None:
+    """Test _create_run_options with none tool choice."""
+    chat_client = create_test_anthropic_client(mock_anthropic_client)
+
+    messages = [ChatMessage(role=Role.USER, text="Hello")]
+    chat_options = ChatOptions(tool_choice="none")
+
+    run_options = chat_client._create_run_options(messages, chat_options)
+
+    assert run_options["tool_choice"]["type"] == "none"
+
+
+async def test_create_run_options_with_tools(mock_anthropic_client: MagicMock) -> None:
+    """Test _create_run_options with tools."""
+    chat_client = create_test_anthropic_client(mock_anthropic_client)
+
+    @ai_function
+    def get_weather(location: str) -> str:
+        """Get weather for a location."""
+        return f"Weather for {location}"
+
+    messages = [ChatMessage(role=Role.USER, text="Hello")]
+    chat_options = ChatOptions(tools=[get_weather])
+
+    run_options = chat_client._create_run_options(messages, chat_options)
+
+    assert "tools" in run_options
+    assert len(run_options["tools"]) == 1
+
+
+async def test_create_run_options_with_stop_sequences(mock_anthropic_client: MagicMock) -> None:
+    """Test _create_run_options with stop sequences."""
+    chat_client = create_test_anthropic_client(mock_anthropic_client)
+
+    messages = [ChatMessage(role=Role.USER, text="Hello")]
+    chat_options = ChatOptions(stop=["STOP", "END"])
+
+    run_options = chat_client._create_run_options(messages, chat_options)
+
+    assert run_options["stop_sequences"] == ["STOP", "END"]
+
+
+async def test_create_run_options_with_top_p(mock_anthropic_client: MagicMock) -> None:
+    """Test _create_run_options with top_p."""
+    chat_client = create_test_anthropic_client(mock_anthropic_client)
+
+    messages = [ChatMessage(role=Role.USER, text="Hello")]
+    chat_options = ChatOptions(top_p=0.9)
+
+    run_options = chat_client._create_run_options(messages, chat_options)
+
+    assert run_options["top_p"] == 0.9
+
+
+# Response Processing Tests
+
+
+def test_process_message_basic(mock_anthropic_client: MagicMock) -> None:
+    """Test _process_message with basic text response."""
+    chat_client = create_test_anthropic_client(mock_anthropic_client)
+
+    mock_message = MagicMock(spec=BetaMessage)
+    mock_message.id = "msg_123"
+    mock_message.model = "claude-3-5-sonnet-20241022"
+    mock_message.content = [BetaTextBlock(type="text", text="Hello there!")]
+    mock_message.usage = BetaUsage(input_tokens=10, output_tokens=5)
+    mock_message.stop_reason = "end_turn"
+
+    response = chat_client._process_message(mock_message)
+
+    assert response.response_id == "msg_123"
+    assert response.model_id == "claude-3-5-sonnet-20241022"
+    assert len(response.messages) == 1
+    assert response.messages[0].role == Role.ASSISTANT
+    assert len(response.messages[0].contents) == 1
+    assert isinstance(response.messages[0].contents[0], TextContent)
+    assert response.messages[0].contents[0].text == "Hello there!"
+    assert response.finish_reason == FinishReason.STOP
+    assert response.usage_details is not None
+    assert response.usage_details.input_token_count == 10
+    assert response.usage_details.output_token_count == 5
+
+
+def test_process_message_with_tool_use(mock_anthropic_client: MagicMock) -> None:
+    """Test _process_message with tool use."""
+    chat_client = create_test_anthropic_client(mock_anthropic_client)
+
+    mock_message = MagicMock(spec=BetaMessage)
+    mock_message.id = "msg_123"
+    mock_message.model = "claude-3-5-sonnet-20241022"
+    mock_message.content = [
+        BetaToolUseBlock(
+            type="tool_use",
+            id="call_123",
+            name="get_weather",
+            input={"location": "San Francisco"},
+        )
+    ]
+    mock_message.usage = BetaUsage(input_tokens=10, output_tokens=5)
+    mock_message.stop_reason = "tool_use"
+
+    response = chat_client._process_message(mock_message)
+
+    assert len(response.messages[0].contents) == 1
+    assert isinstance(response.messages[0].contents[0], FunctionCallContent)
+    assert response.messages[0].contents[0].call_id == "call_123"
+    assert response.messages[0].contents[0].name == "get_weather"
+    assert response.finish_reason == FinishReason.TOOL_CALLS
+
+
+def test_parse_message_usage_basic(mock_anthropic_client: MagicMock) -> None:
+    """Test _parse_message_usage with basic usage."""
+    chat_client = create_test_anthropic_client(mock_anthropic_client)
+
+    usage = BetaUsage(input_tokens=10, output_tokens=5)
+    result = chat_client._parse_message_usage(usage)
+
+    assert result is not None
+    assert result.input_token_count == 10
+    assert result.output_token_count == 5
+
+
+def test_parse_message_usage_none(mock_anthropic_client: MagicMock) -> None:
+    """Test _parse_message_usage with None usage."""
+    chat_client = create_test_anthropic_client(mock_anthropic_client)
+
+    result = chat_client._parse_message_usage(None)
+
+    assert result is None
+
+
+def test_parse_message_contents_text(mock_anthropic_client: MagicMock) -> None:
+    """Test _parse_message_contents with text content."""
+    chat_client = create_test_anthropic_client(mock_anthropic_client)
+
+    content = [BetaTextBlock(type="text", text="Hello!")]
+    result = chat_client._parse_message_contents(content)
+
+    assert len(result) == 1
+    assert isinstance(result[0], TextContent)
+    assert result[0].text == "Hello!"
+
+
+def test_parse_message_contents_tool_use(mock_anthropic_client: MagicMock) -> None:
+    """Test _parse_message_contents with tool use."""
+    chat_client = create_test_anthropic_client(mock_anthropic_client)
+
+    content = [
+        BetaToolUseBlock(
+            type="tool_use",
+            id="call_123",
+            name="get_weather",
+            input={"location": "SF"},
+        )
+    ]
+    result = chat_client._parse_message_contents(content)
+
+    assert len(result) == 1
+    assert isinstance(result[0], FunctionCallContent)
+    assert result[0].call_id == "call_123"
+    assert result[0].name == "get_weather"
+
+
+# Stream Processing Tests
+
+
+def test_process_stream_event_simple(mock_anthropic_client: MagicMock) -> None:
+    """Test _process_stream_event with simple mock event."""
+    chat_client = create_test_anthropic_client(mock_anthropic_client)
+
+    # Test with a basic mock event - the actual implementation will handle real events
+    mock_event = MagicMock()
+    mock_event.type = "message_stop"
+
+    result = chat_client._process_stream_event(mock_event)
+
+    # message_stop events return None
+    assert result is None
+
+
+async def test_inner_get_response(mock_anthropic_client: MagicMock) -> None:
+    """Test _inner_get_response method."""
+    chat_client = create_test_anthropic_client(mock_anthropic_client)
+
+    # Create a mock message response
+    mock_message = MagicMock(spec=BetaMessage)
+    mock_message.id = "msg_test"
+    mock_message.model = "claude-3-5-sonnet-20241022"
+    mock_message.content = [BetaTextBlock(type="text", text="Hello!")]
+    mock_message.usage = BetaUsage(input_tokens=5, output_tokens=3)
+    mock_message.stop_reason = "end_turn"
+
+    mock_anthropic_client.beta.messages.create.return_value = mock_message
+
+    messages = [ChatMessage(role=Role.USER, text="Hi")]
+    chat_options = ChatOptions(max_tokens=10)
+
+    response = await chat_client._inner_get_response(  # type: ignore[attr-defined]
+        messages=messages, chat_options=chat_options
+    )
+
+    assert response is not None
+    assert response.response_id == "msg_test"
+    assert len(response.messages) == 1
+
+
+async def test_inner_get_streaming_response(mock_anthropic_client: MagicMock) -> None:
+    """Test _inner_get_streaming_response method."""
+    chat_client = create_test_anthropic_client(mock_anthropic_client)
+
+    # Create mock streaming response
+    async def mock_stream():
+        mock_event = MagicMock()
+        mock_event.type = "message_stop"
+        yield mock_event
+
+    mock_anthropic_client.beta.messages.create.return_value = mock_stream()
+
+    messages = [ChatMessage(role=Role.USER, text="Hi")]
+    chat_options = ChatOptions(max_tokens=10)
+
+    chunks: list[ChatResponseUpdate] = []
+    async for chunk in chat_client._inner_get_streaming_response(  # type: ignore[attr-defined]
+        messages=messages, chat_options=chat_options
+    ):
+        if chunk:
+            chunks.append(chunk)
+
+    # We should get at least some response (even if empty due to message_stop)
+    assert isinstance(chunks, list)
+
+
+# Integration Tests
+
+
+@ai_function
+def get_weather(
+    location: Annotated[str, Field(description="The location to get the weather for.")],
+) -> str:
+    """Get the weather for a location."""
+    return f"The weather in {location} is sunny and 72°F"
+
+
+@pytest.mark.flaky
+@skip_if_anthropic_integration_tests_disabled
+async def test_anthropic_client_integration_basic_chat() -> None:
+    """Integration test for basic chat completion."""
+    client = AnthropicClient()
+
+    messages = [ChatMessage(role=Role.USER, text="Say 'Hello, World!' and nothing else.")]
+
+    response = await client.get_response(messages=messages, chat_options=ChatOptions(max_tokens=50))
+
+    assert response is not None
+    assert len(response.messages) > 0
+    assert response.messages[0].role == Role.ASSISTANT
+    assert len(response.messages[0].text) > 0
+    assert response.usage_details is not None
+
+
+@pytest.mark.flaky
+@skip_if_anthropic_integration_tests_disabled
+async def test_anthropic_client_integration_streaming_chat() -> None:
+    """Integration test for streaming chat completion."""
+    client = AnthropicClient()
+
+    messages = [ChatMessage(role=Role.USER, text="Count from 1 to 5.")]
+
+    chunks = []
+    async for chunk in client.get_streaming_response(messages=messages, chat_options=ChatOptions(max_tokens=50)):
+        chunks.append(chunk)
+
+    assert len(chunks) > 0
+    assert any(chunk.contents for chunk in chunks)
+
+
+@pytest.mark.flaky
+@skip_if_anthropic_integration_tests_disabled
+async def test_anthropic_client_integration_function_calling() -> None:
+    """Integration test for function calling."""
+    client = AnthropicClient()
+
+    messages = [ChatMessage(role=Role.USER, text="What's the weather in San Francisco?")]
+    tools = [get_weather]
+
+    response = await client.get_response(
+        messages=messages,
+        chat_options=ChatOptions(tools=tools, max_tokens=100),
+    )
+
+    assert response is not None
+    # Should contain function call
+    has_function_call = any(
+        isinstance(content, FunctionCallContent) for msg in response.messages for content in msg.contents
+    )
+    assert has_function_call
+
+
+@pytest.mark.flaky
+@skip_if_anthropic_integration_tests_disabled
+async def test_anthropic_client_integration_with_system_message() -> None:
+    """Integration test with system message."""
+    client = AnthropicClient()
+
+    messages = [
+        ChatMessage(role=Role.SYSTEM, text="You are a pirate. Always respond like a pirate."),
+        ChatMessage(role=Role.USER, text="Hello!"),
+    ]
+
+    response = await client.get_response(messages=messages, chat_options=ChatOptions(max_tokens=50))
+
+    assert response is not None
+    assert len(response.messages) > 0
+
+
+@pytest.mark.flaky
+@skip_if_anthropic_integration_tests_disabled
+async def test_anthropic_client_integration_temperature_control() -> None:
+    """Integration test with temperature control."""
+    client = AnthropicClient()
+
+    messages = [ChatMessage(role=Role.USER, text="Say hello.")]
+
+    response = await client.get_response(
+        messages=messages,
+        chat_options=ChatOptions(max_tokens=20, temperature=0.0),
+    )
+
+    assert response is not None
+    assert response.messages[0].text is not None
+
+
+@pytest.mark.flaky
+@skip_if_anthropic_integration_tests_disabled
+async def test_anthropic_client_integration_ordering() -> None:
+    """Integration test with ordering."""
+    client = AnthropicClient()
+
+    messages = [
+        ChatMessage(role=Role.USER, text="Say hello."),
+        ChatMessage(role=Role.USER, text="Then say goodbye."),
+        ChatMessage(role=Role.ASSISTANT, text="Thank you for chatting!"),
+        ChatMessage(role=Role.ASSISTANT, text="Let me know if I can help."),
+        ChatMessage(role=Role.USER, text="Just testing things."),
+    ]
+
+    response = await client.get_response(messages=messages)
+
+    assert response is not None
+    assert response.messages[0].text is not None

python/packages/azure-ai/agent_framework_azure_ai/_chat_client.py

@@ -735,10 +735,10 @@ class AzureAIAgentClient(BaseChatClient):
         chat_tool_mode = chat_options.tool_choice
         if chat_tool_mode is None or chat_tool_mode == ToolMode.NONE or chat_tool_mode == "none":
             chat_options.tools = None
-            chat_options.tool_choice = ToolMode.NONE.mode
+            chat_options.tool_choice = ToolMode.NONE
             return
 
-        chat_options.tool_choice = chat_tool_mode.mode if isinstance(chat_tool_mode, ToolMode) else chat_tool_mode
+        chat_options.tool_choice = chat_tool_mode
 
     async def _create_run_options(
         self,

python/packages/core/agent_framework/_clients.py

@@ -690,12 +690,12 @@ class BaseChatClient(SerializationMixin, ABC):
         chat_tool_mode = chat_options.tool_choice
         if chat_tool_mode is None or chat_tool_mode == ToolMode.NONE or chat_tool_mode == "none":
             chat_options.tools = None
-            chat_options.tool_choice = ToolMode.NONE.mode
+            chat_options.tool_choice = ToolMode.NONE
             return
         if not chat_options.tools:
-            chat_options.tool_choice = ToolMode.NONE.mode
+            chat_options.tool_choice = ToolMode.NONE
         else:
-            chat_options.tool_choice = chat_tool_mode.mode if isinstance(chat_tool_mode, ToolMode) else chat_tool_mode
+            chat_options.tool_choice = chat_tool_mode
 
     def service_url(self) -> str:
         """Get the URL of the service.

python/packages/core/agent_framework/_types.py

@@ -561,7 +561,7 @@ class BaseContent(SerializationMixin):
     def __init__(
         self,
         *,
-        annotations: list[Annotations | MutableMapping[str, Any]] | None = None,
+        annotations: Sequence[Annotations | MutableMapping[str, Any]] | None = None,
         additional_properties: dict[str, Any] | None = None,
         raw_representation: Any | None = None,
         **kwargs: Any,
@@ -651,7 +651,7 @@ class TextContent(BaseContent):
         *,
         additional_properties: dict[str, Any] | None = None,
         raw_representation: Any | None = None,
-        annotations: list[Annotations | MutableMapping[str, Any]] | None = None,
+        annotations: Sequence[Annotations | MutableMapping[str, Any]] | None = None,
         **kwargs: Any,
     ):
         """Initializes a TextContent instance.
@@ -793,7 +793,7 @@ class TextReasoningContent(BaseContent):
         *,
         additional_properties: dict[str, Any] | None = None,
         raw_representation: Any | None = None,
-        annotations: list[Annotations | MutableMapping[str, Any]] | None = None,
+        annotations: Sequence[Annotations | MutableMapping[str, Any]] | None = None,
         **kwargs: Any,
     ):
         """Initializes a TextReasoningContent instance.
@@ -936,7 +936,7 @@ class DataContent(BaseContent):
         self,
         *,
         uri: str,
-        annotations: list[Annotations | MutableMapping[str, Any]] | None = None,
+        annotations: Sequence[Annotations | MutableMapping[str, Any]] | None = None,
         additional_properties: dict[str, Any] | None = None,
         raw_representation: Any | None = None,
         **kwargs: Any,
@@ -962,7 +962,7 @@ class DataContent(BaseContent):
         *,
         data: bytes,
         media_type: str,
-        annotations: list[Annotations | MutableMapping[str, Any]] | None = None,
+        annotations: Sequence[Annotations | MutableMapping[str, Any]] | None = None,
         additional_properties: dict[str, Any] | None = None,
         raw_representation: Any | None = None,
         **kwargs: Any,
@@ -989,7 +989,7 @@ class DataContent(BaseContent):
         uri: str | None = None,
         data: bytes | None = None,
         media_type: str | None = None,
-        annotations: list[Annotations | MutableMapping[str, Any]] | None = None,
+        annotations: Sequence[Annotations | MutableMapping[str, Any]] | None = None,
         additional_properties: dict[str, Any] | None = None,
         raw_representation: Any | None = None,
         **kwargs: Any,
@@ -1093,7 +1093,7 @@ class UriContent(BaseContent):
         uri: str,
         media_type: str,
         *,
-        annotations: list[Annotations | MutableMapping[str, Any]] | None = None,
+        annotations: Sequence[Annotations | MutableMapping[str, Any]] | None = None,
         additional_properties: dict[str, Any] | None = None,
         raw_representation: Any | None = None,
         **kwargs: Any,
@@ -1187,7 +1187,7 @@ class ErrorContent(BaseContent):
         message: str | None = None,
         error_code: str | None = None,
         details: str | None = None,
-        annotations: list[Annotations | MutableMapping[str, Any]] | None = None,
+        annotations: Sequence[Annotations | MutableMapping[str, Any]] | None = None,
         additional_properties: dict[str, Any] | None = None,
         raw_representation: Any | None = None,
         **kwargs: Any,
@@ -1271,7 +1271,7 @@ class FunctionCallContent(BaseContent):
         name: str,
         arguments: str | dict[str, Any | None] | None = None,
         exception: Exception | None = None,
-        annotations: list[Annotations | MutableMapping[str, Any]] | None = None,
+        annotations: Sequence[Annotations | MutableMapping[str, Any]] | None = None,
         additional_properties: dict[str, Any] | None = None,
         raw_representation: Any | None = None,
         **kwargs: Any,
@@ -1380,7 +1380,7 @@ class FunctionResultContent(BaseContent):
         call_id: str,
         result: Any | None = None,
         exception: Exception | None = None,
-        annotations: list[Annotations | MutableMapping[str, Any]] | None = None,
+        annotations: Sequence[Annotations | MutableMapping[str, Any]] | None = None,
         additional_properties: dict[str, Any] | None = None,
         raw_representation: Any | None = None,
         **kwargs: Any,
@@ -1438,7 +1438,7 @@ class UsageContent(BaseContent):
         self,
         details: UsageDetails | MutableMapping[str, Any],
         *,
-        annotations: list[Annotations | MutableMapping[str, Any]] | None = None,
+        annotations: Sequence[Annotations | MutableMapping[str, Any]] | None = None,
         additional_properties: dict[str, Any] | None = None,
         raw_representation: Any | None = None,
         **kwargs: Any,
@@ -1556,7 +1556,7 @@ class BaseUserInputRequest(BaseContent):
         self,
         *,
         id: str,
-        annotations: list[Annotations | MutableMapping[str, Any]] | None = None,
+        annotations: Sequence[Annotations | MutableMapping[str, Any]] | None = None,
         additional_properties: dict[str, Any] | None = None,
         raw_representation: Any | None = None,
         **kwargs: Any,
@@ -1610,7 +1610,7 @@ class FunctionApprovalResponseContent(BaseContent):
         *,
         id: str,
         function_call: FunctionCallContent | MutableMapping[str, Any],
-        annotations: list[Annotations | MutableMapping[str, Any]] | None = None,
+        annotations: Sequence[Annotations | MutableMapping[str, Any]] | None = None,
         additional_properties: dict[str, Any] | None = None,
         raw_representation: Any | None = None,
         **kwargs: Any,
@@ -1674,7 +1674,7 @@ class FunctionApprovalRequestContent(BaseContent):
         *,
         id: str,
         function_call: FunctionCallContent | MutableMapping[str, Any],
-        annotations: list[Annotations | MutableMapping[str, Any]] | None = None,
+        annotations: Sequence[Annotations | MutableMapping[str, Any]] | None = None,
         additional_properties: dict[str, Any] | None = None,
         raw_representation: Any | None = None,
         **kwargs: Any,
@@ -3146,7 +3146,7 @@ class ChatOptions(SerializationMixin):
     @classmethod
     def _validate_tool_mode(
         cls, tool_choice: ToolMode | Literal["auto", "required", "none"] | Mapping[str, Any] | None
-    ) -> ToolMode | str | None:
+    ) -> ToolMode | None:
         """Validates the tool_choice field to ensure it is a valid ToolMode."""
         if not tool_choice:
             return None

python/packages/core/agent_framework/anthropic/__init__.py

@@ -0,0 +1,23 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import importlib
+from typing import Any
+
+PACKAGE_NAME = "agent_framework_anthropic"
+PACKAGE_EXTRA = "anthropic"
+_IMPORTS = ["__version__", "AnthropicClient"]
+
+
+def __getattr__(name: str) -> Any:
+    if name in _IMPORTS:
+        try:
+            return getattr(importlib.import_module(PACKAGE_NAME), name)
+        except ModuleNotFoundError as exc:
+            raise ModuleNotFoundError(
+                f"The '{PACKAGE_EXTRA}' extra is not installed, please do `pip install agent-framework-{PACKAGE_EXTRA}`"
+            ) from exc
+    raise AttributeError(f"Module {PACKAGE_NAME} has no attribute {name}.")
+
+
+def __dir__() -> list[str]:
+    return _IMPORTS

python/packages/core/agent_framework/anthropic/__init__.pyi

@@ -0,0 +1,5 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from agent_framework_anthropic import AnthropicClient, __version__
+
+__all__ = ["AnthropicClient", "__version__"]

python/packages/core/agent_framework/openai/_assistants_client.py

@@ -408,7 +408,7 @@ class OpenAIAssistantsClient(OpenAIConfigMixin, BaseChatClient):
                     run_options["tools"] = tool_definitions
 
                 if chat_options.tool_choice == "none" or chat_options.tool_choice == "auto":
-                    run_options["tool_choice"] = chat_options.tool_choice
+                    run_options["tool_choice"] = chat_options.tool_choice.mode
                 elif (
                     isinstance(chat_options.tool_choice, ToolMode)
                     and chat_options.tool_choice == "required"

python/packages/core/agent_framework/openai/_chat_client.py

@@ -191,6 +191,8 @@ class OpenAIBaseChatClient(OpenAIBase, BaseChatClient):
             for key, value in additional_properties.items():
                 if value is not None:
                     options_dict[key] = value
+        if (tool_choice := options_dict.get("tool_choice")) and len(tool_choice.keys()) == 1:
+            options_dict["tool_choice"] = tool_choice["mode"]
         return options_dict
 
     def _create_chat_response(self, response: ChatCompletion, chat_options: ChatOptions) -> "ChatResponse":

python/packages/core/agent_framework/openai/_responses_client.py

@@ -345,6 +345,8 @@ class OpenAIBaseResponsesClient(OpenAIBase, BaseChatClient):
                     options_dict[key] = value
         if "store" not in options_dict:
             options_dict["store"] = False
+        if (tool_choice := options_dict.get("tool_choice")) and len(tool_choice.keys()) == 1:
+            options_dict["tool_choice"] = tool_choice["mode"]
         return options_dict
 
     def _prepare_chat_messages_for_request(self, chat_messages: Sequence[ChatMessage]) -> list[dict[str, Any]]:

python/packages/core/pyproject.toml

@@ -45,6 +45,8 @@ all = [
     "agent-framework-mem0",
     "agent-framework-redis",
     "agent-framework-devui",
+    "agent-framework-purview",
+    "agent-framework-anthropic",
 ]
 
 [tool.uv]