Agent

Create an agent (names are unique per account and user; a duplicate raises noclick.Conflict with existing_id).

harness is what runs it: "sdk" (the default), NoClick's own agent loop, or a coding agent in a sandbox of its own with a shell and files: "claude_code", "codex", "opencode", "hermes" or "openclaw" (Agent.harnesses() lists them). model is the harness's own: an OpenRouter id with the openrouter/ prefix on sdk, an alias such as "sonnet" on claude_code, a provider/model on opencode, hermes and openclaw; omitted, the harness's default. model_connection is the connection whose key or plan it thinks with (a Connection of a kind="model" integration such as anthropic, or its name, in the agent's own scope; a lazy create_if_missing one is created first): every CLI harness needs one, and it may still be pending. On sdk it's optional, and lets model name anthropic/... or openai/... on your own key. A Connection object from another scope, such as your account's key for a user's agent, stays that connection (invite-only beta): only a key acting for the whole account may set one, and it must hold a key, since a person's Claude or ChatGPT plan is never shared.

tools are connections (a Connection, or its name: every operation), one operation of one ("gmail.send_email_message"), the capabilities "search" and "fetch", a Toolkit, or a Database (its query, execute and schema, or db.only(...); invite-only beta), or a browser ("browser", or "browser.act" and the like; invite-only beta), or a person (a Human, or human.only(...): tools that notify them, ask them and wait for the answer, or hand them the conversation), or the agents capability ("agents", or noclick.Agents.only(...): tools to spawn, message, ask and keep track of other agents), or NoClick itself ("noclick", or noclick.Platform.only(...): your account's API as tools, a purchase or a deletion waiting for your approval): at most 64 tools in all. A string names a connection in the agent's own user (the account for an account agent, whose "credential:<id>" names an account connected in the NoClick app), else an integration's operations that need no account (on NoClick's key), so tools=["exa.search"] (or "exa", all of them) needs no connection. A Connection object from another scope, another user's or the account's, stays that connection (a key acting for the whole account only; invite-only beta). A lazy create_if_missing connection is created first. Every agent can also run shell commands (the code capability; a policy that denies code refuses them, and shell=False removes it). ttl_s makes it temporary: once that many seconds have passed it's expired, taking no turns (its pending wake-ups are canceled) and readable for 30 days, then deleted; parent_id (an Agent or id) makes it a child of that agent, its budget carved from the parent's, with nothing started (parent.spawn also starts a task); budget_usd_per_month caps its spend.

can_request lets it ask its user to connect accounts at run time (a request_connection tool): integration names, single "integration.operation"s, or "*". What the user connects is a grant (grants()), kept apart from this definition.

triggers wake it without a message: noclick.OnWebhook, OnEvent, OnPlatformEvent, Cron and OnQueue (see triggers()).

timezone (an IANA name) is the zone every turn is told the date and time in; without one, the acting user's timezone, else UTC.

region (noclick.regions()) is where its sandboxes run, for good: a coding harness runs there whole, and an sdk agent's shell does while its loop runs in NoClick's own service. Without one it takes its parent's, else your account's default region, else runs wherever NoClick has capacity. region=db.region keeps an agent beside its data. machine (a Machine or id; invite-only beta) runs its harness on an always-on machine instead: no sandbox per conversation, nothing reaped when it's quiet, no per-minute sandbox charge, and it runs in the machine's region. A coding harness there reaches its model only through NoClick's credential proxy, so its model_connection holds an Anthropic, OpenAI or OpenRouter key (a Claude or ChatGPT plan raises noclick.NotAvailable); a machine runs at most 50 agents.

volumes mounts Volumes (or their ids or names: its user's own, then the account's) read-write in its shell at absolute paths ({"/data": vol}), in every conversation, up to 5; not at /workspace, /root or a system folder. An sdk agent's shell sees each as it was when the turn started and saves its writes when the turn ends; a coding harness's sandbox, from when it starts until it stops.

memories are the Memorys it reads besides its own (agent.memory), in order, up to 10: a Memory, its id or name (its user's own, then the account's), or another agent's memory. Each is read-only to it unless given as memory.writable(); a user's agent reads the account's memories but never writes them, and never another user's. Every turn starts with each entry's name and description, its own memory's first.

repos clones repositories into its workspace, /workspace/<name>, at a conversation's first turn: connection.checkout(...) for one a github connection of its own scope reaches, up to 10 (none with shell=False). Its git reaches those repositories only, through NoClick, with a key made for its sandbox; the connection's token never enters it. A push goes through only to the branches the checkout's push globs name (none: read-only): NoClick judges each push on its way to the git host, because a harness's own git push is no tool call your policy could judge. gh only reads them there; pull requests and issues are the connection's operations, in tools. repo.checkout(...), for a NoClick Repo, is in invite-only beta.

secrets (Secrets, ids or names; up to 20) become environment variables in its shell on every turn, a later secret's key winning a clash (a change reaches its next turn): its user's and the account's, an account agent's the account's only. Its shell takes no model provider's key (OPENAI_API_KEY and the like belong on model_connection): a secret holding one raises noclick.InvalidRequest.

shell=False takes the shell (the code capability) away from an sdk agent, and from the children it spawns; a CLI harness refuses it with noclick.InvalidRequest, since its shell is the harness.

network says what its shell and code may reach: True (the default: anywhere), False, or up to 50 hosts ("pypi.org", or "*.example.com" for a domain and its subdomains), over HTTPS on port 443 only. What it needs to work stays reachable, and False leaves only that: an sdk agent's shell reaches NoClick's git proxy when it has repos (its model and tools run on NoClick); a coding harness reaches NoClick's API, NoClick's proxy for its model on a key and for git, and on a Claude or ChatGPT plan that provider's own hosts. Its tools run on NoClick, outside the limit. Without one it takes its parent's, else anywhere, and the children it spawns take its. Where NoClick can't keep to a limited network (a coding harness on a key other than Anthropic, OpenAI or OpenRouter, say), it raises noclick.NotAvailable rather than widen it.

Invite-only beta: browser_profile (a BrowserProfile or id of its own user's, or your account's for an account agent) signs its browser tool in with that person's logins: each conversation gets a browser of its own for a turn, a step only a person can do holds the turn awaiting_human, and its calls follow policy as browser.*. card (a Card or id of its own scope: a user's agent pays with that user's cards, an account agent with your account's; giving one takes the key's cards scope) is what it pays with: it holds the card (a card has one agent at a time) and gets the tools card__status (what it can spend now) and card__purchase (approve before paying: above the card's threshold the turn waits for a person, and their answer is its next turn), which policy names card.status and card.purchase. It never sees the number, and a turn answering someone outside its scope, or a test run, can't buy anything. A child it spawns pays with the same card only when given "card" (or one of the tools) in its tools.

A lazy reference to the agent called name in the current (or given) user: inside as_user only that user's own agent, never an account agent of the same name (reach one of those outside as_user, then message it for the user). With create_if_missing=True your code is the definition: it's created on first use with the fields Agent.create takes, and an existing agent whose instructions, model, harness, model_connection, tools, can_request, budget, timezone, volumes, memories, secrets, repos, network or shell differ is updated to match (the grants its user gave it are kept; a new harness without a model takes that harness's default model, and its conversations carry on on the new harness). So are its triggers: a trigger your code no longer lists is removed and a new one added, while one that stays keeps its webhook URL; mail and call triggers are never touched. So are its browser_profile and card (invite-only beta). A field you leave out is never changed, and None clears model_connection, budget_usd_per_month, browser_profile, card or timezone, as in update(): moving an agent back to sdk takes harness="sdk", model_connection=None. region is fixed once it's created: an existing agent in another region raises noclick.Conflict naming its region.

A lazy reference to an agent by NoClick id.

Load an agent by NoClick id now; an unknown id raises noclick.NotFound.

The agents the current user can message: inside as_user, that user's own agents and the account's (which the user can message but not change; their user_id is None), so a name may match one of each; outside it, the account's. user_filter lists exactly whose agents instead: a User or your id for one (only theirs), noclick.NO_USER (the account's) or noclick.ALL_USERS.

After the account's API agents come the ones built in the NoClick app, which are the account's too (origin="api" or "app" lists only one kind). Of the filters below, only name and harness apply to them; the others leave them out.

Expired agents are listed for the 30 days they're kept. status keeps the working, idle or expired ones; active_since (an aware datetime) those with a turn since then; parent (an Agent or id) its children; temporary those with (or, False, without) a ttl_s; harness those on one harness; and order="last_active" puts the most recently active first, those that never ran last ("created", the default, the newest first). These reads are cheap: last_active_at is a column stamped as turns start and end, and the counts read partial indexes.

One page of agents; pass next_cursor back as cursor. Takes list's filters and order.

What can run an agent: sdk, NoClick's own agent loop, and the coding agents that each run in a sandbox of their own (claude_code, codex, opencode, hermes, openclaw). On a CLI harness a reply arrives whole rather than streaming, a conversation's first turn starts its sandbox (it stays warm about a minute between turns), and the sandbox's uptime is billed.

One of harnesses() by the name harness= takes; an unknown name raises noclick.NotFound, naming the ones there are.

Store a file (a path, bytes or a binary file object) to send this agent with a message. It's kept as an account file, capped as those are: 10 MB an image (JPEG, PNG, WebP or GIF), 15 MB a document, 20 MB audio or video. voice=True marks a recorded clip (audio), which may carry its waveform peaks. message(files=[...]) uploads paths for you; upload first to send bytes or a file object you name, or a voice clip.

Start a turn without waiting; .wait() returns the AgentReply. files go with the message, as message sends them.

Send text and wait for the reply. Pass the reply's conversation back to continue the same thread. A channel's conversation (channel:<its id>) raises noclick.InvalidRequest: only the channel starts turns there, so post in the channel instead. files (at most 100) are paths, which are uploaded first, attachments from upload, or (for the account) its files from noclick.attachments(): the turn reads them as the agent's media digest does, a document's text, a voice clip's transcript, an image as an image.

The messages of one conversation, oldest first.

Add a line to a conversation without starting a turn: it shows in history and watch as a note with its data, and the agent reads both when its next turn starts, once.

Args: conversation: The current user's conversation (the account's, outside as_user). text: The line, 1-4,000 characters. data: JSON your app reads back with it (at most 4,096 bytes). key: Adds it once: a second note with the same key adds nothing.

Its conversations, most recent first (the current user's, or those user_filter covers). user_filter reads across users without the user header, which only the signed-in owner may do on a user's own agent; with a secret key, read such an agent's threads without it.

One page of its conversations; pass next_cursor back as cursor.

Give a conversation back to the agent after it handed it to a person (its hand_off tool). The person's replies stay in its history, and the agent answers again from the next message. The person can hand it back from their page too.

Make a child agent and start task (its first message, up to 16,000 characters) at once. child.job is that task: a Job that runs while the child works on it, across as many turns as it takes, and finishes when the child stops with nothing left to continue it.

The child lives where its parent does and runs on the parent's harness, model and model connection unless harness, model or model_connection say otherwise. It gets only tools its parent has: tools names some of them (a narrower only(...) of one of the parent's connections is fine, and "card" gives it the card its parent pays with; anything the parent lacks raises noclick.InvalidRequest), and without tools it has none of them (nor its parent's can_request). Like every agent it has its shell (none when its parent has shell=False) and wake_me, and as a spawned child tell_parent, to reach its parent whenever its instructions say to. A person among the parent's tools passes down only with the tools the parent has of them, and a bound operation only as bound or narrower. instructions are its standing instructions: what its updates should say and when to reach out on its own; NoClick adds a short brief saying it works on one task for its parent. budget_usd is carved from the parent's monthly budget, and ttl_s makes it temporary. name defaults to <parent>-<random>.

updates is only when NoClick makes it report: "done" (always on: the job finished, any outcome), "blocked" (it started waiting on a person), noclick.Before(*tools) (before a matching tool call runs) and noclick.Every(interval) (at least that often while it works). Each update is a wake-up for the parent in conversation, the parent's conversation it belongs to (user= says whose, as for message: your key acting for a user spawns from an account agent in that user's thread, and the child is the account's; a user's own session can't); updates that come while the parent is mid-turn arrive together in its next turn. Without conversation, updates wake nobody and wait on the job (job.updates(), and your webhooks' agent.job.update event). A coordinator spawns the same way with its agents tools, its children's updates waking it in the conversation it spawned from. An agent holds up to 20 live children, and children spawn children up to 3 levels below an agent with no parent (noclick.QuotaExceeded). Agent.create(..., parent_id=) still makes a child without starting anything.

Its children, any status (an expired one for its 30 days), newest first: Agent.list(parent=self), read where this agent lives.

The jobs it started: the tasks of the children it spawned (kind="task") and the messages it sent with its agents tools (kind="message", whose only update is done). status takes operation statuses, or "live" for every unfinished one; agent (an Agent or id) keeps the ones one agent does; conversation the ones started from one of its conversations. Read where this agent lives: an account agent's are every user's.

Ask it something without stopping it. By default its model answers from a snapshot of conversation as it stands: its instructions, the conversation, and what a running turn has done so far, with no tools. The question and answer aren't added to the conversation and the agent never sees them; a running turn carries on untouched. The ask is recorded in its activity as an agent.ask operation and billed like a short turn. On a coding harness the snapshot is what NoClick holds: the conversation up to its last finished turn, plus the NoClick tool calls the running turn has made; the harness's own shell commands and file edits only arrive when its turn ends, and its model answers on its connection's key. An agent that thinks with a Claude or ChatGPT plan raises noclick.NotAvailable: a plan runs only in its harness, and answering in a one-off harness session is in invite-only beta (interject=True works).

interject=True puts the question into the running turn instead (the harness's own steering on a coding harness; before its next model call on sdk): the agent sees it, may change course, and answers in that turn, which stays in the conversation. With no turn running, it's an ordinary message. conversation defaults to the one it last worked in for the acting user (a spawned child's: its task's).

The agent's A2A agent card (the JSON other agents discover it by).

Change fields. Grants its user gave it are kept. A new harness without a model takes that harness's default model, and each conversation carries on on the new harness, with its own memory and the memories it attaches, from its next turn. memories are as in create ([] detaches them all). model_connection=None removes an sdk agent's own model key. timezone is as in create, and timezone=None goes back to the acting user's zone. repos are as in create, from its next turn (a running sandbox restarts with them; a clone already in a conversation's workspace stays as it is). shell is as in create, and network too, from its next turn (a coding harness's running sandbox restarts with it). card (invite-only beta) gives it a card in place of the one it holds, as in create, and card=None takes its card back. machine (invite-only beta) moves it onto a Machine, or with None back to a sandbox per conversation; each conversation moves between turns and keeps its files.

The connections its user gave it at run time (requested or active), oldest first.

Take back a grant (an AgentGrant or its id): its tools leave the agent; the connection stays the user's.

Delete the agent and the sub-agents under it: they go to the trash, restorable for 30 days. Its pending wake-ups and jobs end now and stay ended if it's restored.

Have it take a turn later in conversation, told note (up to 4,000 characters) and what woke it. Exactly one of: at (an aware datetime), after (seconds, or a timedelta), when: an Operation (a Job, a HumanRequest, a ConnectLink, ...: it wakes when that settles, with its outcome; one already settled wakes it at once), or a NoClick event type ("connection.connected", "human.answered"; * matches the rest of a name), narrowed by filters, dotted paths into the event's data and the values they must have: the first matching event after it was set wakes it, with the event; or every, a noclick.Cron: a routine that wakes the conversation at each of its times until it's canceled (tz="user" follows the conversation's user). A user's conversation hears that user's events; one of your account's own hears every event, your users' included. user= says whose conversation it is, as for message.

A turn already running in the conversation goes first: the wake-up waits for it, never Conflict. A channel's conversation raises noclick.InvalidRequest, as for message. It survives restarts, starts its turn once, and is billed and capped like any turn; when the turn can't be paid for, the wake-up fails with the reason. A recurring one stays pending, due at its schedule's next time after each turn, so times it missed (held, or late) fold into one turn. Every agent can also wake itself with its wake_me tool, and list, change and cancel its own (list_wakeups, cancel_wakeup). An agent holds up to 100 pending wake-ups and 20 recurring ones (noclick.QuotaExceeded); a time is 1 minute to 365 days ahead, a schedule comes round at most every minute (every 15 for one the agent sets itself), and one conversation's wake-ups are delivered at least a minute apart.

Its wake-ups in the acting user's conversations (or one conversation), or in those of the users user_filter covers: those your code set and those it set itself with wake_me, and NoClick's own: a child's update (update), the link it asked its user to connect an account with being done (answer) and a decided approval (approval). status keeps pending, delivered, canceled or failed ones. user_filter (noclick.ALL_USERS, noclick.NO_USER, a User or your id for one) reads across users without the user header, as conversations does: an account agent's wake-ups in every user's threads.

What wakes it besides a message: its schedules, webhooks, app events, NoClick events and queues, and the inboxes and phone numbers that hand it mail and calls.

Add a trigger: a noclick.OnWebhook, OnEvent, OnPlatformEvent, Cron or OnQueue. An agent holds up to 20. (An agent defined with from_name(create_if_missing=True, triggers=...) gets its list from your code instead, and loses one added here the next time that code runs.)

Remove a trigger: an AgentTrigger (or its id), or the definition you added (noclick.NotFound if the agent has none like it): an OnWebhook by its name alone, as names are unique on an agent. Mail and call triggers are changed on their inbox or number, not here.

The inboxes whose mail wakes it (created or updated with agent= it).

Stop every trigger from waking it: scheduled runs are skipped (not made up later), webhook calls are refused with 409 so their sender can retry, and app events, mail and calls that arrive meanwhile don't wake it. Messages your code sends still run.

Let its triggers wake it again, including one that stopped after failing the same way five times; a schedule picks up at its next run.

The files it works on in one conversation (AgentWorkspace). Sends nothing yet.

Turn on its public chat page, or read it if it's on: anyone with the link can talk to the agent, no sign-in, each visitor in conversations of their own. Visitors' turns bill to you and count against its budget, and each visitor is rate limited.

Its chat page as it is, without turning it on (share() does that).

Send text (with any files, as message sends them) and watch the turn as it happens: the reply as it's written, each tool call and its result, each file, approval and long action, then the whole reply. The same turn as message, billed the same.

Follow one conversation live, whoever moves it: turns a trigger, an answered ask or an approved held call started, messages sent from another client or session, and a person's replies after a hand-off. Your own message and stream turns show up too; tell them apart by operation_id. It runs until you stop reading (break) or the conversation is deleted.

A test run: a real turn of this agent (its model, instructions and tools) where a simulated world answers every tool call, so nothing is sent, no account is touched and its connections needn't be connected yet (its model connection must be). scenario says what that world is like; the world keeps to it, and without one it's an ordinary busy day. The run is billed like a turn, counts toward the agent's budget, and is no turn in any of its conversations. An account has up to 10 runs queued or running at once (noclick.QuotaExceeded past that).