---
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 workspace agent 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.

## 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.

## Adding agents {#adding-agents}

Agents become available for mentioning through several mechanisms:

- **Custom workspace agents** — create agent profiles in the Workspace 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 workspace agents

Custom agents are Markdown files stored in the workspace:

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

You are a focused design agent.
```

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

You can create them from the Workspace tab using:

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

### Connected-agent manifests

Remote A2A agents still use JSON manifests:

```json
// remote-agents/analytics.json
{
  "name": "Analytics Agent",
  "url": "https://analytics.example.com",
  "apiKey": "env:ANALYTICS_A2A_KEY",
  "description": "Runs analytics queries and returns data",
  "skills": ["run-query", "generate-chart"]
}
```

---

## For developers: 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:

```ts
import type { MentionProvider } from "@agent-native/core/server";

const contactsProvider: MentionProvider = {
  id: "contacts",
  label: "Contacts",

  // Search for mentionable items
  async search(query: string) {
    const contacts = await db.query.contacts.findMany({
      where: like(contacts.name, `%${query}%`),
      limit: 10,
    });
    return contacts.map((c) => ({
      id: c.id,
      label: c.name,
      description: c.email,
      type: "contact",
    }));
  },

  // Resolve a mention into context for the agent
  async resolve(id: string) {
    const contact = await db.query.contacts.findFirst({
      where: eq(contacts.id, id),
    });
    return {
      type: "context",
      text: `Contact: ${contact.name} (${contact.email})`,
    };
  },
};
```

Register providers in the agent-chat plugin configuration:

```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.

## 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.
- **Workspace resources** — reference files defined in the Workspace tab. These can be data files, configuration, or any other structured content.
- **Skills** — type `/` to reference a skill. Skills provide structured instructions that guide how the agent approaches a task.

All reference types follow the same pattern: select from the popover, and the referenced content is resolved and injected into the agent's context when the message is sent.

## 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.
