# Agents

> Create a hosted agent in one call, give it your users' connections, and message it.

A hosted **agent** is a model with instructions and tools that NoClick runs for you. You message it, it works (calling tools, acting in your user's accounts), and it replies. Conversation history, tool execution, retries and billing are handled on NoClick's side.

## Create an agent

```python
import noclick

user = noclick.User.from_id("user_42", create_if_missing=True)
with noclick.as_user(user):
    gmail = noclick.Connection.from_name("gmail", integration="gmail", create_if_missing=True)
    stripe = noclick.Connection.from_name("stripe", integration="stripe", create_if_missing=True)

    support = noclick.Agent.from_name(
        "support",
        create_if_missing=True,
        instructions="You answer the user's billing questions. Look invoices up before answering.",
        tools=[gmail, stripe.only("list_invoices", "search_charges"), "search"],
        budget_usd_per_month=50,
    )
```

```ts
import { Agent, Connection, User, asUser } from "noclick";

const user = User.fromId("user_42", { createIfMissing: true });
await asUser(user, async () => {
  const gmail = Connection.fromName("gmail", { integration: "gmail", createIfMissing: true });
  const stripe = Connection.fromName("stripe", { integration: "stripe", createIfMissing: true });

  const support = Agent.fromName("support", {
    createIfMissing: true,
    instructions: "You answer the user's billing questions. Look invoices up before answering.",
    tools: [gmail, stripe.only("list_invoices", "search_charges"), "search"],
    budgetUsdPerMonth: 50,
  });
});
```

Inside `as_user` the agent and its connections are the [user](https://www.noclick.com/docs/guide/users.md)'s, whom `from_id` with `create_if_missing=True` creates the first time. `from_name` finds the agent by name and sets the fields you pass; with `create_if_missing=True` it creates the agent first if it's missing: see [What `from_name` sets](https://www.noclick.com/docs/guide/agents.md#what-from-name-sets). `noclick.Agent.create` always creates, and raises `noclick.Conflict` if the name is taken; with `allow_existing=True` it returns the agent already there instead, untouched. Names are unique for each user, and for your account.

- `instructions` is the system prompt, up to 64,000 characters.
- `harness` is what runs it: NoClick's own agent loop (`sdk`, the default) or a coding agent such as Claude Code. See [Harnesses](https://www.noclick.com/docs/guide/agents.md#harnesses).
- `model` is the harness's own model. On `sdk` it's an OpenRouter model id with an `openrouter/` prefix, like `openrouter/anthropic/claude-sonnet-4.5`. Leave it out for the harness's default.
- `tools` left out gives it everything in its scope (`"everything"`): every connection, ones connected later too, operations that need no account, `"search"`, `"fetch"` and NoClick itself, read at each of its turns, plus the account's owner to notify and ask for an account's agent. Its connections reach its model as `actions__find` and `actions__run`, and a connection it answers on (an event trigger's) gets its replying operations as tools of their own; each run is judged by [policy](https://www.noclick.com/docs/guide/policy.md) and logged as the operation it ran. A list narrows it to what it names:
- `tools` are [connections](https://www.noclick.com/docs/guide/connections.md) (a `Connection`, or its name: every operation), some operations of one (`stripe.only("list_invoices")`, or the string `"stripe.list_invoices"`), operations that need no account (`"exa.search"`), the capabilities `"search"` and `"fetch"`, a [toolkit](https://www.noclick.com/docs/guide/toolkits.md), or NoClick itself (`"noclick"`, see [Give it NoClick itself](https://www.noclick.com/docs/guide/agents.md#give-it-noclick-itself)). A lazy `create_if_missing` connection is created before the agent. Some tools come from elsewhere and are never listed: an [inbox](https://www.noclick.com/docs/guide/inboxes.md) gives the agent it names its `inbox__reply` tool, so `"inbox.reply"` in `tools` is left out, with a line in the result's `notes` saying so; a person to notify or ask is a `{"human": ..., "tools": [...]}` entry (see [Humans](https://www.noclick.com/docs/guide/humans.md)).
- `budget_usd_per_month` caps what the agent may spend in a month.
- `ttl_s` makes it temporary: that many seconds after it's created it expires, taking no more turns, and it's deleted 30 days later. See [Find your agents](https://www.noclick.com/docs/guide/agents.md#find-your-agents).
- `can_request` lets it ask the user for more connections as it goes: see [Asking for connections](https://www.noclick.com/docs/guide/grants.md).

A name in `tools` is a connection in the agent's scope, by the name it has: a WhatsApp connection named `home-whatsapp` is `"home-whatsapp"` or `"home-whatsapp.send_text_message"`, never `"whatsapp..."`, and one connected in the app is its id, `"credential:<id>"`. When no connection has that name, it's the integration of that name, limited to its operations that need no account. So `"exa.search"` gives any agent Exa's web search on NoClick's key, a user's agent included, with nothing to create or connect. `"exa"` gives it every Exa operation that needs no account. A connection named `exa` holding your own key takes over the same names: see [Operations on NoClick's key](https://www.noclick.com/docs/guide/integrations.md#operations-on-noclick-s-key).

A connection must exist when the agent names an operation that needs an account. Without one, creating the agent raises `noclick.InvalidRequest`, which tells you to create it. A lazy `Connection` in `tools`, like `stripe.only(...)` above, is created first; a name in a string is not.

An agent holds at most 64 tools. A small integration fits whole (Gmail has 28 operations), but a large one doesn't: Stripe alone has more than 400, so name the operations the agent needs.

Every agent can also run shell commands in a sandbox of its own, whether or not you list `code`. To take that away, deny `code` in your [policy](https://www.noclick.com/docs/guide/policy.md), or create the agent with `shell=False`: see [What it can reach](https://www.noclick.com/docs/guide/agents.md#what-it-can-reach).

## Harnesses

`harness=` picks what runs the agent. The default, `sdk`, is NoClick's own agent loop. The others are coding agents, each running in a sandbox of its own with its own shell and files, thinking with a model provider's key or plan that you hold in a [connection](https://www.noclick.com/docs/guide/connections.md#model-providers): the agent's `model_connection`.

| `harness=` | What runs it | `model=` | `model_connection` |
| --- | --- | --- | --- |
| `sdk` | NoClick's agent loop | An `openrouter/` id; with a connection, `anthropic/...` or `openai/...` on your key | Optional |
| `claude_code` | Claude Code | An alias (`sonnet`, `opus`, `haiku`) or a `claude-...` id | `anthropic` |
| `codex` | OpenAI's Codex | A Codex model, like `gpt-5.6-luna` or `gpt-5-codex` | `openai` |
| `opencode` | OpenCode | `provider/model`, like `opencode/big-pickle` | The model's provider; none for a free model of OpenCode Zen's |
| `hermes` | Hermes Agent | `provider/model`, a model that calls tools | The model's provider |
| `openclaw` | OpenClaw | `provider/model` | The model's provider |

`noclick.Agent.harnesses()` lists them with the version NoClick runs, each one's default model and the providers whose connection it can think with. A harness's [`models()`](https://www.noclick.com/docs/reference/python/Agent.md#HarnessInfo.models) searches the models it offers, by id or name; leave `model` out for the harness's default.

```python
opencode = noclick.Agent.harness_info("opencode")
print([m.id for m in opencode.models(search="claude")])   # ['opencode/claude-haiku-4-5', ...]
```

```ts
import { Agent } from "noclick";

const opencode = await Agent.harnessInfo("opencode");
console.log((await opencode.models({ search: "claude" })).map((m) => m.id));   // ['opencode/claude-haiku-4-5', ...]
```

One model is often reached several ways: OpenCode offers Claude Sonnet as `anthropic/claude-sonnet-5-5` on a Claude key, `openrouter/anthropic/claude-sonnet-5.5` on an OpenRouter key and `opencode/claude-sonnet-5-5` on an OpenCode Zen key. Each model says its `route` (`maker`, `openrouter`, `opencode` or `opencode-go`) and its `canonical`, the model as its maker names it, the same on every route to it; pick the id of the route whose key you hold.

On NoClick's key (an `sdk` agent with no `model_connection`, or `model_connection="noclick"` on Codex or OpenCode), a model whose output costs more than $2 per million tokens needs at least $5 of funds your account added: creating an agent on one, or switching an agent or a conversation to one, raises `noclick.PaymentRequired` until it has them, with links that add them. The plan's included usage doesn't count. Each model's `noclick_key` says what its output costs there and whether it needs them (`needs_funds_usd`). An agent already on such a model keeps running, as do the children it spawns on its own model, and your own key or plan is never held to it.

`noclick.Agent.harness_info(name)` is one of them by name; an unknown name raises `noclick.NotFound`, naming the ones there are.

An agent on Claude Code, with the Claude connection it thinks with:

```python
claude = noclick.Connection.from_name("claude", integration="anthropic", create_if_missing=True)
coder = noclick.Agent.from_name(
    "coder",
    create_if_missing=True,
    harness="claude_code",
    model="sonnet",
    model_connection=claude,
    instructions="You maintain our docs repo.",
    tools=["github", "search"],
)
if not claude.connected:
    print(claude.connect_url)   # where you paste a Claude key
reply = coder.message("Fix the broken links in README.md", conversation="docs-1")
```

```ts
import { Agent, Connection } from "noclick";

const claude = await Connection.fromName("claude", { integration: "anthropic", createIfMissing: true }).hydrate();
const coder = Agent.fromName("coder", {
  createIfMissing: true,
  harness: "claude_code",
  model: "sonnet",
  modelConnection: claude,
  instructions: "You maintain our docs repo.",
  tools: ["github", "search"],
});
if (!claude.connected) {
  console.log(claude.connectUrl);   // where you paste a Claude key
}
const reply = await coder.message("Fix the broken links in README.md", { conversation: "docs-1" });
```

Every harness but `sdk` needs a `model_connection`, a connection in the agent's own scope, except OpenCode on a free model of OpenCode Zen's (`opencode/...`), which it runs with no key. It may still be pending when you create the agent: until someone connects it, the agent's turns fail with `noclick.NeedsConnection`, which carries the link (a user messaging an account agent gets `noclick.NotAvailable`, with no link). Its link takes a key, or a Claude or ChatGPT plan signed in by the person it belongs to: a Claude plan runs only `claude_code`, a ChatGPT plan `codex`, `opencode`, `hermes` and `openclaw` ([model providers](https://www.noclick.com/docs/guide/connections.md#model-providers)). An account agent thinks with your account's connection, so it can run on your own plan, one you signed in to in the NoClick app included (`"credential:<id>"`, [accounts connected in the app](https://www.noclick.com/docs/guide/connections.md#accounts-connected-in-the-app)); inside `as_user`, the agent and its connection are the user's, and the user can connect their own plan. A plan suits an agent working for the person whose plan it is; [when a key fits better](https://www.noclick.com/docs/guide/connections.md#when-a-plan-fits).

To move an agent that's already running onto a key or plan someone has yet to connect, without stopping it meanwhile, create the connection (or its connect link) with `use_for`: `{agent, harness, model}`. The agent keeps running as it is until the person connects, then takes the connection as its `model_connection`, with that harness and model, as `PATCH /v1/agents/{id}` would set them (a plan connected where a key was asked for runs on the plan's own harness). The link's operation's result says what it set (`attached`) or why it couldn't (`attach_error`). A newer `use_for` link for the same agent closes its older ones nobody has connected through yet (on connections not connected), whatever the provider, so an old link finished late can't undo the switch: their operations end `canceled`, and the new answer names each in `replaced`. Links an agent's turn makes together (a Claude plan and a ChatGPT plan to choose from) are alternatives: they stay open side by side, and the first one connected closes the rest.

What changes on a harness other than `sdk`:

- **Its sandbox starts first.** A conversation's first turn starts the sandbox, which takes longer than a turn on `sdk`, and it stays warm for about a minute after each reply. While it starts, the turn's operation has `step` `"delivering"`, then `"working"`.
- **The reply arrives whole.** The harness doesn't stream its reply as it's written; the whole text comes when the turn ends.
- **Instructions set a conversation's start.** A conversation takes the agent's instructions at its first turn, so new instructions apply to conversations that start after the change.
- **It has its own shell, file editing and web.** Beside the tools you give it, it runs the harness's built-in commands inside its sandbox. The reply's `tool_calls` list them with `source: "harness"`. Your [policy](https://www.noclick.com/docs/guide/policy.md) judges the tools you give it, not these.
- **Its sandbox time is billed.** The model's tokens go to the connection's key or plan; NoClick bills the sandbox's running time: see [Spend](https://www.noclick.com/docs/guide/spend.md).
- **It doesn't take phone calls yet.** A [phone number](https://www.noclick.com/docs/guide/phone-numbers.md) answers with an `sdk` agent.

Changing `harness` moves each conversation to the new harness at its next turn, history included. A new harness without a `model` takes that harness's default model.

### Your account's key for a user's agent

> [!NOTE]
> Invite-only beta. [Request access](mailto:support@noclick.com?subject=Invite-only%20beta%20access) to use this section's API; without access, a call answers 404.

A user's agent can think with your account's model key instead of one of its own: pass your account's `Connection` object as `model_connection`, as you would to [share a connection](https://www.noclick.com/docs/guide/connections.md#share-one-across-users). The same rule applies: only a key acting for the whole account may set it, and it must hold a key, since a person's Claude or ChatGPT plan is never shared.

```python
claude = noclick.Connection.from_name("claude", integration="anthropic", create_if_missing=True)   # your account's key
with noclick.as_user("user_42"):
    coder = noclick.Agent.from_name(
        "coder",
        create_if_missing=True,
        harness="claude_code",
        model_connection=claude,
        instructions="You maintain the user's docs site.",
    )
```

```ts
import { Agent, Connection, asUser } from "noclick";

const claude = Connection.fromName("claude", { integration: "anthropic", createIfMissing: true });   // your account's key
await asUser("user_42", async () => {
  const coder = Agent.fromName("coder", {
    createIfMissing: true,
    harness: "claude_code",
    modelConnection: claude,
    instructions: "You maintain the user's docs site.",
  });
});
```

## Where it runs

`region=` picks the [region](https://www.noclick.com/docs/guide/regions.md) its sandboxes run in, for the agent's whole life: a coding harness runs there whole, and an `sdk` agent runs its shell there while its agent loop runs in NoClick's own service. Without it, a child takes its parent's region, else your account's default, else NoClick runs it wherever it has capacity (`region` is `None`). Put it beside its data with `region=db.region`.

```python
reviewer = noclick.Agent.from_name(
    "reviewer",
    create_if_missing=True,
    instructions="You review pull requests for our EU customers.",
    harness="codex",
    model_connection="openai",
    region="eu",
)
```

```ts
import { Agent } from "noclick";

const reviewer = Agent.fromName("reviewer", {
  createIfMissing: true,
  instructions: "You review pull requests for our EU customers.",
  harness: "codex",
  modelConnection: "openai",
  region: "eu",
});
```

An agent that should always be up, and answer the moment a message arrives, can run on a [machine](https://www.noclick.com/docs/guide/machines.md) instead: `machine=` puts its harness on an always-on machine at a flat monthly price, with no sandbox that sleeps.

## What `from_name` sets

Given fields, `from_name` does two things: it gets the agent, then sets the fields you pass, every time it runs. `create_if_missing` only decides what happens when there's no agent of that name: with `True` it's created from the fields, without it `noclick.NotFound` is raised. When an existing agent's instructions, harness, model, `model_connection`, tools, `tool_rules`, `can_request` or budget differ from what you pass, they're set to yours on first use, so `noclick.Agent.from_name("support", instructions="...")` changes the instructions of the agent that's there. Run new instructions and every user's agent picks them up the next time your code touches it. Connections a user [granted](https://www.noclick.com/docs/guide/grants.md) the agent at run time aren't fields you set, so a run never removes them. A field you leave out is never changed, and `None` clears `model_connection` or the budget: moving an agent back to `sdk` is `harness="sdk", model_connection=None`. `region`, `ttl_s` and `parent_id` are set when an agent is created and never change: passing another raises `noclick.Conflict` naming the field and the value the agent has.

Each run that passes fields is a write. Set them where your code starts, or in a setup script you run on deploy, and take the bare handle in request handlers:

```python
# setup.py, run on deploy
noclick.Agent.from_name(
    "support", create_if_missing=True, instructions="You answer questions about our product.", tools=["search"],
).hydrate()

# in a request handler
support = noclick.Agent.from_name("support")
reply = support.message("Where is my order?")
```

```ts
import { Agent } from "noclick";

// setup.ts, run on deploy
await Agent.fromName("support", {
  createIfMissing: true, instructions: "You answer questions about our product.", tools: ["search"],
}).hydrate();

// in a request handler
const support = Agent.fromName("support");
const reply = await support.message("Where is my order?");
```

Fields set in a handler are written on every request, and two versions of your server (during a rolling deploy, or staging and production on one account) would keep overwriting each other's values. To make an agent once and then leave it alone, so an edit someone makes in the app stays, use `Agent.create(..., allow_existing=True)`: it creates the agent the first time and returns it untouched after.

## Message it

```python
reply = support.message("Why was I charged twice in March?")
print(reply.text)
```

```ts
const reply = await support.message("Why was I charged twice in March?");
console.log(reply.text);
```

`message` sends the text and waits for the reply, an `noclick.AgentReply` with the reply `text`, the `conversation` it belongs to, and the `tool_calls` it made, each `{tool, arguments, result, is_error, created_at}` as [`history()`](https://www.noclick.com/docs/guide/agents.md#read-conversations) shows them. A message is at most 16,000 characters. A user's agent always acts for that user, wherever you call it from.

To keep talking in the same thread, pass the conversation back:

```python
follow_up = support.message("Can you refund one of them?", conversation=reply.conversation)
```

```ts
const followUp = await support.message("Can you refund one of them?", { conversation: reply.conversation });
```

Without a `conversation`, a message goes to the agent's [session](https://www.noclick.com/docs/guide/agents.md#one-session-clear-and-resume), the one conversation everyone talking to it shares. You can also choose the key yourself, for example your own ticket id: any 1 to 128 letters, digits and `. _ : @ + -`. A [channel](https://www.noclick.com/docs/guide/channels.md)'s conversation (`channel:<its id>`) is the one key you can't use: only the channel starts turns in it, under its stop rules, posting their replies to the room, so `message` and `wake` refuse it with `noclick.InvalidRequest`. Post in the channel instead.

Email, calls and your owner's texts can land in a conversation you name too, so one person reaches the agent in one thread whichever way they get in touch: `conversation=` on an [inbox](https://www.noclick.com/docs/guide/inboxes.md#choose-the-conversation), on a [number's](https://www.noclick.com/docs/guide/phone-numbers.md#choose-the-conversation) `answer_with`, and on [`Human.owner().answer_with`](https://www.noclick.com/docs/guide/humans.md#answer-the-owner-s-texts-and-calls-with-an-agent).

## One session: clear and resume

An agent is one session, like one terminal window running Claude Code: everyone who talks to it shares one conversation at a time, its session. A message without a `conversation` goes there, whether it comes from your code, a chat page or a teammate. A shared account agent keeps one session for your account and one for each of your users.

`clear()` starts a new session, as `/clear` does in a terminal, and everyone shares the new one from then on. The old one is kept: `conversations()` still lists it, and `resume()` makes it the session again, as `claude --resume` does. `session()` reads the one in use; in a listing, it's the one whose `active` is true.

```python
coder = noclick.Agent.from_name("coder")
coder.message("Fix the flaky retry test")          # goes to the session
before = coder.session()

coder.clear()                                      # a new session, for everyone
coder.message("Now look at the billing page")

coder.conversation(before.conversation).resume()   # back to the earlier one
```

```ts
import { Agent } from "noclick";

const coder = Agent.fromName("coder");
await coder.message("Fix the flaky retry test");          // goes to the session
const before = await coder.session();

await coder.clear();                                      // a new session, for everyone
await coder.message("Now look at the billing page");

await coder.conversation(before!.conversation).resume();  // back to the earlier one
```

Clearing and resuming only change which conversation is the session: the agent's files in `/workspace` stay as they are. Neither works while the agent is working on a turn: both raise `noclick.Conflict` naming the turn's operation, so wait for it or cancel it first. Resuming a conversation the agent never had raises `noclick.NotFound`. `start_conversation` clears too, with a key you choose. Over HTTP, `POST /v1/agents/{id}/conversations` clears and `POST /v1/agents/{id}/conversations/{conversation}/resume` resumes.

The agent takes one turn at a time, whichever conversation each is in: a message sent while it works waits and runs next ([Don't wait on the reply](https://www.noclick.com/docs/guide/agents.md#don-t-wait-on-the-reply)).

Its model, effort, speed and model connection are the agent's, and every conversation runs on them. Changing one in a conversation's settings (`coder.conversation("main").update(effort="high")`) changes the agent, for everyone. A conversation keeps its own title, archive and permission mode.

## Send it files

`files` sends documents, images, audio and video with a message, at most 10:

```python
analyst = noclick.Agent.from_name("analyst")
reply = analyst.message("What stands out this quarter?", files=["q3-report.pdf", "chart.png"])
```

```ts
import { readFile } from "node:fs/promises";
import { Agent } from "noclick";

// A string in `files` is an attachment's id, not a path: upload a local file first.
const analyst = Agent.fromName("analyst");
const report = await analyst.upload(await readFile("q3-report.pdf"), { name: "q3-report.pdf" });
const chart = await analyst.upload(await readFile("chart.png"), { name: "chart.png" });
const reply = await analyst.message("What stands out this quarter?", { files: [report, chart] });
```

A path is uploaded first. To send bytes, a file object or a recorded voice clip, `upload` it and send the attachment:

```python
analyst = noclick.Agent.from_name("analyst")
clip = analyst.upload(recording, name="question.webm", voice=True)
reply = analyst.message("Here's my question.", files=[clip])
```

```ts
import { Agent } from "noclick";

const analyst = Agent.fromName("analyst");
const clip = await analyst.upload(recording, { name: "question.webm", voice: true });
const reply = await analyst.message("Here's my question.", { files: [clip] });
```

The turn reads each file the way the agent reads one from any channel: a document's text, a voice clip's transcript (credit-gated, as reading media always is), an image as an image. Files are kept as your account's files, capped as those are (10 MB an image, 15 MB a document, 20 MB audio or video), and an upload is sent once, to the agent it was uploaded to. `history()` shows each message's `files`, and a [stream](https://www.noclick.com/docs/guide/sharing.md#stream-a-turn) shows them as `file` events. Over HTTP, `POST /v1/agents/{id}/attachments` takes the file's bytes, and the message sends its id in `attachments`.

Once sent, a file is one of your account's files, beside the images and videos you [made](https://www.noclick.com/docs/guide/ai.md) and your calls' recordings. `noclick.attachments()` lists them, newest first (`query` matches their names), and a message from the account sends any of them again:

```python
analyst = noclick.Agent.from_name("analyst")
[report] = noclick.attachments(query="q3")
reply = analyst.message("What changed since this report?", files=[report])
```

```ts
import { Agent, attachments } from "noclick";

const analyst = Agent.fromName("analyst");
const [report] = await attachments({ query: "q3" });
const reply = await analyst.message("What changed since this report?", { files: [report] });
```

They're the account's alone: a user's key can't list them or send them. `noclick.attachments_page()` reads them a page at a time, and `noclick.delete_attachment(file)` deletes one for good: a message that carried it keeps its name, and its link stops working. Over HTTP, `GET /v1/attachments` lists them (`cursor` for the next page), `DELETE /v1/attachments/{id}` deletes one, and a message sends their ids in `attachments` as it does an upload's.

## Don't wait on the reply

`send` starts the turn and returns an [operation](https://www.noclick.com/docs/guide/operations.md) at once, which suits web servers and job queues:

```python
turn = support.send("Summarize this customer's open tickets")
save(turn.id)

reply = noclick.Operation.from_id(turn.id).wait()   # later, anywhere: an AgentReply
```

```ts
import { Operation, type AgentReply } from "noclick";

const turn = await support.send("Summarize this customer's open tickets");
save(turn.id);

const reply = await Operation.fromId<AgentReply>(turn.id).wait();   // later, anywhere: an AgentReply
```

An agent takes one turn at a time, whichever conversation each is in. A message sent while it works on a turn waits for it and runs next, before the agent's next wake-up: its operation is `running` at step `waiting` until then. Nothing is refused for being busy. `delivery="steer"` puts a message into the running turn instead, when that turn is in the same conversation.

## How far a turn goes

An `sdk` agent's turn stops before it finishes at the first of its limits: $1 of model calls, 30 minutes, or 200 steps (model calls), which is a backstop: a call repeated with the same result, or a long run of calls that only read, is stopped well before it. A turn its spend or time limit ends makes one more call, without tools, that says what it did and what's left, and ends on a line saying why it stopped; `reply.ended_by` is `"steps"`, `"spend"` or `"time"` (`None` when the agent answered on its own).

A turn its steps end carries on by itself: it stops there without a closing call or a reply (its `reply.text` is empty), and a follow-up turn on the same conversation picks the work up straight away, up to 3 in a row, each paid and capped like any turn, with everything the turn before it read still in its context. With nothing left to do, the follow-up is told to end without a reply. A message to the conversation before it starts takes its place. A turn its spend or time limit ends waits to be asked: send "continue" to pick it up, except that a job your account's owner [texted the agent](https://www.noclick.com/docs/guide/humans.md#answer-the-owner-s-texts-and-calls-with-an-agent) carries on past its time limit too, since they wait on it with nothing on screen.

```python
builder = noclick.Agent.from_name("builder")
reply = builder.message("Build and ship a site for the bakery", conversation="bakery")
if reply.ended_by in ("spend", "time"):
    reply = builder.message("continue", conversation="bakery")
```

```ts
import { Agent } from "noclick";

const builder = Agent.fromName("builder");
let reply = await builder.message("Build and ship a site for the bakery", { conversation: "bakery" });
if (reply.endedBy === "spend" || reply.endedBy === "time") {
  reply = await builder.message("continue", { conversation: "bakery" });
}
```

A call the agent repeats with the same arguments and the same result is a loop: the third time, its result tells the agent so, and from then on that call isn't run again in the turn. A call whose result changes, like checking on an operation until it's done, never counts. A coding harness ends its own turns.

## Give a turn more room

`turn_limits` lets an agent that does long jobs go further in one turn, each limit left out at its default (at most 200 steps, $25 and 60 minutes); `None` goes back to the defaults. It's for `sdk` agents: a coding harness refuses it with `noclick.InvalidRequest`.

```python
builder = noclick.Agent.create(
    "builder",
    instructions="You build and ship the sites you're asked for.",
    tools=["noclick"],
    turn_limits={"steps": 100, "usd": 2},
)
```

```ts
import { Agent } from "noclick";

const builder = await Agent.create("builder", {
  instructions: "You build and ship the sites you're asked for.",
  tools: ["noclick"],
  turnLimits: { steps: 100, usd: 2 },
});
```

## Wake it up later

A **wake-up** gives one conversation a turn later: at a time, after a while, or when something finishes. The turn's message is your `note`, followed by what woke it.

```python
support = noclick.Agent.from_name("support")
support.wake("ticket-1841", after=3600, note="Check whether the refund has landed, then tell the customer.", user="user_42")

finance = noclick.Human(email="finance@acme.com").approve("Refund $95.00 to Ana Lima?")
support.wake("ticket-1841", when=finance, note="Finance answered about the refund. Tell the customer what they decided.",
             user="user_42")
```

```ts
import { Agent, Human } from "noclick";

const support = Agent.fromName("support");
await support.wake("ticket-1841", { afterS: 3600, note: "Check whether the refund has landed, then tell the customer.", user: "user_42" });

const finance = await new Human({ email: "finance@acme.com" }).approve("Refund $95.00 to Ana Lima?");
await support.wake("ticket-1841", {
  when: finance,
  note: "Finance answered about the refund. Tell the customer what they decided.",
  user: "user_42",
});
```

Give it exactly one of:

- `at`: a `datetime` with a timezone, from a minute to a year ahead.
- `after`: seconds, or a `timedelta`.
- `when`: an [operation](https://www.noclick.com/docs/guide/operations.md) (a person's answer, a connect link, a turn your code started with `send`, a purchase): it wakes the conversation once the operation finishes, with its outcome. One that has already finished wakes it at once.
- `every`: a `noclick.Cron`, for a routine: it wakes the conversation at each of the schedule's times, until you cancel it (below).

`when` can also be an [event type](https://www.noclick.com/docs/guide/webhooks.md#event-types) (`*` matches the rest of a name: `"connection.*"`), with `filters` naming fields its `data` must have: it wakes the conversation the first time a matching event happens after you set it (its turn starts within about half a minute, as any due wake-up's does), and the turn reads the event. A user's conversation hears that user's events; one of your account's own conversations hears every event, your users' included.

```python
with noclick.as_user("user_42"):
    assistant = noclick.Agent.from_name("assistant")
    assistant.wake("trip-planning", when="connection.connected", filters={"name": "calendar"},
                   note="The user connected their calendar. Book the flights now.")
```

```ts
import { Agent, asUser } from "noclick";

await asUser("user_42", async () => {
  const assistant = Agent.fromName("assistant");
  await assistant.wake("trip-planning", {
    when: "connection.connected",
    filters: { name: "calendar" },
    note: "The user connected their calendar. Book the flights now.",
  });
});
```

A **routine** is a wake-up that comes back. `every` takes a [`Cron`](https://www.noclick.com/docs/guide/triggers.md#run-on-a-schedule), read in its `tz`; `tz="user"` is the timezone of the user whose conversation it is, and follows them when they move. Unlike a schedule trigger, which starts a fresh conversation each time, a routine wakes the same conversation, so each turn reads what the last one did:

```python
coach = noclick.Agent.from_name("coach")
standup = coach.wake("standup", every=noclick.Cron("0 9 * * 1-5", tz="user"),
                     note="Ask how yesterday went and what's blocking today.", user="user_42")

standup.update(every=noclick.Cron("30 9 * * 1-5", tz="user"))   # half an hour later from now on
standup.cancel()
```

```ts
import { Agent, Cron } from "noclick";

const coach = Agent.fromName("coach");
const standup = await coach.wake("standup", {
  every: new Cron("0 9 * * 1-5", { tz: "user" }),
  note: "Ask how yesterday went and what's blocking today.",
  user: "user_42",
});

await standup.update({ every: new Cron("30 9 * * 1-5", { tz: "user" }) });   // half an hour later from now on
await standup.cancel();
```

A routine stays `pending` after each turn, its `at` the next time and `fired` counting the turns it started. Times it missed, while the conversation was busy or a turn couldn't run, fold into one turn rather than several. `update` changes a pending wake-up's `note` or its time (`at`, `after` or `every`); a turn about to start for what it said before doesn't start. A wake-up that's been delivered, canceled or failed raises `noclick.Conflict`.

`wake` returns a `noclick.Wakeup`, and `wakeups()` lists them. `user=` (or `as_user`) says whose thread the conversation is, as it does for `message`, and `user_filter=noclick.ALL_USERS` lists a shared agent's wake-ups across its users' threads, each with its `user_id`, as `conversations` does:

```python
support = noclick.Agent.from_name("support")
for wakeup in support.wakeups(conversation="ticket-1841", user="user_42"):
    print(wakeup.source, wakeup.status, wakeup.at, wakeup.note)
    if wakeup.status == "pending":
        wakeup.cancel()

for wakeup in support.wakeups(status="pending", user_filter=noclick.ALL_USERS):
    print(wakeup.user_id, wakeup.conversation, wakeup.at)   # cancel() acts in its own thread
```

```ts
import { ALL_USERS, Agent } from "noclick";

const support = Agent.fromName("support");
for (const wakeup of await support.wakeups({ conversation: "ticket-1841", user: "user_42" })) {
  console.log(wakeup.source, wakeup.status, wakeup.at, wakeup.note);
  if (wakeup.status === "pending") await wakeup.cancel();
}

for (const wakeup of await support.wakeups({ status: "pending", userFilter: ALL_USERS })) {
  console.log(wakeup.userId, wakeup.conversation, wakeup.at);   // cancel() acts in its own thread
}
```

A wake-up's `status` is `pending`, `delivered` (its turn started: `operation_id` is that turn), `canceled` or `failed` (`error` says why). Its `source` says who set it: `code` for `agent.wake` in your code, `wake_me` for the agent itself.

Every agent has a `wake_me(note, at, after_minutes, operation_id, operation_ids, every, conversation, quiet)` tool, so it can come back to something on its own: "check again in an hour", "carry on when this job finishes", "carry on once all three jobs finish", or "every Monday at 8, send me the week's numbers". `operation_ids` wakes it once, when the last of them finishes, told what each came to; a child's `done` update for one of those jobs comes in that turn rather than one of its own. One set on an `operation_id` also wakes it each time that operation stops to wait on a person (a build asking a question), with what it asks, so the agent can say what's needed; it still wakes when the operation ends. An operation's outcome reaches a conversation once: `wake_me` on one that already ended answers with its outcome and sets nothing, and a turn that reads the outcome itself takes the wake-up set on it there. `every` is a cron expression read in the agent's `timezone`, else its user's, else UTC, and so is `at` without an offset: the agent writes 9am there as `2026-10-24T09:00:00`, or as `09:00` alone for the next time it's 9am there, and the times it's told back are given there too. An `at` with an offset means what it says. With it come `list_wakeups`, the wake-ups pending in the conversation, and `cancel_wakeup`, and `wake_me` with a `wakeup_id` changes one (in whichever of its conversations it waits), so the agent keeps its own routines when the user asks it to. It changes and cancels only the ones your code or it set, never NoClick's. Your policy names all three `wake_me`, so `deny=["wake_me"]` keeps an agent from setting its own wake-ups. In a [channel](https://www.noclick.com/docs/guide/channels.md) the channel decides who takes a turn, so an agent has no `wake_me` there.

`quiet: true` makes a wake-up quiet, for work nobody is waiting on: its turn opens saying so, and nothing it replies reaches anyone. An agent that [answers the owner](https://www.noclick.com/docs/guide/humans.md#answer-the-owner-s-texts-and-calls-with-an-agent) keeps its check-ins quiet, and when there's news it tells them with `notify`, which joins their thread so their reply finds it. `conversation` sets a wake-up for another of the agent's own conversations instead of the one it's in, where its turn's reply goes; `list_wakeups` and `cancel_wakeup` take both. Every turn lands in the agent's one session, so the woken turn sees what came before it. It's always the same agent in the same thread (the account's, or the same user's), never a channel's, and a conversation with someone outside the agent's scope (a stranger's email, an app's visitor) keeps its wake-ups to itself:

```python
owner = noclick.Human.owner()
assistant = noclick.Agent.from_name("assistant", create_if_missing=True, tools=["search", owner], instructions=(
    "Once you finish something for the owner, set one quiet check-in a few hours later with wake_me. "
    "When it wakes you, tell the owner with human__notify only if there's news."))
owner.answer_with(assistant)

for wakeup in assistant.wakeups(conversation="background", status="pending"):
    print(wakeup.at, wakeup.note)   # its quiet check-ins, which wait in its quiet conversation, background
```

```ts
import { Agent, Human } from "noclick";

const owner = Human.owner();
const assistant = Agent.fromName("assistant", {
  createIfMissing: true, tools: ["search", owner],
  instructions: "Once you finish something for the owner, set one quiet check-in a few hours later with wake_me. "
    + "When it wakes you, tell the owner with human__notify only if there's news.",
});
await owner.answerWith(assistant);

for (const wakeup of await assistant.wakeups({ conversation: "background", status: "pending" })) {
  console.log(wakeup.at, wakeup.note);   // its quiet check-ins, which wait in its quiet conversation, background
}
```

How a wake-up is delivered:

- **On time, give or take half a minute.** A wake-up that comes due starts its turn within about 30 seconds.
- **Behind a running turn.** An agent takes one turn at a time, so a wake-up that comes due while a turn runs waits for it, then runs. It never fails with `Conflict`.
- **Once, and durably.** A wake-up survives restarts and deploys, and starts exactly one turn.
- **Billed like any turn.** Its turn counts toward the agent's budget, its user's cap and your account's funds. A one-off wake-up whose turn your account can't pay for fails instead of running; a routine misses that time and comes round at its next, its `missed` saying when and why (`credits`, `spend_cap` or `budget`).

An agent holds up to 100 pending wake-ups, 20 of them routines; one more raises `noclick.QuotaExceeded`. One conversation's wake-ups at a time start at least a minute apart (news, an operation it waited on or a child's update, comes as soon as the conversation is free), and a routine comes round at most once a minute (once every 15 minutes for one the agent sets itself, since each time is a billed turn); a schedule that comes round more often raises `noclick.InvalidRequest`. An agent that keeps waking itself, with no message or other turn in between, is refused the next wake-up once it has woken 10 times in a row, or 25 times in a row on work its own turns set going (a deploy, its check, a build): each of those ends when its operation does. The turn refused ends there, and an `sdk` agent's last words say where the work stands. Deleting an agent cancels its pending wake-ups.

NoClick wakes an agent itself too, listed beside yours with their own `source`: `update` (a child it spawned, reporting back: see [Coordinators](https://www.noclick.com/docs/guide/sub-agents.md#updates-wake-the-parent)), `answer` (a person it [asked something](https://www.noclick.com/docs/guide/humans.md#give-an-agent-a-person) answered, or didn't in time, or the link it asked its user to connect an account with is done, connected or expired: see [Grants](https://www.noclick.com/docs/guide/grants.md)) and `approval` (a person decided a call your [policy](https://www.noclick.com/docs/guide/policy.md) held: see [When a call waits for approval](https://www.noclick.com/docs/guide/agents.md#when-a-call-waits-for-approval)). None of them is set in a [channel](https://www.noclick.com/docs/guide/channels.md)'s conversation, whose turns the channel starts.

Your [webhooks](https://www.noclick.com/docs/guide/webhooks.md#event-types) hear `agent.wakeup.delivered` (its turn started), `agent.wakeup.missed` (a routine's time your account couldn't pay for, skipped) and `agent.wakeup.failed` (it couldn't run and won't come again: your account couldn't pay for a one-off, or the agent was gone).

## Whose accounts it acts in

An agent's connections belong to the same place the agent does. An agent created inside `as_user` belongs to that user and uses that user's connections. An agent created outside `as_user` belongs to your account and uses your account's connections: a support agent with your company's help desk, say. Those include the accounts you connected in the NoClick app, by their id (`"credential:<id>"` or `"credential:<id>.operation"`): see [Accounts connected in the app](https://www.noclick.com/docs/guide/connections.md#accounts-connected-in-the-app).

Every user can message an account agent, each in conversations of their own, but its tools always act in your account's accounts, never the user's. Look it up outside `as_user` and pass `user=` to `message`: inside `as_user`, `Agent.from_name` finds only the user's own agent by that name, never your account's. A user talking to it never gets a link to connect one of your account's connections: an unconnected one just tells the user that tool isn't available.

To act in each user's own accounts, give each user an agent of their own. It's the same code, run inside `as_user`:

```python
def assistant_for(user_id: str) -> noclick.Agent:
    with noclick.as_user(noclick.User.from_id(user_id, create_if_missing=True)):
        gmail = noclick.Connection.from_name("gmail", integration="gmail", create_if_missing=True)
        return noclick.Agent.from_name(
            "assistant",
            create_if_missing=True,
            instructions="You help the user with their email. Be brief.",
            tools=[gmail],
        )
```

```ts
import { Agent, Connection, User, asUser } from "noclick";

function assistantFor(userId: string): Promise<Agent> {
  return asUser(User.fromId(userId, { createIfMissing: true }), () => {
    const gmail = Connection.fromName("gmail", { integration: "gmail", createIfMissing: true });
    return Agent.fromName("assistant", {
      createIfMissing: true,
      instructions: "You help the user with their email. Be brief.",
      tools: [gmail],
    });
  });
}
```

`assistant_for` gets the user's agent and sets its fields each time it runs, so a user's agent takes new instructions the next time your code calls it for them. One your code hasn't called since, say a user whose scheduled turns run while they're away, keeps the instructions it had.

When a connection the agent uses has no account yet, its tools that need one answer with the connection's link and the agent passes it on in its reply; its operations on NoClick's key already work. The next message after the user connects works normally.

To add a connection from another scope beside its own, such as a company's shared Slack or your account's support mailbox, pass that `Connection` object in `tools`: see [Share one across users](https://www.noclick.com/docs/guide/connections.md#share-one-across-users).

## Read conversations

```python
for convo in support.conversations(limit=10):
    print(convo.conversation, convo.title, convo.turns, convo.cost_usd)

for message in support.history(reply.conversation):
    print(message.role, message.text)
    for call in message.tool_calls:
        print("  ", call["tool"], call["arguments"], call["is_error"])
```

```ts
for (const convo of await support.conversations({ limit: 10 })) {
  console.log(convo.conversation, convo.title, convo.turns, convo.costUsd);
}

for (const message of await support.history(reply.conversation!)) {
  console.log(message.role, message.text);
  for (const call of message.toolCalls) {
    console.log("  ", call.tool, call.arguments, call.is_error);
  }
}
```

`history()` reads the whole thread, oldest first. Over HTTP, `GET /v1/agents/{id}/conversations/{conversation}` with `limit` reads its newest `limit` messages, and passing the answer's `next_cursor` as `before` pages back through older ones.

Each message keeps the `files` it carried (a reply, the files its turn made and sent you) and, a reply, the `tool_calls` its turn made, each `{tool, arguments, result, is_error, created_at}` as the turn's `tool_call` and `tool_result` events showed it (a result is its preview, an error's is the error; arguments cut short are `{"_truncated": true}`), and the `reasoning` lines its model sent, each `{text, created_at}`, so a chat UI draws a reloaded thread the way it drew the live one.

A `user` message that didn't come through the API says how it came in `via`: `whatsapp` or `imessage` (a text to NoClick's number), `call` (said on a phone call) or `email` (mail to one of its [inboxes](https://www.noclick.com/docs/guide/inboxes.md)). It keeps what the person wrote; what the agent was told about answering in that app reached the model only. Its reply goes back the same way, so a chat UI can caption both.

A `user` message no person sent says what started its turn in `trigger`: `{kind, id, title}`, where `kind` is the [trigger](https://www.noclick.com/docs/guide/triggers.md)'s (`webhook`, `event`, `cron`, `platform` or `queue`) or `wakeup` for a [wake-up](https://www.noclick.com/docs/guide/agents.md#wake-it-up-later), `id` is the trigger's or the wake-up's, and `title` is what fired (an event's type, a wake-up's note). A NoClick event's (`platform`) also has its `event`, `{id, type, data}`. Its `text` is what the agent read (the trigger's message and the event), so a chat UI can show the turn by what happened (say, "A run of Daily digest failed", from the event's `data`) and its reply as the agent's own update, rather than as something the user said.

## Add a note to a conversation

`note` adds a line to a conversation without starting a turn: something your app wants the thread to show and the agent to know, like a plan change or a record the user just picked. It shows in `history()` and [`watch`](https://www.noclick.com/docs/guide/sharing.md#follow-a-conversation-live) as a `note` message with its `data`, and the agent reads both when its next turn starts, once. A `key` adds it once, so a retry never adds it twice:

```python
support = noclick.Agent.from_name("support")
added = support.note("ticket-1841", "Ada upgraded to the Pro plan.", data={"plan": "pro"}, key="ticket-1841:pro")
```

```ts
import { Agent } from "noclick";

const support = Agent.fromName("support");
const added = await support.note("ticket-1841", "Ada upgraded to the Pro plan.", { data: { plan: "pro" }, key: "ticket-1841:pro" });
```

`note` returns `False` when a note with that key was already there. A note is up to 4,000 characters, its `data` up to 4 KB of JSON. Inside `as_user` it goes to that user's conversation, as a message does. Over HTTP, `POST /v1/agents/{id}/conversations/{conversation}/notes` takes `{text, data, key}`.

A conversation's `status` is `active`, `awaiting_human` while a turn waits on a person (a question it asked, a call your policy held, a sign-in its browser needs), `handed_off` while a person has it (see [Give an agent a person](https://www.noclick.com/docs/guide/humans.md#give-an-agent-a-person)), or `taken_over` while your account's owner drives a coding agent's [terminal](https://www.noclick.com/docs/guide/agents.md#take-over-its-terminal). To follow one as it moves, whoever moves it, see [Follow a conversation live](https://www.noclick.com/docs/guide/sharing.md#follow-a-conversation-live).

## Watch what it did

Every turn is an operation. `operation.tool_calls()` lists the tools the turn called, with their arguments, results and timings, and `support.console_url` opens the agent in the developer console, with each conversation and turn.

## Take over its terminal

A coding agent on Claude Code, Codex, OpenCode, Hermes Agent or OpenClaw works in its harness's own session. `take_over` hands that session to a person: its harness's own terminal (Claude Code's, Codex's, OpenCode's, Hermes's or OpenClaw's), on the conversation the agent works in, to type into, approve and fix things by hand. Claude Code, Codex and Hermes stop while the person drives; OpenCode's and OpenClaw's terminals join the session the agent's harness runs. When they hand it back, what they said there joins the conversation's history, and the agent's next turn goes on from what they did. For how this compares with Claude Code on the web, Codex cloud and others, see [running Claude Code in the cloud](https://www.noclick.com/run-claude-code-in-the-cloud).

```python
coder = noclick.Agent.from_name("coder")
terminal = coder.take_over("main", interrupt=True, cols=120, rows=36)
send_to_browser(terminal.url, terminal.token)   # it opens it within two minutes
...
coder.terminal("main").hand_back()
```

```ts
import { Agent } from "noclick";

const coder = Agent.fromName("coder");
const terminal = await coder.takeOver("main", { interrupt: true, cols: term.cols, rows: term.rows });
const connection = terminal.connect({
  onData: (bytes) => term.write(bytes),
  onState: (status) => console.log(status.state, status.reason),
});
term.onData((text) => connection.write(text));
term.onResize(({ cols, rows }) => connection.resize(cols, rows));
// later
await terminal.handBack();
```

The turn the agent is on finishes first, unless `interrupt` stops it: its operation ends `canceled` with `error.reason` `taken_over`, which is neither a failure nor something to send again, so nothing reports or retries it. Messages that arrive meanwhile wait (their operations stay `running` at step `taken_over`, holding the conversation) and reach the agent once it's handed back, in order, including one that needs the agent's sandbox started again because its settings changed. A `Terminal`'s `state` is `agent`, `taking_over` (waiting for that turn), `person` or `handing_back`, and `take_over` again while it's taken over returns a new token, for a reload or a second tab. It hands itself back after `idle_limit_s` (15 minutes) with nobody typing, `detached_limit_s` (5 minutes) with no terminal open, when its program exits (Claude Code's `/exit`), and before `ends_at`, its sandbox's time limit; `ended_because` says which. Its time is the sandbox's, billed as the agent's sandbox time is, and the person's model calls are charged as the agent's own are (see [What you've spent](https://www.noclick.com/docs/guide/spend.md#see-what-you-ve-spent)).

A terminal shows its sandbox's keys and tokens (its model key through NoClick's proxy, its tools' token, its checkouts' keys), so only your account's owner opens one: signed in, or from your server with a secret key holding the `agents:terminal` scope, which `*` doesn't include. No user's session, app's code, agent or MCP connection can. Your server opens it and hands `url` and `token` to the browser of the person who'll drive it: the token opens it once, within two minutes, as the first message on the websocket (`{"type": "auth", "token", "cols", "rows"}`), never in its URL. Then binary messages carry what they type and what the terminal prints, `{"type": "resize", "cols", "rows"}` sizes it, and the socket closes with code 4410 once the agent has the conversation again. An open terminal ends as soon as what opened it no longer may: its key is revoked or expires, or its user isn't active (4401), the agent is deleted (4404), or that take-over is handed back, even when someone takes it over again right after (4410); a token from one take-over opens nothing in the next. A moment the check can't be made (NoClick's database didn't answer) keeps it open; only 30 seconds of nothing but those closes it, with code 1011, to be opened again. A client that says it renews (`"renew": true` in its first message, as the TypeScript SDK's `connect` does) lasts 15 minutes at a time: in the minute before, the server sends `{"type": "renew"}`, and an answer of `{"type": "renew", "token"}` with a new token for the same terminal (from `take_over` again) keeps it going unbroken; unanswered, it closes with code 4000 to be opened again. A client that doesn't say so has no such limit. It's there while the agent's sandbox runs (while it works, and for a minute after): with nothing running, `take_over` raises `noclick.Conflict` and the next message starts one. A coding agent editing an app in its live session is taken over in the app's live container, where its process runs: while it's taken over the session stays open (it never ends idle, and ending it raises `noclick.Conflict` with `reason` `taken_over` until it's handed back), and another conversation's message for that app waits for the hand-back too. A coding agent on a machine can't be taken over yet.

Over HTTP: `POST /v1/agents/{id}/conversations/{conversation}/terminal` takes `{interrupt, cols, rows}`, `GET` reads its state, and `DELETE` hands it back; the websocket is `/v1/terminals/attach`.

## Find your agents

Every agent says what it's doing: its `status`, when it was `last_active_at` (`None` if it never ran), how many `running_turns` it has, and its `child_count`, the live agents made under it with `parent_id` (or [spawned](https://www.noclick.com/docs/guide/sub-agents.md)). `Agent.list` filters on them. Inside `as_user`, an account agent's are `None` (its activity is other users' turns too), and the filters below never match it on them:

```python
from datetime import datetime, timedelta, timezone

for agent in noclick.Agent.list(status="working", order="last_active"):
    print(agent.name, agent.running_turns, agent.last_active_at)

week = datetime.now(timezone.utc) - timedelta(days=7)
quiet_coders = noclick.Agent.list(status="idle", active_since=week, harness="claude_code")
leftovers = noclick.Agent.list(temporary=True, status="expired")
```

```ts
import { Agent } from "noclick";

for (const agent of await Agent.list({ status: "working", order: "last_active" })) {
  console.log(agent.name, agent.runningTurns, agent.lastActiveAt);
}

const week = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);
const quietCoders = await Agent.list({ status: "idle", activeSince: week, harness: "claude_code" });
const leftovers = await Agent.list({ temporary: true, status: "expired" });
```

| `status` | Means |
| --- | --- |
| `working` | A turn is running, queued or waiting on a person (`running_turns` says how many). |
| `idle` | Nothing is running. |
| `expired` | It was temporary and its `ttl_s` ran out. It takes no turns, and its pending wake-ups are canceled, but you can still read it, its conversations and its jobs for 30 days, when it's deleted. |

A temporary agent used to be deleted the moment its `ttl_s` ran out. It now stays `expired` for those 30 days first, so you can still read what it did. Messaging or changing it raises `noclick.Expired`, and `delete()` removes it before then. Its name is free as soon as it expires: `from_name` with `create_if_missing=True` makes a new agent of that name rather than finding the expired one, and `Agent.list(name=...)` lists both.

`paused` isn't a status. [Pausing](https://www.noclick.com/docs/guide/triggers.md#pause-an-agent) stops an agent's triggers, not its work: a paused agent can be `working` on a message your code sent. Read `agent.paused` for that, and `agent.trigger_kinds` for what wakes it, without a read per agent (`"cron" in agent.trigger_kinds` is an automation).

Some of the agents listed are NoClick's helpers, made for its own work rather than by you: an app's coding agent, which NoClick makes the first time its assistant hands that app a change, and the children your NoClick assistant spawns. `agent.helper` is true for them, so a page that lists a person's agents can leave them out, as NoClick's own app does: their work shows where it happens instead.

Your NoClick assistant is listed too, and so is each space's own NoClick, which is found by the name `noclick-<the space's id>`. `agent.noclick` is true for them, and every read that lists agents says it: a channel's or a workspace's members and the agents' states carry `noclick` as well. NoClick's own app shows each one as NoClick, in its mark, never by that name, and never offers one where it offers your agents. A space's own NoClick answers only in its space's channels: a message sent straight to it raises `noclick.PermissionDenied`.

The filters are `status`, `active_since` (active at or after a time), `parent` (an agent's children; `agent.children()` is the same), `temporary` (made with `ttl_s`, or not) and `harness`. `order="last_active"` puts the most recently active first and those that never ran last; the default is the newest first. They're cheap on NoClick's side: `last_active_at` is stamped as turns start and end, running turns and live children are counted from indexes, and `status` follows from those, so a filtered listing costs no more than a plain one.

### What was added to it in the app

An agent runs on a workflow of its own (its `workflow_id`), which you can open and change in the NoClick app: a trigger wired in to wake it, a step it uses as a tool. `GET /v1/agents/{id}` names what was added there in `added_in_app`: each step's `id`, `name`, `type`, `operation` and `role` (`trigger`, `tool` or `step`), never what NoClick made for the agent itself. `GET /v1/workflows/{workflow_id}` reads that workflow in full (its `agent_id` names the agent), though it isn't listed among your workflows; it changes and runs as the agent, so changing, running or pausing it through `/v1/workflows` raises `noclick.PermissionDenied`. Inside `as_user`, an account agent has no `added_in_app` and its workflow doesn't read.

### Agents built in the app

The agents in your [workflows](https://www.noclick.com/docs/guide/workflows.md), built in the NoClick app, are your account's agents too. `Agent.list` gives them after the ones made through the API, with `origin` `app` (the others say `api`; `origin=` lists only one kind), and you message them the same way:

```python
for agent in noclick.Agent.list(origin="app"):
    print(agent.name, agent.workflow_name, agent.enabled, agent.app_url)

triage = noclick.Agent.list(origin="app", name="Triage")[0]
reply = triage.message("Anything urgent in the queue this morning?")
print(reply.text)
```

```ts
import { Agent } from "noclick";

for (const agent of await Agent.list({ origin: "app" })) {
  console.log(agent.name, agent.workflowName, agent.enabled, agent.appUrl);
}

const [triage] = await Agent.list({ origin: "app", name: "Triage" });
const reply = await triage.message("Anything urgent in the queue this morning?");
console.log(reply.text);
```

An app agent's id is `node:<workflow id>:<node id>`, and it carries its `workflow_id`, `node_id`, `workflow_name`, whether it's `enabled`, your `access` to its workflow (`owner`, or `editor` or `viewer` for one shared with you) and its `app_url`. A message runs a turn on the agent's own step, as a message from the app does, as an operation (`send`) or waited on (`message`), with files; `conversation=` continues a thread. A reply arrives whole, so `stream()` is refused. What the agent is (its instructions, model, tools, triggers) is changed in the app, where its conversations are read too: beyond reading it and messaging it, the API refuses it with a link to its workflow, and only `name` and `harness` filter the list down to it. A user's scope (`as_user`) never sees them, since they belong to the account, and only a workflow you own or edit takes messages. When one messages you with its `message_coordinator` tool, an `agent.asked_owner` [event](https://www.noclick.com/docs/guide/webhooks.md#event-types) carries it.

## Tell it the time

Every turn starts by telling the agent the current date and time, so "last month", "this Friday" and "yesterday's tickets" mean what they say. The time is in the agent's `timezone` (an IANA name) when it has one, else the acting user's [`timezone`](https://www.noclick.com/docs/guide/users.md), else UTC. It opens the turn's message as a line like "It is Thursday, 1 October 2026, 09:15 in Europe/London (UTC+01:00).", on every harness and every kind of turn (a message, a trigger, a wake-up, a channel or a call), and stays out of the conversation you read back.

```python
digest = noclick.Agent.from_name(
    "digest",
    create_if_missing=True,
    instructions="You summarize last week's support tickets every Monday.",
    timezone="Europe/London",
)
```

```ts
import { Agent } from "noclick";

const digest = Agent.fromName("digest", {
  createIfMissing: true,
  instructions: "You summarize last week's support tickets every Monday.",
  timezone: "Europe/London",
});
```

A schedule can follow the user too: `noclick.Cron("0 8 * * *", tz="user")` fires at 8:00 wherever the agent's user is ([Triggers](https://www.noclick.com/docs/guide/triggers.md#run-on-a-schedule)).

## Give it a repository

`repos=` clones repositories into the agent's workspace, `/workspace/<name>`, at its first turn, so a coding agent has the code in front of it:

```python
github = noclick.Connection.from_name("github", integration="github", create_if_missing=True)
fixer = noclick.Agent.from_name(
    "fixer",
    create_if_missing=True,
    harness="claude_code",
    model_connection="claude",
    instructions="You fix failing tests in acme/web. Push your fix to a branch named agent/<issue> and open a pull request.",
    tools=[github.only("create_pull_request")],
    repos=[github.checkout("acme/web", push=["agent/*"])],
)
```

```ts
import { Agent, Connection } from "noclick";

const github = Connection.fromName("github", { integration: "github", createIfMissing: true });
const fixer = Agent.fromName("fixer", {
  createIfMissing: true,
  harness: "claude_code",
  modelConnection: "claude",
  instructions: "You fix failing tests in acme/web. Push your fix to a branch named agent/<issue> and open a pull request.",
  tools: [github.only("create_pull_request")],
  repos: [github.checkout("acme/web", { push: ["agent/*"] })],
});
```

`connection.checkout(repository, branch=, path=, push=)` takes a repository a `github` [connection](https://www.noclick.com/docs/guide/connections.md) of the agent's own scope reaches; an agent takes up to 10, and none without a shell (`shell=False`). `path` names the folder (the repository's name by default) and `branch` the branch it starts on (its default branch). The connection may still be pending when you define the agent; a turn that would clone through it first raises `noclick.NeedsConnection` with its `connect_url`. One of your own [repos](https://www.noclick.com/docs/guide/repos.md) in the agent's scope is checked out with `repo.checkout(branch=, path=, push=)`, the same way.

The agent's `git` reaches those repositories only, through NoClick, with a key made for its sandbox and revoked when the sandbox ends; the connection's own token never enters the sandbox, so the model can't read it. `push` lists the branches it may push to, as globs; without it the checkout is read-only. NoClick judges every push on its way to GitHub and refuses one that touches any other ref (a tag, or `main` unless a glob names it), in git's own words (`! [remote rejected] main -> main (NoClick: this checkout may push only to agent/*)`). Whatever the globs allow, the agent can't force-push or delete the repository's default branch, and before a push rewrites or deletes any other branch NoClick keeps its old head for 30 days: on GitHub in the repository, as `refs/noclick/backups/<branch>/<time>`, and on one of your repos as a backup `repo.backups()` lists ([Branches and history](https://www.noclick.com/docs/guide/repos.md#branches-and-history)). This sits in git itself because a coding harness's own `git push` is a command in its shell, not a tool call your [policy](https://www.noclick.com/docs/guide/policy.md) could judge.

`gh` in the shell reads the same GitHub repositories through NoClick, and the agent is told how, and nothing more, since its writes could merge or move a branch past `push`. Opening a pull request or commenting is the connection's operation, `github.only("create_pull_request", ...)` in `tools`, which your policy judges like any other.

The clone lives in the agent's workspace, so the next turn finds it as it was left, with whatever wasn't pushed yet, whoever it answers and across a clear; a changed `repos` reaches the agent at its next turn, and a clone already in its workspace stays as it is.

## What it can reach

`shell=False` takes the shell away from an `sdk` agent altogether: it keeps only the tools you list, `code` among them is refused (`noclick.InvalidRequest`), and the children it spawns have none either. A coding harness refuses it with `noclick.InvalidRequest`, since the shell is the harness. `update(shell=True)` gives it back.

```python
faq = noclick.Agent.from_name(
    "faq", create_if_missing=True, instructions="You answer from our help center.", tools=["search"], shell=False,
)
```

```ts
import { Agent } from "noclick";

const faq = Agent.fromName("faq", {
  createIfMissing: true, instructions: "You answer from our help center.", tools: ["search"], shell: false,
});
```

`network` says where the agent's shell and code may connect: `True` (the default, anywhere), `False`, or a list of up to 50 hosts, with `*.example.com` for a domain and every name under it. Hosts are reached over HTTPS on port 443 only, as in a [sandbox's list](https://www.noclick.com/docs/guide/sandboxes.md#reach-only-some-hosts).

```python
analyst = noclick.Agent.from_name(
    "analyst",
    create_if_missing=True,
    instructions="You answer questions about our orders from the data in /data.",
    network=["pypi.org", "files.pythonhosted.org"],
)
```

```ts
import { Agent } from "noclick";

const analyst = Agent.fromName("analyst", {
  createIfMissing: true,
  instructions: "You answer questions about our orders from the data in /data.",
  network: ["pypi.org", "files.pythonhosted.org"],
});
```

What the agent needs to work stays reachable, and `False` leaves only that:

| Agent | Always reachable |
| --- | --- |
| `sdk` | NoClick's git proxy, when it has `repos`. Its model and its tools run on NoClick, not in its shell, so with no `repos` `False` is no network at all. |
| A coding harness | NoClick's API (its turns, and its tools, which it reaches there over MCP), NoClick's proxy for git and for its model on a Claude, ChatGPT or OpenRouter key, and on a plan its provider's own hosts: `api.anthropic.com` and `platform.claude.com` for a Claude plan, `chatgpt.com` and `auth.openai.com` for a ChatGPT plan. |

`network` limits its shell and code, not its tools: `fetch` still reads any page, so leave it out of `tools` to keep the agent off the web. On a limited network a coding harness on a key always reaches its model through NoClick's proxy, so the provider's API isn't open to its code; a key the proxy doesn't carry (anything but Claude, ChatGPT or OpenRouter) can't run on one yet. Where NoClick can't keep to a limited network, creating or updating the agent raises `noclick.NotAvailable` rather than widen it.

A change reaches the agent's next turn; a coding harness's sandbox restarts for it, as for any change to what it starts with. A child takes its parent's `network` unless it's created with its own, and the children an agent spawns always do. A reachable host is reachable with anyone's account, NoClick's own API included: `network` bounds where code connects, not as whom.

## App testing: a bigger computer when a task needs one

A coding agent can start your app and run its tests against a real database, the way a developer checks their work. We call that app testing. It needs a bigger computer than the agent's usual sandbox, so it's off until a task needs it, and the agent turns it on itself. The chat shows one quiet line when it does, with what it costs while it works:

> Atlas turned on app testing for this task · about $0.44/hour while it works

The agent's turn ends there, its computer restarts as the bigger one, and NoClick wakes it straight away to carry on where it left off. Its files and the conversation stay as they were; anything still running before the restart stops. When the tests are done it turns app testing off, and the chat says how long it ran and what that cost:

> Atlas turned app testing off · ran 18 min, $0.13

If the agent forgets, app testing goes off by itself once nothing has run on it for 5 minutes, and after 2 hours at the latest. It never goes off in the middle of a turn or under a test that's still running: off applies from the agent's next turn. The agent's budget and your spending cap count it like any of its work.

You choose how much the agent decides, in its profile in Work (its name opens it) or with `app_testing`:

- `"by_itself"` (the default): it turns app testing on when a task needs it and off once it's done, and says so in the chat.
- `"ask_first"`: it asks you in the chat each time, with the price. Allow turns it on for that task, Not now keeps it off (the agent checks what it can without running the app), and Allow from now on switches the agent to `"by_itself"`.
- `"never"`: it doesn't run the app or a database, and tells you which checks needed one. Setting `"never"` while app testing is on turns it off from the agent's next turn.

```python
coder = noclick.Agent.from_name(
    "checkout-tests",
    create_if_missing=True,
    instructions="Keep the checkout service's tests green.",
    harness="claude_code",
    model_connection="claude",
    app_testing="ask_first",
)
```

```ts
import { Agent } from "noclick";

const coder = Agent.fromName("checkout-tests", {
  createIfMissing: true,
  instructions: "Keep the checkout service's tests green.",
  harness: "claude_code",
  modelConnection: "claude",
  appTesting: "ask_first",
});
```

App testing is Docker in the agent's sandbox (a VM of the `"small"` size below), switched by the agent's own `app_testing` tool, and the agent's `app_testing_usd_per_hour` is what an hour of it costs where it runs. An agent with `docker=True` has Docker on all the time instead. On your own [machine](https://www.noclick.com/docs/guide/machines.md) the machine's Docker is already there, at no extra cost, and the machine has an `app_testing` of its own (`"ask_first"` unless you change it): the stricter of the agent's and the machine's holds, so the agent asks first when either says so and never runs containers when either says never. An `sdk` agent has no sandbox to run it in.

## Run Docker in its sandbox

A coding agent can run Docker, for a test suite that starts its database in a container (testcontainers), `docker compose up`, or an image it builds. `docker=True` runs its sandbox as a VM with dockerd running before its first turn, so `docker`, `docker compose` and testcontainers work as on any Linux machine, and it's told so with its other notes about where it works. `sandbox_size` is the VM: `"small"` (2 CPUs, 4 GB, the default), `"medium"` (4 CPUs, 8 GB) or `"large"` (8 CPUs, 16 GB).

```python
tester = noclick.Agent.from_name(
    "tester",
    create_if_missing=True,
    instructions="You run our backend's test suite and fix what fails.",
    harness="claude_code",
    model_connection="claude",
    docker=True,
    sandbox_size="medium",
)
```

```ts
import { Agent } from "noclick";

const tester = Agent.fromName("tester", {
  createIfMissing: true,
  instructions: "You run our backend's test suite and fix what fails.",
  harness: "claude_code",
  modelConnection: "claude",
  docker: true,
  sandboxSize: "medium",
});
```

A VM has exactly its size and keeps all of it, so it's billed at Modal's rate for its whole size while it's up (a sandbox without Docker reserves a little and grows as it works): `agent.sandbox().get()` shows its `usd_per_hour` while it runs. Between turns it's paused as any warm sandbox is, with its containers as they were, and it ends after its sandbox's hard cap or a change to what it starts with, taking its containers and images with it: keep what lasts in `/workspace`. On a limited `network`, pulling an image needs its registry's hosts listed (Docker Hub's are `registry-1.docker.io`, `auth.docker.io` and `production.cloudflare.docker.com`). `docker` and `sandbox_size` are for a coding harness's own sandbox: an `sdk` agent, or `sandbox_size` without `docker`, raises `noclick.InvalidRequest`, and so does `docker` on an agent on a [machine](https://www.noclick.com/docs/guide/machines.md), where Docker is the machine's to allow. A change reaches the agent's next turn and restarts a running sandbox; `docker=False` drops its size.

## Allow, ask first or turn off each app

`tool_rules` says what the agent may do with each app it reaches: `"allow"` runs a call, `"ask"` holds it for the owner's yes (an approval, as [When a call waits for approval](https://www.noclick.com/docs/guide/agents.md#when-a-call-waits-for-approval) describes) and `"off"` refuses it. A key is an app as `tools` names it (a connection's name, `"credential:<id>"`, an integration's, `"noclick"`, and the web's `"search"` and `"fetch"`), one action of it (`"work-gmail.delete_email_message"`; NoClick's actions are its groups, `"noclick.spend"`), or `"*"` for whatever the rest don't name. The most specific key that names a call decides it, and with none it's allowed.

```python
support = noclick.Agent.from_name("support")
support.update(tool_rules={"work-gmail.delete_email_message": "off", "stripe.create_refund": "ask"})
```

```ts
import { Agent } from "noclick";

const support = Agent.fromName("support");
await support.update({ toolRules: { "work-gmail.delete_email_message": "off", "stripe.create_refund": "ask" } });
```

An agent holding everything reaches every account connected later too. `"*": "off"` keeps it to the apps its rules turn on, so one connected later starts off:

```python
support.update(tool_rules={"*": "off", "work-gmail": "allow", "noclick": "allow", "search": "allow", "fetch": "allow"})
```

```ts
await support.update({ toolRules: { "*": "off", "work-gmail": "allow", noclick: "allow", search: "allow", fetch: "allow" } });
```

An action that's off isn't among what `actions__find` answers, and a run of it is refused before anything happens; an app that's off isn't listed at all. Reading never waits for a person, so `"noclick.read"` is allowed or off. A list of `tools` reaches only what it names, with or without rules. `agent.tool_access()` (`toolAccess()`) reads it all app by app: each connection of the agent's scope, NoClick and the web, whether it's on, each action with what the rules say of it, and how often each ran in the last 7 days. For an agent given a list, `listed` is true and `rules` are what the list amounts to. A child the agent spawns keeps its rules. Rules change from the next call. A rule turning `"noclick.spend"` or `"noclick.delete"` to `"allow"` also lets the agent's purchases or deletions through without asking, within your account's ceiling: it sets the agent's [`approvals`](https://www.noclick.com/docs/guide/policy.md#set-them-for-one-agent) for `purchase` or `delete`, and who may do that is decided as for `approvals`.

The rules are the owner's, set in the agent's Tools tab in Work: code or an assistant acting for them sets them only on their word. NoClick's own assistant changes another agent's rules, its who-to-answer entry or a trigger's settings only with `owner_asked`, the owner's words asking for it, quoted from what they wrote in that conversation: NoClick checks the quote (word for word, or nearly) and refuses the change without it. Your own changes, in Work or with your key, carry nothing. An agent whose send is `"ask"` doesn't need to ask the owner about it first, since the hold shows them the exact call and NoClick runs it once they approve. When it did ask first anyway, with a question that showed the exact words, and the owner answered with a plain yes (the card's approve button, or yes, send or ok with nothing else), the turn that answer starts sends those words once, to that conversation's own chat, with no second hold. Anything else is held as usual: a yes with a change, other words, another recipient, an attachment or any argument the question didn't show, or the same words again.

## See what its model used

An agent that thinks with your own key or plan (a `model_connection`) doesn't bill its model calls to you, so NoClick meters them for you instead. `reply.model_usage` holds the turn's `input_tokens` (`cached_tokens` of them read from the provider's cache), `output_tokens` and what they'd cost at the provider's list price in `usd`; `convo.model_usage` sums a conversation's turns, and a [streamed](https://www.noclick.com/docs/guide/sharing.md#stream-a-turn) turn's `done` event carries it too. It's `None` for an agent on NoClick's key, whose turns are billed as usual (`cost_usd`).

Where the numbers come from: an `sdk` agent's calls, as the provider reports them; a coding harness's calls, one by one where NoClick's model proxy carries them, else what the harness reports at the end of its turn (a Claude or ChatGPT plan, say), priced as if it ran on a key. Usage recorded after a turn settles isn't in that turn's `model_usage`, but is in the conversation's.

```python
reply = coder.message("Fix the broken links in README.md", conversation="docs-1")
print(reply.model_usage.input_tokens, reply.model_usage.usd)
```

```ts
const reply = await coder.message("Fix the broken links in README.md", { conversation: "docs-1" });
console.log(reply.modelUsage?.inputTokens, reply.modelUsage?.usd);
```

## Give it NoClick itself

`"noclick"` in `tools` gives an agent your account's API as tools: what a connected app gets on the [MCP server](https://www.noclick.com/docs/guide/mcp.md), `search`, `fetch`, `api_describe` and `api_call`, plus `quote`, `buy` and `delete`. It can create agents and resources, buy a phone number or a domain, deploy and read what happened, as your code would:

```python
ops = noclick.Agent.from_name(
    "ops",
    create_if_missing=True,
    instructions="You run our NoClick account: numbers, domains, agents and apps.",
    tools=["noclick"],
)
reply = ops.message("Get us a phone number in the 415 area code.")
```

```ts
import { Agent } from "noclick";

const ops = Agent.fromName("ops", {
  createIfMissing: true,
  instructions: "You run our NoClick account: numbers, domains, agents and apps.",
  tools: ["noclick"],
});
const reply = await ops.message("Get us a phone number in the 415 area code.");
```

Its calls act as the turn: the key that sent the message and the user it acts for, never more than that key may. A turn a [connected app](https://www.noclick.com/docs/guide/mcp.md) started (its message, or a trigger or wake-up it set) reaches only the capability groups the app was granted, and when the agent holds more, the app's messages go to conversations of its own, apart from the ones turns with more power read. A turn another agent started (its message, a child's task) reaches only what that agent's turn could, in the same way ([A coordinator](https://www.noclick.com/docs/guide/sub-agents.md#a-coordinator)). The rules that judge a connected app judge them:

- Deleting something the [trash](https://www.noclick.com/docs/guide/undo.md) keeps (an app, database, bucket, dict, queue, repo, volume, inbox or agent) moves it there at once, restorable for 30 days. A purchase, and a deletion that can't be undone (purging the trash, or deleting anything the trash doesn't keep), wait for your account's owner, who approves it from a link NoClick sends them, with its exact price, or with what goes with it. The turn waits on them as on any person it asked, and the call's outcome (run once approved, or declined) is the conversation's next turn. The model never approves anything itself. On your own turns, what that turn made (or a turn whose own wake-ups started it) is its to take back: deleting or pausing it waits for nobody, while what an earlier turn made waits for you as before, and canceling a call it holds for your yes (`delete` with the call's operation id) withdraws the ask, its link and card with it, so the turn no longer waits on it.
- A secret's value never comes from the conversation: the agent creates the secret by name, and a person types its value on NoClick ([Secrets](https://www.noclick.com/docs/guide/secrets.md)). Keys, policy and anything that reveals a secret stay with a person.
- A turn answering someone outside the agent's scope (an email to its inbox, a caller) asks a person before anything that acts outside your account.
- A long action, like a deploy, answers with its operation, and the agent calls `wake_me` with its id to take a turn when it ends, unless a turn there has already read its outcome through these tools.

`noclick.Platform.only(...)` narrows it. Capability groups (`read`, `build`, `deploy`, `spend`, `delete`) bound what kind of call it makes; API areas (a key's [scopes](https://www.noclick.com/docs/guide/keys.md), like `domains` or `phone`) bound which part of the API it reaches. `"admin"` is a group nothing holds unless it's named (`"noclick.admin"` beside `"noclick"`): it adds a few administrative calls and loosening what other agents may do, each off until your approval settings switch it ([Let an agent or a connected app administer](https://www.noclick.com/docs/guide/policy.md#let-an-agent-or-a-connected-app-administer)):

```python
registrar = noclick.Agent.from_name(
    "registrar",
    create_if_missing=True,
    instructions="You look after our domains and their DNS.",
    tools=[noclick.Platform.only("domains")],
)
```

```ts
import { Agent, Platform } from "noclick";

const registrar = Agent.fromName("registrar", {
  createIfMissing: true,
  instructions: "You look after our domains and their DNS.",
  tools: [Platform.only("domains")],
});
```

Without `spend` it isn't offered `quote` and `buy`, and without `delete` not `delete`. Your [policy](https://www.noclick.com/docs/guide/policy.md) names its tools `noclick.search` ... `noclick.delete`, so a rule can hold or forbid any of them. A purchase or a deletion that can't be undone waits for you unless the agent's own `approvals` let it through within your account's ceiling, as `approvals={"purchase": {"disposition": "allow", "under_usd": 20}}` does for purchases of $20 or less ([Set them for one agent](https://www.noclick.com/docs/guide/policy.md#set-them-for-one-agent)); a tool rule allowing `noclick.spend` sets that too. In a stream or a watch, a held purchase or deletion is an `approval` event and a long action an `operation` event ([Sharing and streaming](https://www.noclick.com/docs/guide/sharing.md#stream-a-turn)). It works in the agent's own conversations; in a [channel](https://www.noclick.com/docs/guide/channels.md) the room starts its turns, and it isn't offered there.

## When a call waits for approval

When your [policy](https://www.noclick.com/docs/guide/policy.md) holds a tool call for a person's approval, the turn tells the user it's waiting and the conversation carries on. Once the person decides, the conversation takes a turn on its own (a wake-up of source `approval`) with what came of it: approved, NoClick runs exactly the call that was held (an operation's, once) and the turn gets its result; declined, the turn has the decline and the approver's note, and the call never runs. A held shell command or other tool that isn't an operation the agent makes again itself, as the turn tells it. Its reply goes out wherever the conversation lives: the chat, or the email thread. A held call in a [channel](https://www.noclick.com/docs/guide/channels.md)'s conversation wakes nothing, since the channel starts its turns. `agent.triggers()` lists an `approval` trigger while your policy may hold one of its tools, and [`request.approve(note=...)`](https://www.noclick.com/docs/guide/humans.md#answer-from-your-own-code) answers one from your own code.

## Change or remove it

```python
support.update(instructions="...", tools=["stripe.list_invoices", "stripe.create_refund", gmail, "search"])
support.delete()
```

```ts
await support.update({ instructions: "...", tools: ["stripe.list_invoices", "stripe.create_refund", gmail, "search"] });
await support.delete();
```

Omitted fields stay as they are. Changes apply from the next turn.

### Rename it

```python
support.update(name="Billing desk")
print(support.former_names)   # ["support"]
```

```ts
await support.update({ name: "Billing desk" });
console.log(support.formerNames); // ["support"]
```

A name is unique among its scope's agents, as when you make one. The agent keeps its id, and its old name keeps reaching it: `agent:support` in a call, `Agent.from_name("support")`, `GET /v1/agents?name=support` and an `@support` mention in a channel all find it, and each answer that found it that way says its name now in `notes`. The old name stays reserved for it in `former_names`, so no other agent of its scope takes it, until the agent is deleted or you rename it back. Its channels call it by the new name, and its next turns are told it was renamed, so instructions or memories that still use the old name read as itself. A NoClick keeps its name.

## Triggers, memory, sharing and test runs

Wake an agent on a webhook or an app event, a Slack message or a failed payment, on a schedule as an automation, or for each message on a queue, without anyone messaging it: [Triggers and automations](https://www.noclick.com/docs/guide/triggers.md). Give its shell your API keys, `secrets=` on `create` and `from_name`: [Secrets](https://www.noclick.com/docs/guide/secrets.md#use-it-in-an-agent-s-shell). Rehearse it against a simulated world before it touches real accounts: [Test runs](https://www.noclick.com/docs/guide/testing.md). Give it a memory it keeps across conversations, read the checkpoint a long conversation keeps there, and put files in a conversation's workspace for it: [Memory and files](https://www.noclick.com/docs/guide/memory.md). Let it read memories other agents read too, `memories=[company]` on `create` and `from_name`: [Share a memory between agents](https://www.noclick.com/docs/guide/memory.md#share-a-memory-between-agents). Give its shell a folder every conversation shares, `volumes={"/data": vol}` on `create` and `from_name`: [Volumes](https://www.noclick.com/docs/guide/volumes.md#mount-it-in-an-agent). Keep its files in a bucket, a folder per user: [Storage](https://www.noclick.com/docs/guide/storage.md#use-it-from-an-app-or-an-agent). Share it at a public link, or stream its turns into your own UI and follow a conversation live: [Sharing and streaming](https://www.noclick.com/docs/guide/sharing.md). Let it notify or ask a person, or hand them the conversation, a `Human` in `tools`: [Give an agent a person](https://www.noclick.com/docs/guide/humans.md#give-an-agent-a-person). Let it browse with a person's logins, `"browser"` in `tools` and `browser_profile=` on `create`, `from_name` and `update`: [Give an agent a browser](https://www.noclick.com/docs/guide/browser.md#give-an-agent-a-browser). Ask it something without stopping it, `agent.ask(...)`: [Ask without stopping it](https://www.noclick.com/docs/guide/sub-agents.md#ask-without-stopping-it). Give it another user's connection, or your account's, beside its own, a `Connection` object in `tools`: [Share one across users](https://www.noclick.com/docs/guide/connections.md#share-one-across-users).

> [!NOTE]
> Invite-only beta. [Request access](mailto:support@noclick.com?subject=Invite-only%20beta%20access) to use what these pages describe; without access, a call answers 404, or `not_available`.

- Let it pay with a card: `card=` ([Cards](https://www.noclick.com/docs/guide/cards.md))
- Let it read and write a SQL database: a `Database` in `tools`, or `db.only("query")` ([Databases](https://www.noclick.com/docs/guide/databases.md#use-it-from-an-app-or-an-agent))
- See the inboxes whose mail wakes it: `agent.inboxes()` ([Inboxes](https://www.noclick.com/docs/guide/inboxes.md))

## Next

- Let an agent ask its user for the accounts it needs: [Asking for connections](https://www.noclick.com/docs/guide/grants.md)
- Let one agent hand work to others and hear back when it must (`"agents"` in its `tools` lets it spawn, message and keep track of them itself), give them budgets, or let other agents call yours: [Coordinators and sub-agents](https://www.noclick.com/docs/guide/sub-agents.md)
- Put agents, your user and outside agents in one room, and group rooms into workspaces: [Channels](https://www.noclick.com/docs/guide/channels.md), [Workspaces](https://www.noclick.com/docs/guide/workspaces.md)
- Give an agent an email address or a phone number: [Inboxes](https://www.noclick.com/docs/guide/inboxes.md), [Phone numbers](https://www.noclick.com/docs/guide/phone-numbers.md)
- Talk to an agent from any OpenAI client or chat UI, as the model `agent:support`: [Talk to your agents from any OpenAI client](https://www.noclick.com/docs/guide/ai.md#talk-to-your-agents-from-any-openai-client)
