Python: docs: fix outdated @ai_function reference to @tool in workflows README - #5597
Conversation
The @ai_function decorator was renamed to @tool in v1.0.0b260128 (PR microsoft#3413). Updated the workflows README to use the correct @tool decorator name.
Evan Mattson (moonbox3)
added
documentation
github-actions
Bot
changed the title
There was a problem hiding this comment.
Pull request overview
Updates the workflows sample README to match the current Python tool API naming (@tool), preventing users from following outdated documentation after the breaking rename introduced in PR #3413.
Changes:
- Replaced the outdated
@ai_functionreference with@toolin the “Workflow as Agent kwargs” row. - Reformatted multiple sample tables for consistent Markdown table layout/alignment.
| | Sample | File | Concepts | | ||
| | ------------------------ | ---------------------------------------------------------------------------------- | -------------------------------------------------------------- | | ||
| | Basic Pipeline | [functional/basic_pipeline.py](./functional/basic_pipeline.py) | Sequential steps as plain async functions | | ||
| | Basic Streaming Pipeline | [functional/basic_streaming_pipeline.py](./functional/basic_streaming_pipeline.py) | Stream workflow events in real time with `run(stream=True)` | | ||
| | Parallel Pipeline | [functional/parallel_pipeline.py](./functional/parallel_pipeline.py) | Fan-out/fan-in with `asyncio.gather` | | ||
| | Steps and Checkpointing | [functional/steps_and_checkpointing.py](./functional/steps_and_checkpointing.py) | `@step` decorator for per-step checkpointing and observability | | ||
| | Human-in-the-Loop Review | [functional/hitl_review.py](./functional/hitl_review.py) | HITL with `ctx.request_info()` and replay | | ||
| | Agent Integration | [functional/agent_integration.py](./functional/agent_integration.py) | Calling agents inside workflow steps | | ||
| | Naive Group Chat | [functional/naive_group_chat.py](./functional/naive_group_chat.py) | Simple round-robin group chat as a plain loop | |
There was a problem hiding this comment.
The PR description says this is a single-line docs fix (line 58), but this commit also reformats multiple tables across the README. Consider either (a) limiting the change to the @tool rename to keep the PR focused, or (b) explicitly calling out the table reformatting in the PR description (or splitting it into a separate PR) to reduce review noise.
| | Sample | File | Concepts | | ||
| | -------------------------------- | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- | | ||
| | State with Agents | [state-management/state_with_agents.py](./state-management/state_with_agents.py) | Store in state once and later reuse across agents | | ||
| | Workflow Kwargs - Global Context | [state-management/workflow_kwargs_global.py](./state-management/workflow_kwargs_global.py) | Pass custom context (data, user tokens) via kwargs to `@tool` tools in all agents | | ||
| | Workflow Kwargs - Per Agent | [state-management/workflow_kwargs_per_agent.py](./state-management/workflow_kwargs_per_agent.py) | Pass custom context (data, user tokens) via kwargs to `@tool` tools in individual agents | |
There was a problem hiding this comment.
In the state-management table, the phrasing "@tool tools" is a bit redundant/ambiguous, especially now that the agents table uses "@tool functions". Consider rewording these rows to consistently refer to "@tool-decorated functions" (or similar) to avoid confusing readers about whether @tool applies to a function vs a tool object.
| | Sample | File | Concepts | | |
| | -------------------------------- | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- | | |
| | State with Agents | [state-management/state_with_agents.py](./state-management/state_with_agents.py) | Store in state once and later reuse across agents | | |
| | Workflow Kwargs - Global Context | [state-management/workflow_kwargs_global.py](./state-management/workflow_kwargs_global.py) | Pass custom context (data, user tokens) via kwargs to `@tool` tools in all agents | | |
| | Workflow Kwargs - Per Agent | [state-management/workflow_kwargs_per_agent.py](./state-management/workflow_kwargs_per_agent.py) | Pass custom context (data, user tokens) via kwargs to `@tool` tools in individual agents | | |
| | Sample | File | Concepts | | |
| | -------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ | | |
| | State with Agents | [state-management/state_with_agents.py](./state-management/state_with_agents.py) | Store in state once and later reuse across agents | | |
| | Workflow Kwargs - Global Context | [state-management/workflow_kwargs_global.py](./state-management/workflow_kwargs_global.py) | Pass custom context (data, user tokens) via kwargs to `@tool`-decorated functions in all agents | | |
| | Workflow Kwargs - Per Agent | [state-management/workflow_kwargs_per_agent.py](./state-management/workflow_kwargs_per_agent.py) | Pass custom context (data, user tokens) via kwargs to `@tool`-decorated functions in individual agents | |
|
@microsoft-github-policy-service agree |
Evan Mattson (moonbox3)
left a comment
Evan Mattson (moonbox3)
left a comment
There was a problem hiding this comment.
What is the actual change here? I see lots of table formatting changes (extra spaces?).
|
Hi Evan Mattson (@moonbox3) , the core fix is on line 58 — changing |
Yes, please, let's keep it scoped to the rename only with no unnecessary formatting/white space additions. |
|
Hi Evan Mattson (@moonbox3), apologies for the noise. I've created a new focused PR with only the single-line fix — no formatting or whitespace changes. 👉 Link to new PR Thanks for the feedback! |
The @ai_function decorator was renamed to tool in v1.0.0b260128 (PR #3413). Updated the workflows README to use the correct tool decorator name.
Motivation and Context
The
@ai_functiondecorator was renamed to@toolin release python-1.0.0b260128 (Jan 28, 2026) as a breaking change (PR #3413).However, line 58 of
python/samples/03-workflows/README.mdstill referenced the old@ai_functionname, causing users to follow outdated documentation and hitImportError: cannot import name 'AIFunction'.Additionally, the official Microsoft Learn docs at:
https://learn.microsoft.com/en-us/python/api/agent-framework-core/agent_framework.aifunction still show the old API — this is the primary source of user confusion.
Fixes #5564
Description
Changed
@ai_function toolsto@tool functionson line 58 ofpython/samples/03-workflows/README.mdin the agents table (Workflow as Agent kwargs row).Contribution Checklist
✅ The code builds clean without any errors or warnings — docs-only change, no build impact
✅ The PR follows the Contribution Guidelines
✅ All unit tests pass, and I have added new tests where possible — no tests needed for docs fix
❌ Is this a breaking change? — No, this is a docs fix only