---
title: "Using Your Agent"
description: "The day-to-day loop of working with the agent: it sees what you're looking at, you direct it, embed it, go UI-light, and co-edit alongside it."
---

# Using Your Agent

The defining idea behind agent-native is that the agent and the UI are **equal partners** — see [What Is Agent-Native?](/docs/what-is-agent-native) for the why. This section is about the other half of that promise: what it feels like to actually work with the agent once it's docked next to your app.

There's a simple through-line. The agent **sees** what you're looking at, you **direct** it toward what you want, you can **embed** it anywhere, you can go fully **UI-light** when that's the better fit, and you can **co-edit** the same documents at the same time. Each of those is a page in this section.

<Diagram id="doc-block-z4xjdy" title="The day-to-day loop" summary={"Five ways of working with a docked agent — each is a page in this section."}>

```html
<div class="diagram-loop">
  <div class="diagram-card">
    <strong>Sees</strong
    ><small class="diagram-muted">your view &amp; selection</small>
  </div>
  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
  <div class="diagram-card">
    <strong>Direct</strong
    ><small class="diagram-muted">@-mentions &amp; voice</small>
  </div>
  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
  <div class="diagram-card">
    <strong>Embed</strong><small class="diagram-muted">drop into any app</small>
  </div>
  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
  <div class="diagram-card">
    <strong>UI-light</strong
    ><small class="diagram-muted">chat is the product</small>
  </div>
  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
  <div class="diagram-card accent-card">
    <span class="diagram-pill accent">Co-edit</span
    ><small class="diagram-muted">live, side by side</small>
  </div>
</div>
```

```css
.diagram-loop {
  display: flex;
  align-items: stretch;
  gap: 10px;
  flex-wrap: wrap;
}
.diagram-loop .diagram-card {
  display: flex;
  flex-direction: column;
  gap: 6px;
  padding: 14px 16px;
  min-width: 130px;
  flex: 1;
}
.diagram-loop .diagram-arrow {
  align-self: center;
  font-size: 22px;
  line-height: 1;
}
```

</Diagram>

This is what it looks like in practice: your app on one side, the agent docked next to it on the other, seeing the same screen you do.

<WireframeBlock id="doc-block-usingagent1">
  <Screen
    surface="desktop"
    html={
      "<div style='min-height:520px;box-sizing:border-box;display:grid;grid-template-columns:1fr 300px;gap:16px;padding:24px'><main class='wf-card' style='display:flex;flex-direction:column;gap:10px'><div style='display:flex;align-items:center;gap:10px'><strong>Inbox</strong><span class='wf-pill'>12 unread</span></div><div class='wf-box'>Design review notes<br/><span class='wf-muted'>Ada Lovelace &middot; 9:14 AM</span></div><div class='wf-box' style='border-color:var(--wf-accent)'>Q3 renewal — action needed<br/><span class='wf-muted'>Selected &middot; 10:02 AM</span></div><div class='wf-box'>Weekly signups digest<br/><span class='wf-muted'>Automations &middot; 8:00 AM</span></div></main><aside class='wf-card' style='display:flex;flex-direction:column;gap:10px'><strong>Agent</strong><div class='wf-box' style='align-self:flex-end;max-width:85%'>Summarize this and draft a reply. <span class='wf-pill'>@analytics</span></div><div class='wf-box' style='max-width:90%;background:var(--wf-accent-soft)'>Ada wants to move the renewal call. Draft below — send it?</div><div style='flex:1'></div><div class='wf-card' style='padding:10px;display:flex;align-items:center;gap:8px'><span class='wf-muted' style='flex:1'>Message the agent...</span><button>Voice</button></div></aside></div>"
    }
  />
</WireframeBlock>

## It sees what you're looking at {#it-sees}

The agent isn't blind to your screen. Open an email and it knows which thread. Select a chart and it knows which chart. Highlight a paragraph and it can act on just that range. That shared awareness is what lets you say "reply to this" or "summarize the selection" without spelling out the context every time.

This works because the app quietly keeps track of what view you're on and what you've selected, and shares that with the agent as part of its context. The agent can also drive that same state back — opening a view, selecting a row — so you watch it work in the real UI rather than in a transcript.

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

**Shared awareness is two-way.** You and the agent both read and write `application_state`, so "reply to this" or "summarize the selection" just works — and when the agent navigates, the real UI moves with it.

</Callout>

## You direct it {#you-direct-it}

Most of the time you steer the agent by typing into the chat. Two things make that faster.

**Mentions.** Tag a custom agent, a connected agent, or a file with `@` to pull it into the conversation — "let `@analytics` pull last week's numbers, then draft the summary." Mentions are how you reach the right specialist or attach the right context without leaving the composer.

**Voice.** The composer has a microphone. Dictate a request instead of typing it, with provider options ranging from Builder's hosted transcription to bring-your-own-key to a browser fallback.

A few examples of what that looks like in practice:

| Type or say this                       | What happens                                                         |
| -------------------------------------- | -------------------------------------------------------------------- |
| "Summarize this" (with a row selected) | Acts on exactly what you have open or highlighted — no re-explaining |
| "@analytics pull last week's signups"  | Pulls in a specialist agent's answer before continuing your request  |
| Click the mic and talk                 | Your words become the prompt — no typing needed                      |
| "Reply to this and CC Ada"             | Drafts using the context it already has from what you're looking at  |

## You embed it {#you-embed-it}

The agent isn't a separate app you tab over to. Wherever you see a chat panel in an agent-native app, it can be docked next to any screen — toggle it open, and it's right there next to whatever you're working on. App builders can also wire a button to hand a specific task straight to the agent instead of building a one-off "AI" feature for it. If you're building the app rather than using it, see [Drop-in Agent](/docs/drop-in-agent) for the components that make this work.

## You can go UI-light {#ui-light}

Not every app needs a full dashboard. When the agent _is_ the product, you can skip most of the custom UI: open the app, ask for what you want, and let the agent do the rest. The agent still has its management surface — history, agent resources, settings — but the primary interaction is conversation rather than clicks.

## You co-edit with it {#you-co-edit}

When you and the agent are working on the same document, you don't take turns. With real-time collaboration, the agent's edits stream in alongside yours — live cursors, no overwrites — the same way a teammate's would. You can keep typing while it works, and it sees your changes as they happen.

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

- [**Context Awareness**](/docs/context-awareness) — the agent knows what you're looking at
- [**Agent Mentions**](/docs/agent-mentions) — direct it with `@`-mentions
- [**Voice Input**](/docs/voice-input) — direct it by speaking
- [**Drop-in Agent**](/docs/drop-in-agent) — embed it in any React app
- [**Native Chat UI**](/docs/native-chat-ui) — ask for a chart or table and get a real, interactive one in the reply
- [**Generative UI**](/docs/generative-ui) — ask for sliders, a calculator, or a picker and the agent builds it inline
- [**Automation-First Apps**](/docs/pure-agent-apps) — use no-browser apps for jobs, queues, scripts, and external agents
- [**Real-Time Collaboration**](/docs/real-time-collaboration) — co-edit the same document together
- [**Component API**](/docs/components) — the full building-block reference, for developers embedding the agent