Skip to content

Commit 1a84cb6

Browse files
authored
Python: prompt template config and kernel args support for agents (#10298)
### Motivation and Context To bring the SK Python framework closer to .Net parity, we need to support the ability to specify a prompt template config and kernel arguments for ChatCompletion Agents as well as for Assistant Agents. <!-- Thank you for your contribution to the semantic-kernel repo! Please help reviewers and future users, providing the following information: 1. Why is this change required? 2. What problem does it solve? 3. What scenario does it contribute to? 4. If it fixes an open issue, please link to the issue here. --> ### Description This PR adds support for: - being able to specify a prompt template config for SK agents. - allows kernel arguments to be passed to the agent as well as during invoke - invoke args, similar to other kwargs, take precedence over agent level config. - adds test coverage - creates agent templating samples for both ChatCompletionAgents and OpenAI/AzureAssistantAgents - closes #8022 - closes #8699 <!-- Describe your changes, the overall approach, the underlying design. These notes will help understanding how your code works. Thanks! --> ### Contribution Checklist <!-- Before submitting this PR, please make sure: --> - [X] The code builds clean without any errors or warnings - [X] The PR follows the [SK Contribution Guidelines](https://github.com/microsoft/semantic-kernel/blob/main/CONTRIBUTING.md) and the [pre-submission formatting script](https://github.com/microsoft/semantic-kernel/blob/main/CONTRIBUTING.md#development-scripts) raises no violations - [X] All unit tests pass, and I have added new tests where possible - [X] I didn't break anyone 😄
1 parent 2d7a558 commit 1a84cb6

22 files changed

Lines changed: 1004 additions & 95 deletions
Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
# Copyright (c) Microsoft. All rights reserved.
2+
3+
import asyncio
4+
5+
from semantic_kernel.agents.open_ai import AzureAssistantAgent, OpenAIAssistantAgent
6+
from semantic_kernel.contents.chat_message_content import ChatMessageContent
7+
from semantic_kernel.contents.utils.author_role import AuthorRole
8+
from semantic_kernel.functions.kernel_arguments import KernelArguments
9+
from semantic_kernel.kernel import Kernel
10+
from semantic_kernel.prompt_template.prompt_template_config import PromptTemplateConfig
11+
12+
#####################################################################
13+
# The following sample demonstrates how to create an assistant #
14+
# agent using either Azure OpenAI or OpenAI within Semantic Kernel. #
15+
# It uses parameterized prompts and shows how to swap between #
16+
# "semantic-kernel," "jinja2," and "handlebars" template formats, #
17+
# This sample highlights how the agent’s threaded conversation #
18+
# state parallels the Chat History in Semantic Kernel, ensuring #
19+
# all responses and parameters remain consistent throughout the #
20+
# session. #
21+
#####################################################################
22+
23+
inputs = [
24+
("Home cooking is great.", None),
25+
("Talk about world peace.", "iambic pentameter"),
26+
("Say something about doing your best.", "e. e. cummings"),
27+
("What do you think about having fun?", "old school rap"),
28+
]
29+
30+
31+
async def invoke_assistant_agent(agent: OpenAIAssistantAgent | AzureAssistantAgent, inputs):
32+
"""Invokes the given agent with each (input, style) in inputs."""
33+
thread_id = await agent.create_thread()
34+
35+
try:
36+
for user_input, style in inputs:
37+
# Add user message to the conversation
38+
await agent.add_chat_message(
39+
thread_id=thread_id,
40+
message=ChatMessageContent(role=AuthorRole.USER, content=user_input),
41+
)
42+
print(f"[USER]: {user_input}")
43+
44+
# If style is specified, override the 'style' argument
45+
argument_overrides = None
46+
if style:
47+
argument_overrides = KernelArguments(style=style)
48+
49+
# Stream agent responses
50+
async for response in agent.invoke(thread_id=thread_id, arguments=argument_overrides):
51+
print(f"[AGENT]: {response.content}")
52+
finally:
53+
# Clean up
54+
await agent.delete_thread(thread_id)
55+
await agent.delete()
56+
57+
58+
async def invoke_agent_with_template(
59+
kernel: Kernel, template_str: str, template_format: str, default_style: str = "haiku"
60+
):
61+
"""Creates an agent with the specified template and format, then invokes it using invoke_assistant_agent."""
62+
# Switch between Azure or OpenAI as desired:
63+
use_azure_openai = False
64+
65+
instructions = (
66+
"You are a friendly poet, skilled at writing a one verse poem on any requested topic. "
67+
"Always include the poem style in the final output."
68+
)
69+
70+
# Configure the prompt template
71+
prompt_config = PromptTemplateConfig(template=template_str, template_format=template_format)
72+
73+
if use_azure_openai:
74+
agent = await AzureAssistantAgent.create(
75+
kernel=kernel,
76+
service_id="agent",
77+
name="MyPoetAgent",
78+
instructions=instructions,
79+
prompt_template_config=prompt_config,
80+
arguments=KernelArguments(style=default_style),
81+
)
82+
else:
83+
agent = await OpenAIAssistantAgent.create(
84+
kernel=kernel,
85+
service_id="agent",
86+
name="MyPoetAgent",
87+
instructions=instructions,
88+
prompt_template_config=prompt_config,
89+
arguments=KernelArguments(style=default_style),
90+
)
91+
92+
await invoke_assistant_agent(agent, inputs)
93+
94+
95+
async def main():
96+
kernel = Kernel()
97+
98+
# 1) Using "semantic-kernel" format
99+
print("\n===== SEMANTIC-KERNEL FORMAT =====\n")
100+
semantic_kernel_template = """
101+
Write a one verse poem on the requested topic in the style of {{$style}}.
102+
Always state the requested style of the poem.
103+
"""
104+
await invoke_agent_with_template(
105+
kernel=kernel,
106+
template_str=semantic_kernel_template,
107+
template_format="semantic-kernel",
108+
default_style="haiku",
109+
)
110+
111+
# 2) Using "jinja2" format
112+
print("\n===== JINJA2 FORMAT =====\n")
113+
jinja2_template = """
114+
Write a one verse poem on the requested topic in the style of {{style}}.
115+
Always state the requested style of the poem.
116+
"""
117+
await invoke_agent_with_template(
118+
kernel=kernel, template_str=jinja2_template, template_format="jinja2", default_style="haiku"
119+
)
120+
121+
# 3) Using "handlebars" format
122+
print("\n===== HANDLEBARS FORMAT =====\n")
123+
handlebars_template = """
124+
Write a one verse poem on the requested topic in the style of {{style}}.
125+
Always state the requested style of the poem.
126+
"""
127+
await invoke_agent_with_template(
128+
kernel=kernel, template_str=handlebars_template, template_format="handlebars", default_style="haiku"
129+
)
130+
131+
132+
if __name__ == "__main__":
133+
asyncio.run(main())

‎python/samples/concepts/agents/chat_completion_function_termination.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@
1515
AutoFunctionInvocationContext,
1616
)
1717
from semantic_kernel.filters.filter_types import FilterTypes
18+
from semantic_kernel.functions.kernel_arguments import KernelArguments
1819
from semantic_kernel.functions.kernel_function_decorator import kernel_function
1920
from semantic_kernel.kernel import Kernel
2021

@@ -108,7 +109,7 @@ async def main():
108109
kernel=kernel,
109110
name=HOST_NAME,
110111
instructions=HOST_INSTRUCTIONS,
111-
execution_settings=settings,
112+
arguments=KernelArguments(settings=settings),
112113
)
113114

114115
# Define the chat history
Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
# Copyright (c) Microsoft. All rights reserved.
2+
3+
import asyncio
4+
5+
from semantic_kernel.agents.chat_completion.chat_completion_agent import ChatCompletionAgent
6+
from semantic_kernel.connectors.ai.open_ai.services.azure_chat_completion import AzureChatCompletion
7+
from semantic_kernel.connectors.ai.open_ai.services.open_ai_chat_completion import OpenAIChatCompletion
8+
from semantic_kernel.contents.chat_history import ChatHistory
9+
from semantic_kernel.contents.chat_message_content import ChatMessageContent
10+
from semantic_kernel.contents.utils.author_role import AuthorRole
11+
from semantic_kernel.functions.kernel_arguments import KernelArguments
12+
from semantic_kernel.kernel import Kernel
13+
from semantic_kernel.prompt_template.prompt_template_config import PromptTemplateConfig
14+
15+
#####################################################################
16+
# The following sample demonstrates how to create a chat completion #
17+
# agent using either Azure OpenAI or OpenAI within Semantic Kernel. #
18+
# It uses parameterized prompts and shows how to swap between #
19+
# "semantic-kernel," "jinja2," and "handlebars" template formats, #
20+
# This sample highlights the agent’s chat history conversation #
21+
# is managed and how kernel arguments are passed in and used. #
22+
#####################################################################
23+
24+
inputs = [
25+
("Home cooking is great.", None),
26+
("Talk about world peace.", "iambic pentameter"),
27+
("Say something about doing your best.", "e. e. cummings"),
28+
("What do you think about having fun?", "old school rap"),
29+
]
30+
31+
32+
def _create_kernel_with_chat_completion_service(use_azure_openai: bool = True) -> Kernel:
33+
kernel = Kernel()
34+
kernel.add_service(
35+
AzureChatCompletion(service_id="agent") if use_azure_openai else OpenAIChatCompletion(service_id="agent")
36+
)
37+
return kernel
38+
39+
40+
async def invoke_chat_completion_agent(agent: ChatCompletionAgent, inputs):
41+
"""Invokes the given agent with each (input, style) in inputs."""
42+
43+
chat = ChatHistory()
44+
45+
for user_input, style in inputs:
46+
# Add user message to the conversation
47+
chat.add_message(ChatMessageContent(role=AuthorRole.USER, content=user_input))
48+
print(f"[USER]: {user_input}")
49+
50+
# If style is specified, override the 'style' argument
51+
argument_overrides = None
52+
if style:
53+
argument_overrides = KernelArguments(style=style)
54+
55+
# Stream agent responses
56+
async for response in agent.invoke(history=chat, arguments=argument_overrides):
57+
print(f"[AGENT]: {response.content}")
58+
59+
60+
async def invoke_agent_with_template(
61+
kernel: Kernel, template_str: str, template_format: str, default_style: str = "haiku"
62+
):
63+
"""Creates an agent with the specified template and format, then invokes it using invoke_chat_completion_agent."""
64+
65+
instructions = (
66+
"You are a friendly poet, skilled at writing a one verse poem on any requested topic. "
67+
"Always include the poem style in the final output."
68+
)
69+
70+
# Configure the prompt template
71+
prompt_config = PromptTemplateConfig(template=template_str, template_format=template_format)
72+
73+
agent = ChatCompletionAgent(
74+
kernel=kernel,
75+
name="MyPoetAgent",
76+
instructions=instructions,
77+
prompt_template_config=prompt_config,
78+
arguments=KernelArguments(style=default_style),
79+
)
80+
81+
await invoke_chat_completion_agent(agent, inputs)
82+
83+
84+
async def main():
85+
kernel = _create_kernel_with_chat_completion_service()
86+
87+
# 1) Using "semantic-kernel" format
88+
print("\n===== SEMANTIC-KERNEL FORMAT =====\n")
89+
semantic_kernel_template = """
90+
Write a one verse poem on the requested topic in the style of {{$style}}.
91+
Always state the requested style of the poem.
92+
"""
93+
await invoke_agent_with_template(
94+
kernel=kernel,
95+
template_str=semantic_kernel_template,
96+
template_format="semantic-kernel",
97+
default_style="haiku",
98+
)
99+
100+
# 2) Using "jinja2" format
101+
print("\n===== JINJA2 FORMAT =====\n")
102+
jinja2_template = """
103+
Write a one verse poem on the requested topic in the style of {{style}}.
104+
Always state the requested style of the poem.
105+
"""
106+
await invoke_agent_with_template(
107+
kernel=kernel, template_str=jinja2_template, template_format="jinja2", default_style="haiku"
108+
)
109+
110+
# 3) Using "handlebars" format
111+
print("\n===== HANDLEBARS FORMAT =====\n")
112+
handlebars_template = """
113+
Write a one verse poem on the requested topic in the style of {{style}}.
114+
Always state the requested style of the poem.
115+
"""
116+
await invoke_agent_with_template(
117+
kernel=kernel, template_str=handlebars_template, template_format="handlebars", default_style="haiku"
118+
)
119+
120+
121+
if __name__ == "__main__":
122+
asyncio.run(main())

‎python/samples/concepts/agents/mixed_chat_agents_plugins.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@
1010
from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion
1111
from semantic_kernel.contents.chat_message_content import ChatMessageContent
1212
from semantic_kernel.contents.utils.author_role import AuthorRole
13+
from semantic_kernel.functions.kernel_arguments import KernelArguments
1314
from semantic_kernel.functions.kernel_function_decorator import kernel_function
1415
from semantic_kernel.kernel import Kernel
1516

@@ -86,7 +87,7 @@ async def main():
8687
kernel=kernel,
8788
name=REVIEWER_NAME,
8889
instructions=REVIEWER_INSTRUCTIONS,
89-
execution_settings=settings,
90+
arguments=KernelArguments(settings=settings),
9091
)
9192

9293
agent_writer = await OpenAIAssistantAgent.create(

‎python/samples/getting_started_with_agents/step2_plugins.py‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@
88
from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion
99
from semantic_kernel.contents.chat_history import ChatHistory
1010
from semantic_kernel.contents.utils.author_role import AuthorRole
11+
from semantic_kernel.functions.kernel_arguments import KernelArguments
1112
from semantic_kernel.functions.kernel_function_decorator import kernel_function
1213
from semantic_kernel.kernel import Kernel
1314

@@ -81,7 +82,11 @@ async def main():
8182

8283
# Create the agent
8384
agent = ChatCompletionAgent(
84-
service_id="agent", kernel=kernel, name=HOST_NAME, instructions=HOST_INSTRUCTIONS, execution_settings=settings
85+
service_id="agent",
86+
kernel=kernel,
87+
name=HOST_NAME,
88+
instructions=HOST_INSTRUCTIONS,
89+
arguments=KernelArguments(settings=settings),
8590
)
8691

8792
# Define the chat history

‎python/samples/learn_resources/agent_docs/chat_agent.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111
from semantic_kernel.contents.chat_history import ChatHistory
1212
from semantic_kernel.contents.chat_message_content import ChatMessageContent
1313
from semantic_kernel.contents.utils.author_role import AuthorRole
14+
from semantic_kernel.functions.kernel_arguments import KernelArguments
1415
from semantic_kernel.kernel import Kernel
1516

1617
# Adjust the sys.path so we can use the GitHubPlugin and GitHubSettings classes
@@ -60,7 +61,7 @@ async def main():
6061
6162
The current date and time is: {current_time}.
6263
""",
63-
execution_settings=settings,
64+
arguments=KernelArguments(settings=settings),
6465
)
6566

6667
history = ChatHistory()

0 commit comments

Comments
 (0)