Mentions

Mentions let a user select a typed object—such as a file, knowledge base, or integration-provided business record—and send its stable reference with an agent turn. AgentFlow resolves that reference on the server and injects the result into hidden system_context; the visible user message remains unchanged.

From editor to agent context

Load the agent’s mention manifest with client.mention_types.agent_manifest(agent_id).
Search a manifest entry with search_for_agent(...). Agent-scoped search rejects mention types that are not assigned to that agent.
Submit the selected option as a ContextRef in RunOptions.context_refs.
AgentFlow hydrates the reference through its registered provider and persists the hidden context with the turn for replay.

from agentflow import ContextRef, RunOptions

manifest = await client.mention_types.agent_manifest(agent_id)
mention_type = manifest.mention_types[0]
options = await client.mention_types.search_for_agent(
    agent_id,
    mention_type.key,
    query="",
    limit=10,
)
selected = options[0]

result = await client.agents.run(
    agent_id=agent_id,
    message=f"Use {mention_type.trigger}{selected.name} as context for this request.",
    options=RunOptions(
        context_refs=[
            ContextRef(
                ref_system=mention_type.ref_config["system"],
                ref_type=mention_type.ref_config["type"],
                ref_id=selected.id,
                label=selected.name,
            )
        ]
    ),
)

Use the exact ContextRef shape returned by your application contract. Do not place provider credentials or a full provider record in the user message.

Catalog and custom mention types

/api/v1/mention-types exposes the tenant catalog, provider metadata, editor options, search, availability, and tenant-admin CRUD. System-managed mention types can be searched and assigned but cannot be edited or deleted. Custom mention types require a provider that advertises customer configuration support; AgentFlow validates the provider and source configuration before saving it. The supported triggers are @, #, and /, with @ as the default. Mention keys are stable identifiers and use lowercase letters, numbers, and underscores. The default icon is the canonical keyword-tag UI icon.

Data-object mentions

The data-object catalog describes provider objects and fields that are safe to expose in a mention editor. Use the preview endpoint before creating a data-object mention type. Preview validates the source configuration and returns sample options plus the context that would be injected, without creating the mention type. See SDK: Mentions and the Mentions API reference.

Getting Started

Core Concepts

Guides

From editor to agent context

Catalog and custom mention types

Data-object mentions

​From editor to agent context

​Catalog and custom mention types

​Data-object mentions

From editor to agent context

Catalog and custom mention types

Data-object mentions