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
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,
)Inside as_user the agent and its connections are the user'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. 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.
instructionsis the system prompt, up to 64,000 characters.harnessis what runs it: NoClick's own agent loop (sdk, the default) or a coding agent such as Claude Code. See Harnesses.modelis the harness's own model. Onsdkit's an OpenRouter model id with anopenrouter/prefix, likeopenrouter/anthropic/claude-sonnet-4.5. Leave it out for the harness's default.toolsleft 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 asactions__findandactions__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 and logged as the operation it ran. A list narrows it to what it names:toolsare connections (aConnection, 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, or NoClick itself ("noclick", see Give it NoClick itself). A lazycreate_if_missingconnection is created before the agent. Some tools come from elsewhere and are never listed: an inbox gives the agent it names itsinbox__replytool, so"inbox.reply"intoolsis left out, with a line in the result'snotessaying so; a person to notify or ask is a{"human": ..., "tools": [...]}entry (see Humans).budget_usd_per_monthcaps what the agent may spend in a month.ttl_smakes 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.can_requestlets it ask the user for more connections as it goes: see Asking for connections.
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.
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, or create the agent with shell=False: see 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: 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() searches the models it offers, by id or name; leave model out for the harness's default.
opencode = noclick.Agent.harness_info("opencode")
print([m.id for m in opencode.models(search="claude")]) # ['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:
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")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). 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); 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.
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 hasstep"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_callslist them withsource: "harness". Your policy 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.
- It doesn't take phone calls yet. A phone number answers with an
sdkagent.
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
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. 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.
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.",
)Where it runs
region= picks the region 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.
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",
)An agent that should always be up, and answer the moment a message arrives, can run on a machine 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 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:
# 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?")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
reply = support.message("Why was I charged twice in March?")
print(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() 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:
follow_up = support.message("Can you refund one of them?", conversation=reply.conversation)Without a conversation, a message goes to the agent's session, 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'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, on a number's answer_with, and on Human.owner().answer_with.
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.
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 oneClearing 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).
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:
analyst = noclick.Agent.from_name("analyst")
reply = analyst.message("What stands out this quarter?", files=["q3-report.pdf", "chart.png"])A path is uploaded first. To send bytes, a file object or a recorded voice clip, upload it and send the attachment:
analyst = noclick.Agent.from_name("analyst")
clip = analyst.upload(recording, name="question.webm", voice=True)
reply = 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 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 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:
analyst = noclick.Agent.from_name("analyst")
[report] = noclick.attachments(query="q3")
reply = 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. Over HTTP, GET /v1/attachments lists them, 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 at once, which suits web servers and job queues:
turn = support.send("Summarize this customer's open tickets")
save(turn.id)
reply = noclick.Operation.from_id(turn.id).wait() # later, anywhere: an AgentReplyAn 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 carries on past its time limit too, since they wait on it with nothing on screen.
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")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.
builder = noclick.Agent.create(
"builder",
instructions="You build and ship the sites you're asked for.",
tools=["noclick"],
turn_limits={"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.
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")Give it exactly one of:
at: adatetimewith a timezone, from a minute to a year ahead.after: seconds, or atimedelta.when: an operation (a person's answer, a connect link, a turn your code started withsend, a purchase): it wakes the conversation once the operation finishes, with its outcome. One that has already finished wakes it at once.every: anoclick.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 (* 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.
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.")A routine is a wake-up that comes back. every takes a Cron, 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:
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()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:
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 threadA 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 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 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:
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, backgroundHow 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
missedsaying when and why (credits,spend_caporbudget).
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), answer (a person it asked something 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) and approval (a person decided a call your policy held: see When a call waits for approval). None of them is set in a channel's conversation, whose turns the channel starts.
Your webhooks 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.
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:
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],
)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.
Read conversations
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"])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). 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's (webhook, event, cron, platform or queue) or wakeup for a wake-up, 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 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:
support = noclick.Agent.from_name("support")
added = 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), or taken_over while your account's owner drives a coding agent's terminal. To follow one as it moves, whoever moves it, see 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.
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()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).
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. 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/.
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). 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:
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")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 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.
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/ 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, 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:
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)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 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, 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.
digest = noclick.Agent.from_name(
"digest",
create_if_missing=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).
Give it a repository
repos= clones repositories into the agent's workspace, /workspace/, at its first turn, so a coding agent has the code in front of it:
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/*"])],
)connection.checkout(repository, branch=, path=, push=) takes a repository a github connection 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 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). 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 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.
faq = noclick.Agent.from_name(
"faq", create_if_missing=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.
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"],
)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.
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",
)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 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).
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",
)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, 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 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.
support = noclick.Agent.from_name("support")
support.update(tool_rules={"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:
support.update(tool_rules={"*": "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.
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 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.
reply = coder.message("Fix the broken links in README.md", conversation="docs-1")
print(reply.model_usage.input_tokens, reply.model_usage.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, 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:
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.")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 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). The rules that judge a connected app judge them:
- Deleting something the trash 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 (
deletewith 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). 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_mewith 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, like domains or phone) bound which part of the API it reaches:
registrar = noclick.Agent.from_name(
"registrar",
create_if_missing=True,
instructions="You look after our domains and their DNS.",
tools=[noclick.Platform.only("domains")],
)Without spend it isn't offered quote and buy, and without delete not delete. Your policy names its tools noclick.search ... noclick.delete, so a rule can hold or forbid any of them. 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). It works in the agent's own conversations; in a channel the room starts its turns, and it isn't offered there.
When a call waits for approval
When your policy 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'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=...) answers one from your own code.
Change or remove it
support.update(instructions="...", tools=["stripe.list_invoices", "stripe.create_refund", gmail, "search"])
support.delete()Omitted fields stay as they are. Changes apply from the next turn.
Rename it
support.update(name="Billing desk")
print(support.former_names) # ["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. Give its shell your API keys, secrets= on create and from_name: Secrets. Rehearse it against a simulated world before it touches real accounts: Test runs. 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. Let it read memories other agents read too, memories=[company] on create and from_name: Share a memory between agents. Give its shell a folder every conversation shares, volumes={"/data": vol} on create and from_name: Volumes. Keep its files in a bucket, a folder per user: Storage. Share it at a public link, or stream its turns into your own UI and follow a conversation live: Sharing and streaming. Let it notify or ask a person, or hand them the conversation, a Human in tools: 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. Ask it something without stopping it, agent.ask(...): 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.
- Let it pay with a card:
card=(Cards) - Let it read and write a SQL database: a
Databaseintools, ordb.only("query")(Databases) - See the inboxes whose mail wakes it:
agent.inboxes()(Inboxes)
Next
- Let an agent ask its user for the accounts it needs: Asking for connections
- Let one agent hand work to others and hear back when it must (
"agents"in itstoolslets it spawn, message and keep track of them itself), give them budgets, or let other agents call yours: Coordinators and sub-agents - Put agents, your user and outside agents in one room, and group rooms into workspaces: Channels, Workspaces
- Give an agent an email address or a phone number: Inboxes, Phone numbers
- Talk to an agent from any OpenAI client or chat UI, as the model
agent:support: Talk to your agents from any OpenAI client