Skip to content

Add the Microsoft Agent Framework integration page (Python) - #5712

Draft
DABH wants to merge 9 commits into
mainfrom
dabh/agent-framework-python-docs
Draft

DABH wants to merge 9 commits into
mainfrom
dabh/agent-framework-python-docs

Conversation

@DABH

@DABH DABH commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

What does this PR do?

This PR adds docs/develop/python/integrations/microsoft-agent-framework.mdx, the guide for the Temporal Python plugin for Microsoft Agent Framework, with the sidebar entry, the Python index bullet and the integrations grid card. The page covers install, hello world, Activity-backed tools, MCP, middleware, approvals, structured output, streaming, Continue-As-New and OpenTelemetry, and ends with the plugin's limits.

Notes to reviewers

The plugin is merged (temporalio/ai-integrations#522). Its first pre-release (0.0.1rc1) is on TestPyPI only, so the page names the package as it will be on PyPI and claims no version. The 17 code blocks are snipsync markers from temporalio/samples-python#418 and stay empty until that PR merges after the PyPI release; yarn snipsync then fills them, staging only this file, and the PR can be marked ready. The page stays a draft until then. The branch is merged with main; Vale with the CI config, the snipsync-marker check and the orphan check pass.

DABH added 3 commits November 12, 2026 23:13
Add docs/develop/python/integrations/agent-framework.mdx for the
temporalio-agent-framework plugin, register it first in the Python
Integrations sidebar category, list it on the Python SDK index page, and
add its IntegrationsGrid entry.

The snippet blocks are empty on purpose. They reference markers in the
samples-python agent_framework_plugin samples, which are not on main yet.
Run yarn snipsync after that PR merges, before marking the docs PR ready.
Describe the streamed Activity result as the plugin now records it:
text runs and tool-call argument deltas merged, one payload under the
2 MiB limit, and a retried stream publishing from its first update again.
State the Python floor as the plugin's requires-python, lead the install
with the package alone and move the mcp extra to the MCP section, match
the middleware and approval prose to the samples (a Decision with the
request id, a validator that checks the input, a handler that checks the
state), explain add_temporal_spans=True and show the tracer provider
call, give the heartbeat numbers, and spell out identifier outside code.
Say that each published streaming batch is a Signal that counts toward
the 10,000 a Workflow Execution can receive, so a chat that streams has
to Continue-As-New sooner, and name that limit as the second
non-retryable StreamError case. Make the unknown-model-name failure per
Worker, add the MCP tool classes and the OpenTelemetry globals to the
limitations list, describe the lock, end_chat Signal and transcript
Query the continue-as-new snippet shows, and apply the wording nits:
run commands for hello world, exhausted MCP Activities, run-level tool
collisions, the MCPPlugin name clash, compaction, the OTLP endpoint
variable, and "Out of scope" as the label.
@vercel

vercel Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
temporal-documentation Ready Ready Preview Nov 15, 2026 5:05pm UTC

Request Review

@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Snipsync coverage

SDK code lines in docs/ that come from Snipsync: 58.3% → 58.2% (−0.1 pts), 23,698 of 40,687 lines.

Section Snipsync lines Inline lines Snipsync % Change
develop/python 5,146 535 → 542 90.6% → 90.5% −0.1 pts
All sections

All languages: 50.1% (24,523 of 48,936 lines).

Section Snipsync lines Inline lines Snipsync %
design-patterns 26 7,808 0.3%
develop/python 5,146 542 90.5%
develop/java 4,639 49 99.0%
guides 34 4,494 0.8%
develop/go 4,285 80 98.2%
develop/typescript 3,702 314 92.2%
develop/dotnet 2,374 0 100.0%
develop/rust 1,571 0 100.0%
develop/ruby 1,232 0 100.0%
develop/php 30 1,144 2.6%
develop 484 606 44.4%
production-deployment 116 746 13.5%
encyclopedia 0 837 0.0%
develop/worker-performance 48 177 21.3%
cloud 0 127 0.0%
references 0 48 0.0%
best-practices 11 17 39.3%
Language Snipsync lines Inline lines Snipsync %
Python 5,289 6,622 44.4%
Go 4,425 3,181 58.2%
Java 4,724 2,593 64.6%
TypeScript 3,869 2,778 58.2%
C# 2,449 457 84.3%
Rust 1,609 31 98.1%
Ruby 1,303 159 89.1%
PHP 30 1,168 2.5%
Snipsync origin Lines
temporalio/documentation-sdk-code-examples 19,666
temporalio/samples-python 2,266
temporalio/samples-typescript 693
temporalio/features 464
temporalio/samples-go 384
temporalio/samples-java 184
temporalio/samples-php 30
temporalio/reference-app-orders-go 11

Compared with 882a9de. Counts non-blank lines in fenced code blocks tagged with an SDK language. Hand-written code isn't compiled anywhere; code Snipsync pulls from a sample repository is built in that repository's CI. See UTILITIES.md.

@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

📖 Docs PR preview links

The short name is too generic: any vendor, Temporal included, could
publish an agent framework, so the integration takes the product's full
name. The plugin and the samples are renamed the same way, and the
page's slug, sidebar entry, grid href, install commands, imports, class,
error and Activity names and links follow them.
The plugin changed after the second review: a client with
streaming_topic now runs every call through the streaming Activity and
publishes on each one, batches cap at 256 updates, activity_as_tool
needs a timeout when the tool is built, a raising or wrong-type factory
fails the Activity once with a typed error, hosted MCP headers move to
the Worker through hosted_mcp_headers, sync tools run inline through a
rebound asyncio.to_thread, and Retry-After dates are parsed. Say each of
those, and add the loop settings, the unanswered-approval behavior, the
version-qualified MCP heartbeat sentence and the unregistered-server
case.
DABH added a commit to temporalio/ai-integrations that referenced this pull request Nov 13, 2026
The release-stage link pointed at a docs page that is not merged yet
(temporalio/documentation#5712). python/mcp uses the plain label for the
same reason.
The plugin changed after a maintainer review: the plugin goes on
Client.connect, because only a plugin on the Client sets the data
converter and provider imports must stay out of the sandboxed Workflow
file; TemporalChatClient sends store=False unless set; a factory that
raises is retried while None or a wrong type fails once; the stream
error type is MicrosoftAgentFrameworkStreamError; MCP tool names are
normalized as MCPTool does and temporalio-mcp is described at 0.3 only;
client_kwargs are recorded in Event History and credential headers are
refused; structured output sends the strict schema; prompts arriving
mid-run must be carried across Continue-As-New; Retry-After parses as
seconds or milliseconds, capped at 60 seconds; the seam error names the
tested range.
The plugin now requires temporalio-mcp 0.4, whose MCP Activities
heartbeat by default with a 10-second heartbeat timeout, so a cancel
reaches a running request and a lost Worker is noticed within seconds.
Replace the sentence that said the provider sets no heartbeat timeout
and that 0.3 does not heartbeat, name the heartbeat_timeout option on
TemporalMCPToolProvider (None turns heartbeats off), and name the 0.4
floor where the mcp extra is installed.
The plugin now defines its tested range as the floor it was first
tested on through the version its lock pins, which CI runs on every
change, so the range is 1.23.0 through 1.24.0; the runtime seam error
names that range. For a hosted MCP connector tool, the authorization
entry in hosted_mcp_headers goes to the tool's authorization field as
the bare token, with a leading "Bearer " dropped, because the Responses
API takes the bare token there.

This branch was successfully deployed

1 active deployment
Preview — a4b37ed1 Deployed Nov 15, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant