---
title: "Agent Mentions"
description: "Tag custom agents, connected agents, and files in chat with @-mentions."
---

# Agent Mentions

Type `@` in the chat composer to mention custom agents, connected agents, files, and resources.

## Overview {#overview}

The `@`-mention system connects the chat composer to the broader agent ecosystem. When you type `@`, a popover appears listing available custom agents, connected agents, codebase files, and resources.

This is how you orchestrate multi-agent workflows from a single chat. Ask your local `@design` agent to critique a layout, `@analytics` to pull in the latest numbers from another app, and the main agent can incorporate both in one conversation.

## Mentioning agents {#mentioning-agents}

To mention an agent in the chat composer:

1. Type `@` to open the mention popover
2. Browse or search the list of available agents
3. Select an agent — it appears as a tag in your message
4. Send the message — the server resolves the mention and includes that agent's response in the conversation context

There are two agent paths:

- **Custom agents** — local agent-resource profiles in `agents/*.md`. These run inside the current app/runtime using the agent profile's instructions and optional model override.
- **Connected agents** — remote A2A peers. These are called over the [A2A protocol](/docs/a2a-protocol).

In both cases, your main agent sees the response and can reference or build on it.

<Diagram id="doc-block-1gv51ha" title="Where an @-mention routes" summary={"The server splits each mention by type: custom agents run locally, connected agents go over A2A — both responses fold back into the main agent's context."}>

```html
<div class="diagram-mention">
  <div class="diagram-node">
    @-mention<br /><small class="diagram-muted">in the composer</small>
  </div>
  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
  <div class="diagram-panel center" data-rough>
    <span class="diagram-pill accent">Server resolves</span
    ><small class="diagram-muted">extract refs by type</small>
  </div>
  <div class="diagram-col">
    <div class="row">
      <span class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</span>
      <div class="diagram-box">
        Custom agent<br /><small class="diagram-muted"
          >agents/*.md &middot; runs local</small
        >
      </div>
    </div>
    <div class="row">
      <span class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</span>
      <div class="diagram-box">
        Connected agent<br /><small class="diagram-muted"
          >A2A peer &middot; remote call</small
        >
      </div>
    </div>
  </div>
  <div class="diagram-arrow diagram-accent" aria-hidden="true">&rarr;</div>
  <div class="diagram-box diagram-accent">
    &lt;agent-response&gt;<br /><small class="diagram-muted"
      >injected into main agent</small
    >
  </div>
</div>
```

```css
.diagram-mention {
  display: flex;
  align-items: center;
  gap: 12px;
  flex-wrap: wrap;
}
.diagram-mention .center {
  display: flex;
  flex-direction: column;
  align-items: center;
  gap: 4px;
  padding: 14px;
}
.diagram-mention .diagram-col {
  display: flex;
  flex-direction: column;
  gap: 10px;
}
.diagram-mention .row {
  display: flex;
  align-items: center;
  gap: 8px;
}
.diagram-mention .diagram-arrow {
  font-size: 22px;
  line-height: 1;
}
```

</Diagram>

## Referencing files {#referencing-files}

The `@` popover is not limited to agents. You can also reference:

- **Codebase files** — type `@` and search for a filename. The file contents are included in the agent's context so it can read, analyze, or modify the file.
- **Agent resources** — reference files defined in the Resources tab. These can be data files, configuration, or any other structured content.

Selecting a file or resource resolves it into the agent's context when the message is sent, the same way an agent mention does.

Skills use a separate trigger: type `/` instead of `@` to reference a skill. Skills provide structured instructions that guide how the agent approaches a task — see [Skills Guide](/docs/skills-guide) for the full authoring format.

## For developers {#for-developers}

The rest of this page covers how mentions resolve on the server, how agents
become mentionable, and how to extend the mention system — useful if you're
building or configuring an app, not required to use `@`-mentions day to day.

### How it works {#how-it-works}

When a message containing an `@`-mention is sent, the following happens on the server:

1. The server extracts mention references from the message
2. For each mentioned agent:
   - custom agents run locally with their profile instructions
   - connected agents are called via A2A
3. The agent's response is wrapped in an `<agent-response>` XML block and injected into the conversation context
4. The main agent processes the enriched message, seeing both the user's text and the mentioned agent's response

What the main agent sees in its context:

```text
User: Draft an email with the latest signup numbers. @analytics

<agent-response agent="analytics">
Last week's signups: 1,247 total
  - Organic: 623
  - Paid: 412
  - Referral: 212
</agent-response>
```

The main agent can then use this data naturally in its response — for example, incorporating the numbers into an email draft.

<Callout id="doc-block-r8svs3" tone="info">

Mentioned-agent output arrives as an `<agent-response agent="…">` block in the **main agent's** context — not as separate chat bubbles. The main agent decides how to weave it into the reply.

</Callout>

### Adding agents {#adding-agents}

Agents become available for mentioning through several mechanisms:

- **Custom agents** — create agent profiles in the Resources tab as `agents/*.md`
- **Auto-discovery** — the framework automatically discovers connected agents running on known ports or configured URLs
- **Remote manifests** — add connected-agent manifests as `remote-agents/*.json`

#### Custom agents

Custom agents are Markdown files stored in agent resources:

```markdown
---
name: Design
description: Reviews layouts, product UX, and visual direction.
model: inherit
---

You are a focused design agent.
```

See [Agent Resources — Custom Agents](/docs/agent-resources#custom-agents) for the full format (including `tools`, `delegate-default`, and model overrides).

You can create them from the Resources tab using:

- `Create Agent` -> `Describe It`
- `Create Agent` -> `Fill Form`

#### Connected-agent manifests

Remote A2A agents still use JSON manifests. Only `name`, `url`, `description`,
and `color` are actually read — the manifest is discovery metadata, not an
auth or capability config:

```json
// remote-agents/analytics.json
{
  "name": "Analytics Agent",
  "url": "https://analytics.example.com",
  "description": "Runs analytics queries and returns data",
  "color": "#2563EB"
}
```

Outbound call-time authentication is resolved separately, not from this file
— see [A2A Protocol](/docs/a2a-protocol) for how server-side caller auth is
configured.

### Sub-agent selection {#sub-agent-selection}

The main agent can also use custom agents when spawning sub-agents with `agent-teams` (action: "spawn").

Pass the `agent` parameter to choose a profile from `agents/*.md`. That profile's instructions are added to the delegated run, and its `model` frontmatter can override the default model for that sub-agent.

### Extending mentions {#extending-mentions}

Templates can register custom mention providers to add domain-specific mentionable items beyond agents and files. A mention provider implements the `MentionProvider` interface: a `label` (the section heading shown in the `@` popover) plus a `search(query, event?)` function that returns up to a handful of `MentionProviderItem` matches (`id`, `label`, `description?`, `refType`, `refId?`, `refPath?`, `metadata?`).

<AnnotatedCode
  id="doc-block-159gm13"
  title="A custom MentionProvider"
  filename="server/mentions/contacts.ts"
  language="ts"
  code={
    'import type { MentionProvider } from "@agent-native/core/server";\nimport { like } from "drizzle-orm";\nimport { getDb, schema } from "../db/index.js";\n\nconst contactsProvider: MentionProvider = {\n  label: "Contacts",\n\n  // Runs as the user types after `@`. Return up to a handful of matches.\n  async search(query) {\n    const db = getDb();\n    const matches = await db\n      .select()\n      .from(schema.contacts)\n      .where(like(schema.contacts.name, `%${query}%`))\n      .limit(10);\n    return matches.map((c) => ({\n      id: c.id,\n      label: c.name,\n      description: c.email,\n      refType: "contact",\n      refId: c.id,\n    }));\n  },\n};'
  }
  annotations={[
    {
      lines: "5",
      label: "label",
      note: "The section heading shown in the `@` popover for this provider's matches.",
    },
    {
      lines: "8-18",
      label: "search",
      note: "Runs as the user types after `@`. Return matches as `MentionProviderItem`s — `id`, `label`, `description`, `refType`, `refId`.",
    },
  ]}
/>

Register providers in the agent-chat plugin configuration, keyed by provider id:

```ts
// server/plugins/agent-chat.ts
import { createAgentChatPlugin } from "@agent-native/core/server";

export default createAgentChatPlugin({
  actions: scriptRegistry,
  systemPrompt: "You are a helpful assistant...",
  mentionProviders: { contacts: contactsProvider },
});
```

Custom mention providers appear alongside the built-in agent and file providers in the mention popover. When the message is sent, a picked item is added to the agent's context as a compact reference line (`[contact] Jane Doe (id: ...)`), not a fully resolved document — put enough into `label`/`description` for the agent to act, or give it an action to look up the full record by `refId`.

## What's next {#whats-next}

- [**Using Your Agent**](/docs/using-your-agent) — where mentions fit in the day-to-day loop with the agent
- [**A2A Protocol**](/docs/a2a-protocol) — how connected-agent mentions are resolved over the wire
- [**Agent Teams**](/docs/agent-teams) — spawn sub-agents and pass the `agent` profile parameter
- [**Skills Guide**](/docs/skills-guide) — author the skills referenced with `/`
- [**Agent Resources**](/docs/agent-resources#custom-agents) — the full custom-agent profile format