Repository navigation
Add Microsoft Agent Framework plugin samples #418
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
DABH
wants to merge
37
commits into
main
Choose a base branch
from
dabh/agent-framework-plugin
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
+5,432
−200
Open
Changes from all commits
Commits
Show all changes
37 commits
Select commit
Hold shift + click to select a range
538c15b
Add the agent-framework dependency group and lock it
DABH d62d1ef
Keep Client.connect sites type-checking on temporalio 1.36
DABH 6da7d77
Add Microsoft Agent Framework samples
DABH ca8a71b
Test the Agent Framework samples with a scripted chat client
DABH b7410ed
Document and register the Agent Framework samples
DABH 53ece11
Record the human-in-the-loop decision in the Update handler
DABH ef55d93
Restore the Claude tests row in CODEOWNERS
DABH a7fbfcd
Key the human-in-the-loop decision to its request
DABH 27f5157
Keep the middleware snippet self-contained
DABH fe521e2
Fail the Claude decision Update instead of the Workflow Task
DABH 4124a04
Read the transcript through the provider's source id
DABH 035d61d
Point the sample README at poe test
DABH 440e36a
Pin the plugin to its round-1 revision
DABH 16dbbfa
Pin the plugin to its current revision
DABH 4002670
State the Python floor as the plugin's requires-python
DABH be77fc1
Use poe test in the mcp README and note the no-collector case
DABH 83d46bf
Name the request id in the approval wait
DABH 7c737ec
Rename the samples to microsoft_agent_framework_plugin
DABH cca8634
Pin the plugin to d374e26c
DABH 0b94d38
Let the streaming topic route the model call
DABH 45e76fe
Pin the plugin to 8b472d21
DABH e711f1d
Test turns and end_chat sent while a turn is running
DABH 485c406
Pin the plugin to a453fa6c
DABH 6fad07a
Pin the plugin to 54998df8
DABH 9ac1b81
Pin the plugin to its merge commit on main
DABH df932db
Add plugins to the loaded client config on temporalio 1.36
DABH 585c7c9
Merge remote-tracking branch 'origin/main' into dabh/agent-framework-…
DABH 207fa64
State the MCP Activities' heartbeat default in the mcp README
DABH 4b278f9
Depend on temporalio-microsoft-agent-framework 0.0.1 from PyPI
DABH f0d599a
Await the stream subscriber instead of draining it
DABH d4039d6
Build the chat agent and session in a workflow.init
DABH a4e303f
Skip the mcp sample tests on the Python version only
DABH 84bc658
Assert the agent span is exported once under the Workflow span
DABH f5762ac
Normalize the path before the middleware prefix check
DABH 698b636
Say why the decide handler's None branch exists
DABH 0cb95e0
Import posixpath at the top of the middleware module
DABH 05682ab
Refuse with the path the model sent
DABH File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,108 @@ | ||
| # Microsoft Agent Framework samples | ||
|
|
||
| These samples show the [Temporal plugin for Microsoft Agent Framework](https://github.com/temporalio/ai-integrations/tree/main/python/microsoft_agent_framework), which runs an Agent Framework `Agent` inside a Temporal Workflow. You write the agent the way Agent Framework documents it and swap the chat client for `TemporalChatClient`. Each model call then runs as the `microsoft_agent_framework.invoke_model` Activity (`microsoft_agent_framework.invoke_model_streaming` when you stream), with its own timeout and retries. The agent's loop, tools, middleware and approvals run in the Workflow, where Temporal records every step and replays it after a crash or a Worker restart. The docs page is [Microsoft Agent Framework](https://docs.temporal.io/develop/python/integrations/microsoft-agent-framework). | ||
|
|
||
| > **Pre-release.** The `temporalio-microsoft-agent-framework` package and its interfaces may change before General Availability. | ||
|
|
||
| `MicrosoftAgentFrameworkPlugin` goes on the Client or on the Worker, not both. These samples put it on `Client.connect(...)`; the Worker built from that Client inherits it. | ||
|
|
||
| ## Samples | ||
|
|
||
| | Sample | Description | | ||
| |--------|-------------| | ||
| | [hello_world](hello_world) | One `Agent` over `TemporalChatClient`, one prompt, one model Activity. Start here. | | ||
| | [tools](tools) | A pure `@tool` that runs in the Workflow next to an Activity wrapped with `activity_as_tool`. | | ||
| | [mcp](mcp) | Tools from an MCP server through `TemporalMCPToolProvider`; the listing and each call are Activities. Its own uv project, see below. | | ||
| | [human_in_the_loop](human_in_the_loop) | A tool with `approval_mode="always_require"`. The Workflow publishes the request through a Query, waits for a `decide` Update and answers on the same session. | | ||
| | [middleware](middleware) | Function and chat middleware running in the Workflow: one refuses a tool call, one edits the instructions. | | ||
| | [multi_agent](multi_agent) | A coordinator with two sub-agents as tools through `Agent.as_tool()`; every agent's model calls are Activities. | | ||
| | [structured_output](structured_output) | `response_format` with a Pydantic model; the Workflow returns the model through the plugin's data converter. | | ||
| | [streaming](streaming) | `streaming_topic` publishes each update to a Workflow Stream; the starter prints them as they arrive. | | ||
| | [continue_as_new](continue_as_new) | A chat driven by Updates that hands `session.to_dict()` to a fresh run when Temporal suggests Continue-As-New. | | ||
| | [open_telemetry](open_telemetry) | `OpenTelemetryPlugin` and `MicrosoftAgentFrameworkPlugin` on one Client: one trace from the starter through the Workflow to the model Activity. | | ||
|
|
||
| ## Prerequisites | ||
|
|
||
| 1. Python 3.11 or later. The plugin declares `requires-python = ">=3.11"`, as Temporal Python SDK 1.36 does, so on 3.10 the `microsoft-agent-framework` dependency group resolves to nothing and the tests are not collected. | ||
|
|
||
| 2. Install the dependencies from the repository root: | ||
|
|
||
| ```bash | ||
| uv sync --group microsoft-agent-framework | ||
| ``` | ||
|
|
||
| This installs `temporalio-microsoft-agent-framework`, `agent-framework-openai` and Temporal Python SDK 1.36.0 or later. | ||
|
|
||
| 3. An OpenAI API key. Each Worker reads it when it builds the `OpenAIChatClient`; the Workflow only carries the model name `gpt-4o-mini`: | ||
|
|
||
| ```bash | ||
| export OPENAI_API_KEY=... | ||
| ``` | ||
|
|
||
| 4. A local Temporal Service from the [Temporal CLI](https://docs.temporal.io/cli): | ||
|
|
||
| ```bash | ||
| temporal server start-dev | ||
| ``` | ||
|
|
||
| ## Running a sample | ||
|
|
||
| Each sample has two scripts. Start the Worker first, then the starter in a second terminal, both from the repository root: | ||
|
|
||
| ```bash | ||
| # Terminal 1: start the Worker | ||
| uv run microsoft_agent_framework_plugin/<sample>/run_worker.py | ||
|
|
||
| # Terminal 2: start the Workflow | ||
| uv run microsoft_agent_framework_plugin/<sample>/run_workflow.py | ||
| ``` | ||
|
|
||
| For example, for the tools sample: | ||
|
|
||
| ```bash | ||
| # Terminal 1 | ||
| uv run microsoft_agent_framework_plugin/tools/run_worker.py | ||
|
|
||
| # Terminal 2 | ||
| uv run microsoft_agent_framework_plugin/tools/run_workflow.py | ||
| ``` | ||
|
|
||
| The `mcp` sample is its own uv project: the plugin's MCP support needs MCP Python SDK 2, and other samples in this repository still pin SDK 1, so they cannot share one lock file. Run it from its directory: | ||
|
|
||
| ```bash | ||
| cd microsoft_agent_framework_plugin/mcp | ||
| uv sync | ||
|
|
||
| # Terminal 1 | ||
| uv run run_worker.py | ||
|
|
||
| # Terminal 2 | ||
| uv run run_workflow.py | ||
| ``` | ||
|
|
||
| ## Key features | ||
|
|
||
| - One Activity per model round trip, `microsoft_agent_framework.invoke_model`, with a 60-second start-to-close timeout in these samples and the plugin's default 10-second heartbeat timeout. Temporal owns retries, so the Workers build the OpenAI client with `AsyncOpenAI(max_retries=0)`. | ||
| - Tools run where you put them: a plain `@tool` runs in the Workflow, `activity_as_tool` runs an Activity with its own `start_to_close_timeout`. | ||
| - MCP servers are registered on the Worker. `TemporalMCPToolProvider` lists and calls their tools through the `temporalio.mcp.<server>.list-tools` and `temporalio.mcp.<server>.call-tool` Activities. | ||
| - Approvals are Agent Framework's own `approval_mode`; the wait is a Workflow Update with a validator. | ||
| - Middleware and context providers run in the Workflow, so they must be deterministic; I/O in middleware goes through `workflow.execute_activity`. | ||
| - Streaming publishes `ChatResponseUpdate` dicts to a Workflow Stream topic, batched every 100 milliseconds. | ||
| - Long chats carry `session.to_dict()` across Continue-As-New and restore it with `AgentSession.from_dict`. | ||
| - `OpenTelemetryPlugin` composes on the same Client; `create_tracer_provider()` keeps the spans Agent Framework starts from Workflow code replay-safe. | ||
|
|
||
| ## Tests | ||
|
|
||
| The tests run every sample against the plugin's scripted `FakeChatClient` and a local dev server, with no API key: | ||
|
|
||
| ```bash | ||
| uv run poe test tests/microsoft_agent_framework_plugin | ||
| uv run poe test tests/microsoft_agent_framework_plugin --workflow-environment time-skipping | ||
| cd microsoft_agent_framework_plugin/mcp && uv run poe test | ||
| ``` | ||
|
|
||
| ## Related | ||
|
|
||
| - [Temporal plugin for Microsoft Agent Framework](https://github.com/temporalio/ai-integrations/tree/main/python/microsoft_agent_framework) | ||
| - [Microsoft Agent Framework](https://github.com/microsoft/agent-framework) | ||
| - [Microsoft Agent Framework docs page](https://docs.temporal.io/develop/python/integrations/microsoft-agent-framework) |
Empty file.
31 changes: 31 additions & 0 deletions
31
microsoft_agent_framework_plugin/continue_as_new/README.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,31 @@ | ||
| # Continue-as-new | ||
|
|
||
| A chat that runs as long as you like. Each user turn is an Update, so the caller gets the reply from the same call. History grows with every turn, and `workflow.info().is_continue_as_new_suggested()` turns `True` once the Temporal Service decides it is large enough. The Workflow waits on that or on the `end_chat` Signal, lets in-flight Updates finish with `workflow.all_handlers_finished`, and hands `session.to_dict()` to a fresh run, which restores it with `AgentSession.from_dict`. | ||
|
|
||
| What crosses the boundary: the serialized session, which holds the transcript, any pending approval state and the provider's conversation id. What does not: the `Agent` object, provider connections and spans; the new run builds the agent again. Nothing waits in Workflow fields at the handoff: a `turn` is an Update, so it completes in the run that accepted it and returns its reply from there, `workflow.all_handlers_finished` lets an accepted turn finish before the handoff, and an `end_chat` that arrives during a turn ends the chat after that turn instead of being lost. | ||
|
|
||
| ## What this sample demonstrates | ||
|
|
||
| - The `turn` Update, the `end_chat` Signal and the `transcript` Query | ||
| - An `asyncio.Lock` so turns take the session one at a time | ||
| - `workflow.continue_as_new(ChatInput(session=session.to_dict()))` | ||
|
|
||
| ## Running the sample | ||
|
|
||
| ```bash | ||
| # Terminal 1 | ||
| uv run microsoft_agent_framework_plugin/continue_as_new/run_worker.py | ||
|
|
||
| # Terminal 2 | ||
| uv run microsoft_agent_framework_plugin/continue_as_new/run_workflow.py | ||
| ``` | ||
|
|
||
| The starter sends two turns, prints each reply, prints the number of messages in the session and ends the chat. Two turns do not reach the default threshold, so the Workflow `microsoft-agent-framework-chat` completes in one run; the test lowers the threshold to see the handoff. In a chat application a UI would drive the Updates and the Workflow would run on, continuing as new whenever history gets large. | ||
|
|
||
| ## Files | ||
|
|
||
| | File | Description | | ||
| |------|-------------| | ||
| | `workflow.py` | `ChatInput` and `ChatWorkflow` with the Update, Signal and Query | | ||
| | `run_worker.py` | Registers the plugin, starts the Worker on `microsoft-agent-framework-chat` | | ||
| | `run_workflow.py` | Starts the chat, sends two turns, ends it | |
Empty file.
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.