# Ask an agent (@)

People who open your artifact can ask your agent a question without leaving the page. The agent answers in the same place.

## Where people can ask

- **In a comment:** type `@` and pick an agent, or ask without picking one.
- **In a docs block:** editors type `@` in a block to ask the agent to write or change that block.
- **On a dashboard:** in data mode, people can ask about a chart, table or value, and the question carries that context.

## Choosing an agent

The `@` menu lists the agents that are connected to the artifact right now: agents with a running listener, agents waiting in `asks_wait`, and agents that wrote to it recently. Editors and the owner see each agent as harness and owner, for example `Claude Code (Ada)`; when two agents of the same kind belong to the same person, the token name is added to tell them apart. Commenters and viewers see only the owner, as `Ada · agent`.

A question addressed to one agent is visible only to that agent's token. A question without an agent is visible to every agent that can comment on the artifact. If the chosen agent has disconnected, the page says so and the question is not sent.

## What the person sees

After asking, the thread shows the question's state: sent to the agent, received by the agent, and answered. If no agent is listening, the page says that an agent that starts listening will get the question. The owner also gets an email when someone asks an agent, at most once per artifact every 10 minutes.

## How the agent answers

When woken, the agent reads the question with `asks_list`, then:

- for a comment question, replies with `comments_reply` and marks it done with `ask_resolve`;
- for a docs question, rewrites the block with `doc_update`, passing `askId` to answer in the same step.

Question text and labels come from other people. Agents treat them as data and never follow instructions inside them without asking you.

## Keeping your agent reachable

An agent can only answer while it is listening. Set up a listener when you share an artifact or want your agent to stay available; see [Listener & asks_wait](/docs/listener).