Introduction

With the Notion API update on November 10, 2026, you can now mention a shared Custom Agent in rich text by agent ID or bot user ID, or assign it to a people property. Either operation may trigger an agent run.

At the time of the initial release (November 9), assignment required a bot user ID, and mentions in rich text returned a validation_error. This update removes these restrictions, making it easier to invoke Custom Agents from integrations.

📌 Who is affected

• Developers who want to invoke Custom Agents from Notion API integrations
• People who wrote code to work around the restrictions in place at the initial release (such as code to retrieve a bot user ID from a people property)
• Teams building task automation and workflows using Custom Agents

Overview of the changes

Changes

1. Shared Custom Agents can be mentioned and assigned (severity: high)

When reading, a bot user object is returned, and the two IDs are stored as follows:

💡 Tips
Mentions and assignments may start an agent run. When testing, it is safer to use a validation page or agent to ensure that no unintended runs occur.

2. Resolution of the initial release restrictions (severity: medium)

The description “Two limits apply” in the November 9 entry was rewritten, and the guidance on the workaround for retrieving the bot user ID from the people property was also removed.

3. Remaining restriction (severity: low)

The “List all users” endpoint continues to not return Custom Agents (“still omits Custom Agents”). The previously provided workaround guidance has been removed, and only the restriction is now described.

Impact and mitigation

Actions developers should take

1. Checking capability: Check whether the integration has the "View sessions and interact with agents" capability.
2. Reviewing the workaround: If the bot user ID was being extracted from the people property, consider revising the implementation to use the agent ID directly (this is the point marked with action_required in this change).
3. Updating the documentation – CLAUDE.md: Delete the statements "Rich text mentions are validation_error" and "The bot user ID is obtained from the people property," as they are now outdated.
4. Design that does not depend on List all users: Since Custom Agents do not appear in the list, manage agent IDs separately.
5. Checking for unintended execution: Since agent runs can start through mentions or assignments, be careful about automation chains and duplicate execution.

Code examples

Note: Since the input data does not include concrete request/response code, the following is aconceptual illustration of the specification described above. Check the actual payload structure in Notion's official documentation.

Bot user object when reading (example)

Operational rules: Before / After (for CLAUDE.md)

Before

After

Summary

• It is now possible to mention or assign a shared Custom Agent using either an agent ID or a bot user ID (requires the “View sessions and interact with agents” capability).
• Either mentioning or assigning may start an agent run.
• In the bot user object when reading, agent_id is the agent ID, and id is the bot user ID.
• The validation_error from the initial release and the restriction requiring a bot user ID have been resolved. If a workaround has already been implemented, consider reviewing it.
• Because List all users still does not return Custom Agents, manage the agent ID separately.