The Notion API can assign a Custom Agent to a people property
TL;DR
On November 9, 2026, a Notion API connection can assign a Custom Agent to a people property when it creates a page or updates page properties. The connection needs the View sessions and interact with agents capability, and the agent must be selected in the connection's Agent access tab. Assigning the agent can start a run. Page responses now include that agent as a bot user. A user mention of a Custom Agent still returns a validation_error, and List all users still omits Custom Agents.
- Status
- Live
- Released
- Plans
- Not specified
What changed
On November 9, 2026, Notion's developer changelog added Custom Agents to people page properties in the API.
You can assign a Custom Agent when you create a page or update page properties. Send the agent's bot user ID in the property's people array, the same shape the API already uses for a person. The people property reference says writes accept user IDs, including bots that appear as user objects.
Two conditions apply:
- The connection needs the View sessions and interact with agents capability. The capabilities reference lists people-property assignment under that capability, alongside querying agents and working with sessions.
- The agent must be selected in the connection's Agent access tab. A connection reaches only the Custom Agents selected there.
Assigning an agent can start a run, the same as assigning it in Notion. The changelog says "can." It does not say that every assignment starts a run, and it does not list the agent settings that decide.
Page responses now include assigned Custom Agents as bot user objects. Before this change, those agents were left out of people arrays. The user reference says a Custom Agent in that array has user type bot. A bot's avatar_url is now null when its icon is not an image URL. People values can be partial user objects, so a response may omit a name or email.
On update, an omitted property keeps its current value. A submitted people array replaces the whole value. Include every person and agent who should remain assigned.
What stays limited
A user rich text mention of a Custom Agent still returns a validation_error. The rich text reference says a user mention can name a person or a connection's bot, and that a Custom Agent mention is rejected. To hand work to an agent, assign it on a people property.
List all users does not include Custom Agents. Read an agent's bot user ID from a people property on a page where that agent is already assigned. When a page response omits a long people list, Retrieve a page property item returns a paginated list with one user in each item.
Other bots that Notion uses internally still cannot be assigned. The people-property reference says so. On June 10, 2026, the changelog named integrations used internally for database automations and Custom Agents as bots that did not appear as user objects, and said assigning one of those returned a validation_error. The November 9 change covers Custom Agents on people properties. User mentions of a Custom Agent stay rejected, and those other internal bots stay unassignable.
The November 9 changelog and the linked reference pages do not name a plan requirement.
This writes through the page endpoints. It is separate from the session routes in the Notion Agent APIs, from Notion MCP session tools, and from embedding a Custom Agent chat on a page.
Why it matters
A connection that creates or updates rows can put a Custom Agent in a people field, for example the assignee on a task. Notion says that assignment can start a run, the same way assigning the agent in Notion can.
The bot user ID has to come from a page where the agent is already assigned. List all users will not return it. The changelog does not describe a lookup for an agent that has never been assigned on a people property.
Because a people update replaces the whole array, a client that sends only the agent removes the other assignees.
Frequently asked questions
How do I assign a Custom Agent with the Notion API?
Set its bot user ID on a people property when you create a page or update page properties. The connection needs View sessions and interact with agents, and the agent must be selected in the connection's Agent access tab. Notion added this on November 9, 2026.
Does assigning a Custom Agent in the API start a run?
It can. Notion says assigning an agent can start a run, the same as assigning it in Notion. The changelog does not say that every assignment starts one, and it does not list the conditions.
How do I find a Custom Agent's bot user ID?
Read a people property on a page where that agent is already assigned. List all users does not include Custom Agents. The November 9 changelog does not name another way to look the ID up.
Can the Notion API mention a Custom Agent in page text?
A user rich text mention of a Custom Agent returns a validation_error. The rich text reference says to hand work to an agent by assigning it on a people property.
Which Notion plans include assigning a Custom Agent on a people property?
The November 9 changelog and the linked page-property, user, and capabilities pages do not say.
Sources
- Notion developer changelog: Custom Agents in people properties (Nov 9, 2026)
- Notion developer changelog: bots in people properties (June 10, 2026)
- Page property values: people
- Create a page
- Update page
- Connection capabilities: agent capabilities
- User object: bots
- Rich text: user mention
- List all users
- Retrieve a page property item