wangtao
/
autogen
mirror of https://github.com/microsoft/autogen.git
1
0
Fork 1
Code Issues Packages Projects Releases Wiki Activity

feat: add Semantic Kernel Adapter documentation and usage examples in user guides (#5256) 

Partially address #5205 and #5226
This commit is contained in:
Eric Zhu 2025-01-29 16:37:18 -08:00 committed by GitHub
parent 7020f2ac34
commit 403844ef2b
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
3 changed files with 337 additions and 114 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

95
python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/tutorial/models.ipynb
View File

@ -327,6 +327,101 @@
"response = await model_client.create([UserMessage(content=\"What is the capital of France?\", source=\"user\")])\n",
"print(response)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Semantic Kernel Adapter\n",
"\n",
"The {py:class}`~autogen_ext.models.semantic_kernel.SKChatCompletionAdapter`\n",
"allows you to use Semantic kernel model clients as a\n",
"{py:class}`~autogen_core.models.ChatCompletionClient` by adapting them to the required interface.\n",
"\n",
"You need to install the relevant provider extras to use this adapter. \n",
"\n",
"The list of extras that can be installed:\n",
"\n",
"- `semantic-kernel-anthropic`: Install this extra to use Anthropic models.\n",
"- `semantic-kernel-google`: Install this extra to use Google Gemini models.\n",
"- `semantic-kernel-ollama`: Install this extra to use Ollama models.\n",
"- `semantic-kernel-mistralai`: Install this extra to use MistralAI models.\n",
"- `semantic-kernel-aws`: Install this extra to use AWS models.\n",
"- `semantic-kernel-hugging-face`: Install this extra to use Hugging Face models.\n",
"\n",
"For example, to use Anthropic models, you need to install `semantic-kernel-anthropic`."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"vscode": {
"languageId": "shellscript"
}
},
"outputs": [],
"source": [
"# pip install \"autogen-ext[semantic-kernel-anthropic]\""
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"To use this adapter, you need create a Semantic Kernel model client and pass it to the adapter.\n",
"\n",
"For example, to use the Anthropic model:"
]
},
{
"cell_type": "code",
"execution_count": 1,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"finish_reason='stop' content='The capital of France is Paris. It is also the largest city in France and one of the most populous metropolitan areas in Europe.' usage=RequestUsage(prompt_tokens=0, completion_tokens=0) cached=False logprobs=None\n"
]
}
],
"source": [
"import os\n",
"\n",
"from autogen_core.models import UserMessage\n",
"from autogen_ext.models.semantic_kernel import SKChatCompletionAdapter\n",
"from semantic_kernel import Kernel\n",
"from semantic_kernel.connectors.ai.anthropic import AnthropicChatCompletion, AnthropicChatPromptExecutionSettings\n",
"from semantic_kernel.memory.null_memory import NullMemory\n",
"\n",
"sk_client = AnthropicChatCompletion(\n",
" ai_model_id=\"claude-3-5-sonnet-20241022\",\n",
" api_key=os.environ[\"ANTHROPIC_API_KEY\"],\n",
" service_id=\"my-service-id\", # Optional; for targeting specific services within Semantic Kernel\n",
")\n",
"settings = AnthropicChatPromptExecutionSettings(\n",
" temperature=0.2,\n",
")\n",
"\n",
"anthropic_model_client = SKChatCompletionAdapter(\n",
" sk_client, kernel=Kernel(memory=NullMemory()), prompt_settings=settings\n",
")\n",
"\n",
"# Call the model directly.\n",
"model_result = await anthropic_model_client.create(\n",
" messages=[UserMessage(content=\"What is the capital of France?\", source=\"User\")]\n",
")\n",
"print(model_result)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Read more about the [Semantic Kernel Adapter](../../../reference/python/autogen_ext.models.semantic_kernel.rst)."
]
}
],
"metadata": {

95
python/packages/autogen-core/docs/src/user-guide/core-user-guide/components/model-clients.ipynb
View File

@ -336,6 +336,101 @@
"print(response)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Semantic Kernel Adapter\n",
"\n",
"The {py:class}`~autogen_ext.models.semantic_kernel.SKChatCompletionAdapter`\n",
"allows you to use Semantic kernel model clients as a\n",
"{py:class}`~autogen_core.models.ChatCompletionClient` by adapting them to the required interface.\n",
"\n",
"You need to install the relevant provider extras to use this adapter. \n",
"\n",
"The list of extras that can be installed:\n",
"\n",
"- `semantic-kernel-anthropic`: Install this extra to use Anthropic models.\n",
"- `semantic-kernel-google`: Install this extra to use Google Gemini models.\n",
"- `semantic-kernel-ollama`: Install this extra to use Ollama models.\n",
"- `semantic-kernel-mistralai`: Install this extra to use MistralAI models.\n",
"- `semantic-kernel-aws`: Install this extra to use AWS models.\n",
"- `semantic-kernel-hugging-face`: Install this extra to use Hugging Face models.\n",
"\n",
"For example, to use Anthropic models, you need to install `semantic-kernel-anthropic`."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"vscode": {
"languageId": "shellscript"
}
},
"outputs": [],
"source": [
"# pip install \"autogen-ext[semantic-kernel-anthropic]\""
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"To use this adapter, you need create a Semantic Kernel model client and pass it to the adapter.\n",
"\n",
"For example, to use the Anthropic model:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"finish_reason='stop' content='The capital of France is Paris. It is also the largest city in France and one of the most populous metropolitan areas in Europe.' usage=RequestUsage(prompt_tokens=0, completion_tokens=0) cached=False logprobs=None\n"
]
}
],
"source": [
"import os\n",
"\n",
"from autogen_core.models import UserMessage\n",
"from autogen_ext.models.semantic_kernel import SKChatCompletionAdapter\n",
"from semantic_kernel import Kernel\n",
"from semantic_kernel.connectors.ai.anthropic import AnthropicChatCompletion, AnthropicChatPromptExecutionSettings\n",
"from semantic_kernel.memory.null_memory import NullMemory\n",
"\n",
"sk_client = AnthropicChatCompletion(\n",
" ai_model_id=\"claude-3-5-sonnet-20241022\",\n",
" api_key=os.environ[\"ANTHROPIC_API_KEY\"],\n",
" service_id=\"my-service-id\", # Optional; for targeting specific services within Semantic Kernel\n",
")\n",
"settings = AnthropicChatPromptExecutionSettings(\n",
" temperature=0.2,\n",
")\n",
"\n",
"anthropic_model_client = SKChatCompletionAdapter(\n",
" sk_client, kernel=Kernel(memory=NullMemory()), prompt_settings=settings\n",
")\n",
"\n",
"# Call the model directly.\n",
"model_result = await anthropic_model_client.create(\n",
" messages=[UserMessage(content=\"What is the capital of France?\", source=\"User\")]\n",
")\n",
"print(model_result)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Read more about the [Semantic Kernel Adapter](../../../reference/python/autogen_ext.models.semantic_kernel.rst)."
]
},
{
"cell_type": "markdown",
"metadata": {},

261
python/packages/autogen-ext/src/autogen_ext/models/semantic_kernel/_sk_chat_completion_adapter.py
View File

@ -35,11 +35,20 @@ class SKChatCompletionAdapter(ChatCompletionClient):
By leveraging this adapter, you can:
- Pass in a `Kernel` and any supported Semantic Kernel `ChatCompletionClientBase` connector.
- Provide tools (via Autogen `Tool` or `ToolSchema`) for function calls during chat completion.
- Stream responses or retrieve them in a single request.
- Provide prompt settings to control the chat completion behavior either globally through the constructor
or on a per-request basis through the `extra_create_args` dictionary.
- Pass in a `Kernel` and any supported Semantic Kernel `ChatCompletionClientBase` connector.
- Provide tools (via Autogen `Tool` or `ToolSchema`) for function calls during chat completion.
- Stream responses or retrieve them in a single request.
- Provide prompt settings to control the chat completion behavior either globally through the constructor
or on a per-request basis through the `extra_create_args` dictionary.
The list of extras that can be installed:
- `semantic-kernel-anthropic`: Install this extra to use Anthropic models.
- `semantic-kernel-google`: Install this extra to use Google Gemini models.
- `semantic-kernel-ollama`: Install this extra to use Ollama models.
- `semantic-kernel-mistralai`: Install this extra to use MistralAI models.
- `semantic-kernel-aws`: Install this extra to use AWS models.
- `semantic-kernel-hugging-face`: Install this extra to use Hugging Face models.
Args:
sk_client (ChatCompletionClientBase):
@ -54,124 +63,148 @@ class SKChatCompletionAdapter(ChatCompletionClient):
service_id (Optional[str]):
Optional service identifier.
Example usage:
Examples:
.. code-block:: python
Anthropic models:
import asyncio
from semantic_kernel import Kernel
from semantic_kernel.memory.null_memory import NullMemory
from semantic_kernel.connectors.ai.open_ai.services.azure_chat_completion import AzureChatCompletion
from semantic_kernel.connectors.ai.open_ai.prompt_execution_settings.azure_chat_prompt_execution_settings import (
AzureChatPromptExecutionSettings,
)
from semantic_kernel.connectors.ai.google.google_ai import GoogleAIChatCompletion
from semantic_kernel.connectors.ai.ollama import OllamaChatCompletion, OllamaChatPromptExecutionSettings
from autogen_core.models import SystemMessage, UserMessage, LLMMessage
from autogen_ext.models.semantic_kernel import SKChatCompletionAdapter
from autogen_core import CancellationToken
from autogen_core.tools import BaseTool
from pydantic import BaseModel
.. code-block:: bash
pip install "autogen-ext[semantic-kernel-anthropic]"
.. code-block:: python
import asyncio
import os
from autogen_agentchat.agents import AssistantAgent
from autogen_core.models import UserMessage
from autogen_ext.models.semantic_kernel import SKChatCompletionAdapter
from semantic_kernel import Kernel
from semantic_kernel.connectors.ai.anthropic import AnthropicChatCompletion, AnthropicChatPromptExecutionSettings
from semantic_kernel.memory.null_memory import NullMemory
# 1) Basic tool definition (for demonstration)
class CalculatorArgs(BaseModel):
a: float
b: float
class CalculatorResult(BaseModel):
result: float
class CalculatorTool(BaseTool[CalculatorArgs, CalculatorResult]):
def __init__(self) -> None:
super().__init__(
args_type=CalculatorArgs,
return_type=CalculatorResult,
name="calculator",
description="Add two numbers together",
async def main() -> None:
sk_client = AnthropicChatCompletion(
ai_model_id="claude-3-5-sonnet-20241022",
api_key=os.environ["ANTHROPIC_API_KEY"],
service_id="my-service-id", # Optional; for targeting specific services within Semantic Kernel
)
settings = AnthropicChatPromptExecutionSettings(
temperature=0.2,
)
async def run(self, args: CalculatorArgs, cancellation_token: CancellationToken) -> CalculatorResult:
return CalculatorResult(result=args.a + args.b)
model_client = SKChatCompletionAdapter(sk_client, kernel=Kernel(memory=NullMemory()), prompt_settings=settings)
# Call the model directly.
model_result = await model_client.create(
messages=[UserMessage(content="What is the capital of France?", source="User")]
)
print(model_result)
# Create an assistant agent with the model client.
assistant = AssistantAgent("assistant", model_client=model_client)
# Call the assistant with a task.
result = await assistant.run(task="What is the capital of France?")
print(result)
async def main():
# 2) Create a Semantic Kernel instance (with null memory for simplicity)
kernel = Kernel(memory=NullMemory())
# ----------------------------------------------------------------
# Example A: Azure OpenAI
# ----------------------------------------------------------------
deployment_name = "<AZURE_OPENAI_DEPLOYMENT_NAME>"
endpoint = "<AZURE_OPENAI_ENDPOINT>"
api_key = "<AZURE_OPENAI_API_KEY>"
azure_client = AzureChatCompletion(deployment_name=deployment_name, endpoint=endpoint, api_key=api_key)
azure_settings = AzureChatPromptExecutionSettings(temperature=0.8)
azure_adapter = SKChatCompletionAdapter(sk_client=azure_client, kernel=kernel, prompt_settings=azure_settings)
# ----------------------------------------------------------------
# Example B: Google Gemini
# ----------------------------------------------------------------
google_api_key = "<GCP_API_KEY>"
google_model = "gemini-1.5-flash"
google_client = GoogleAIChatCompletion(gemini_model_id=google_model, api_key=google_api_key)
google_adapter = SKChatCompletionAdapter(sk_client=google_client)
# ----------------------------------------------------------------
# Example C: Ollama (local Llama-based model)
# ----------------------------------------------------------------
ollama_client = OllamaChatCompletion(
service_id="ollama", # custom ID
host="http://localhost:11434",
ai_model_id="llama3.1",
)
request_settings = OllamaChatPromptExecutionSettings(
# For model specific settings, specify them in the options dictionary.
# For more information on the available options, refer to the Ollama API documentation:
# https://github.com/ollama/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values
options={
"temperature": 0.8,
},
)
ollama_adapter = SKChatCompletionAdapter(sk_client=ollama_client, prompt_settings=request_settings)
# 3) Create a tool and register it with the kernel
calc_tool = CalculatorTool()
# 4) Prepare messages for a chat completion
messages: list[LLMMessage] = [
SystemMessage(content="You are a helpful assistant."),
UserMessage(content="What is 2 + 2?", source="user"),
]
# 5) Invoke chat completion with different adapters
# Azure example
azure_result = await azure_adapter.create(
messages=messages,
tools=[calc_tool],
)
print("Azure result:", azure_result.content)
# Google example
google_result = await google_adapter.create(
messages=messages,
tools=[calc_tool],
)
print("Google result:", google_result.content)
# Ollama example
ollama_result = await ollama_adapter.create(
messages=messages,
tools=[calc_tool],
)
print("Ollama result:", ollama_result.content)
if __name__ == "__main__":
asyncio.run(main())
Google Gemini models:
.. code-block:: bash
pip install "autogen-ext[semantic-kernel-google]"
.. code-block:: python
import asyncio
import os
from autogen_agentchat.agents import AssistantAgent
from autogen_core.models import UserMessage
from autogen_ext.models.semantic_kernel import SKChatCompletionAdapter
from semantic_kernel import Kernel
from semantic_kernel.connectors.ai.google.google_ai import (
GoogleAIChatCompletion,
GoogleAIChatPromptExecutionSettings,
)
from semantic_kernel.memory.null_memory import NullMemory
async def main() -> None:
sk_client = GoogleAIChatCompletion(
gemini_model_id="gemini-1.5-flash",
api_key=os.environ["GEMINI_API_KEY"],
)
settings = GoogleAIChatPromptExecutionSettings(
temperature=0.2,
)
model_client = SKChatCompletionAdapter(sk_client, kernel=Kernel(memory=NullMemory()), prompt_settings=settings)
# Call the model directly.
model_result = await model_client.create(
messages=[UserMessage(content="What is the capital of France?", source="User")]
)
print(model_result)
# Create an assistant agent with the model client.
assistant = AssistantAgent("assistant", model_client=model_client)
# Call the assistant with a task.
result = await assistant.run(task="What is the capital of France?")
print(result)
asyncio.run(main())
Ollama models:
.. code-block:: bash
pip install "autogen-ext[semantic-kernel-ollama]"
.. code-block:: python
import asyncio
from autogen_agentchat.agents import AssistantAgent
from autogen_core.models import UserMessage
from autogen_ext.models.semantic_kernel import SKChatCompletionAdapter
from semantic_kernel import Kernel
from semantic_kernel.connectors.ai.ollama import OllamaChatCompletion, OllamaChatPromptExecutionSettings
from semantic_kernel.memory.null_memory import NullMemory
async def main() -> None:
sk_client = OllamaChatCompletion(
host="http://localhost:11434",
ai_model_id="llama3.2:latest",
)
ollama_settings = OllamaChatPromptExecutionSettings(
options={"temperature": 0.5},
)
model_client = SKChatCompletionAdapter(
sk_client, kernel=Kernel(memory=NullMemory()), prompt_settings=ollama_settings
)
# Call the model directly.
model_result = await model_client.create(
messages=[UserMessage(content="What is the capital of France?", source="User")]
)
print(model_result)
# Create an assistant agent with the model client.
assistant = AssistantAgent("assistant", model_client=model_client)
# Call the assistant with a task.
result = await assistant.run(task="What is the capital of France?")
print(result)
asyncio.run(main())
"""
def __init__(