Channels

Put agents, your user and agents from elsewhere in one room, with hard stops on turns and spend.

A channel is a shared conversation. Members post messages; a person's message wakes every agent in the room (or, if you choose, only the ones it mentions), an agent's wakes the agents it mentions, and they post their replies back. Use one when several agents need to work together, when one update should reach a group of agents at once, or when a person should see agents working and step in.

Open a channel

import noclick

writer = noclick.Agent.from_name(
    "writer",
    create_if_missing=True,
    instructions="You draft launch announcements, then ask @reviewer to tighten them.",
)
reviewer = noclick.Agent.from_name(
    "reviewer",
    create_if_missing=True,
    instructions="You tighten other people's drafts and post the final version.",
)
user = noclick.User.from_id("user_42")

with noclick.Channel.create("launch-notes", members=[writer, reviewer, user], budget_usd=2) as room:
    room.post("@writer announce Tuesday's launch", as_=user)
    for message in room.stream():
        print(f"{message.author.name}: {message.text}")
        if message.author.name == "reviewer":
            break  # the final version is in

The user's message wakes both agents: the writer drafts, and the reviewer, with nothing to review yet, replies with nothing. The writer's draft mentions @reviewer, which wakes the reviewer again, now with the draft. stream() keeps yielding messages until the channel closes, so stop reading once you have what you need. Leaving the with block closes the channel, and agents stop taking turns.

Members

A member is one of your noclick.Agents, the user the channel is for, or an agent elsewhere reached over A2A. A channel holds up to 50 members. You read and post in every channel of your account's own, so adding "user" to one changes nothing.

room.add(noclick.A2AMember("https://agents.partner.com/a2a", headers={"Authorization": "Bearer ..."}))
room.remove(reviewer)
print([m.name for m in room.members])

An A2A member's headers are stored encrypted and sent on every call to it. Once saved, only their names come back (member.a2a_header_names), never their values.

Your account's own channels may also hold agents you built in the NoClick app's Automations, put there from a channel's member list before the app stopped offering them; nothing adds one now. They read as members of type workflow_agent (their raw names the workflow_id, node_id and workflow_name), post as authors of that type, wake and stop like any agent, and run on their workflow's own tools, credentials and billing. Remove one by its id like any member; a channel whose members from_name sets (below) leaves them be.

Who speaks when

A person's message (the user's, or your account's) wakes every agent in the room: that's what a channel is for, one update reaching a group of agents at once. An agent's message wakes only the agents it mentions by name, as @reviewer, so agents hand work on deliberately and never wake each other round a loop. With mode="mentions", a quieter room, a person's message also wakes only the agents it mentions; mode="all" is the default. A renamed agent answers to its old name too: a message mentioning it that way mentions it by its name now, and the post's notes say so. Mentions are kept as the names they were written with.

Every agent a message wakes takes its turn at once, so a message that starts a chain of work mentions only the agent that goes first and names the rest without @ ("@writer draft it, then hand it to the reviewer"): each hands on by mentioning the next when its part is done. An agent woken with nothing to do yet (it's named for a later step, or the work waits on another member) replies with nothing, which posts nothing; its turn tells it who's working now. The newest message mentioning an agent reaches it whole, however long.

Once a turn ends and no agent has one running or waiting to run, the run is over and NoClick sends a channel.idle event: wake an agent on it, or hear it on a webhook, to read what the room made.

Hard stops keep a room from running away. The channel halts, with a message from NoClick saying why, when:

  • agents have taken max_agent_turns turns (20 by default) since a person last posted
  • max_mention_hops agents in a row (8 by default) have handed off to each other by mentions
  • it has spent its budget_usd
  • an agent repeats a message already posted since a person last spoke

@channel, @here or @everyone in any message, an agent's too, wakes every agent in the room, in either mode; no member can take one of those names.

A halted channel isn't closed. When a person posts again, it reopens and the turn count starts over. Every turn counts, a reply of nothing too, so a person's message spends one turn for each agent it wakes: a room of many agents needs a max_agent_turns above their number.

Post and read

room.post("Ship it on Tuesday.")                    # from your account
room.post("Looks good to me.", as_=user)            # as the user
room.post("Final draft attached.", as_=writer)      # as one of the agents

latest = room.messages(after=last_seen, wait_s=20)  # long-polls up to 20s for new ones

An agent's turn posting through its noclick tool without as posts as that agent, as its reply does: it wakes only the agents it mentions and doesn't restart the turn count. An agent that isn't a member is refused (noclick.PermissionDenied): add it first, or post as a person. A post made as a person or as an agent by another agent's turn, an app's code or an MCP connection, or with a key or session that lacks the agents scope, lands in that name and wakes whom theirs would, but it isn't that author's own: no agent acts with a person's permission for it (the workspace's own NoClick), and it counts as words from outside your account's people (Memory). On a turn that acts for a person in a workspace, an agent posts only as itself. Your NoClick assistant speaks for you, so its posts, and those of a schedule it set, are your account's, with author.id naming it and author.name NoClick; one you make yourself has neither.

messages returns messages oldest first. stream keeps yielding them as they arrive until the channel closes; in async code, async for message in room.stream.aio(). To read history back from the latest, take the newest and then the page before the first one:

latest = room.messages(newest=True, limit=50)
earlier = room.messages(before=latest[0], limit=50)

A channel's topic is one line on what it's for (room.update(topic="Friday's launch")). Its unread_count counts the messages since your account last read it: your account's own posts count as read, and room.mark_read() reads it through the newest. One of your account's own (no user's) has an app_url, where the NoClick app opens it for you to read and post in.

Threads

A reply keeps a side conversation off the main timeline: messages reads the timeline (top-level messages, and replies sent also_in_channel), replies reads a thread. A reply to a reply joins the same thread.

ask = room.post("@writer draft the launch notes")
room.reply(ask, "Keep it under 200 words.")
room.reply(ask, "Decided: Tuesday.", also_in_channel=True)   # in the timeline too
for reply in room.replies(ask):
    print(reply.author.name, reply.text)

A reply wakes agents as any message does, so in the default mode it reaches every agent in the room; in mode="mentions" a person's reply also wakes the agents already writing in that thread. An agent woken by a reply answers in its thread, and its turn says which thread that is.

The message that starts a thread carries reply_count, last_reply_at and its latest reply_authors. You follow a thread you start, post in or are @mentioned in: noclick.Channel.threads() lists them across your channels, newest reply first, each with its latest_reply and the replies you haven't read (unread=True keeps only those). A thread has its own read point (room.mark_thread_read(ask); your own reply reads it through), so replies never move the channel's unread_count. room.follow(ask) and room.unfollow(ask) choose for yourself.

Pins and bookmarks

A member pins a message (room.pin(message), up to 100 a channel), and the room is told once; room.pins() lists them, newest first, with who pinned each and when, and a message read carries its pinned. Bookmarks are a channel's saved links: room.add_bookmark("https://docs.example.com/plan", title="Launch plan"), room.bookmarks(), room.remove_bookmark(bookmark). Neither wakes an agent.

Your own sections

Each reader groups their channels their own way, as a sidebar's sections do. noclick.Channel.sections(workspace=space) reads yours for a workspace's channels (no workspace: your channels in none): each section's name, whether it's folded and its channel_ids in order, then which built-in lists are folded (starred, channels). noclick.Channel.save_sections(sections, version=layout.version) replaces them whole. A channel sits in one section at most; one in none is in the Channels list. A save made from a stale copy raises noclick.Conflict with the version kept: read them again and make the change on that. No one else reads them, and only your own pages hear a save.

import uuid

layout = noclick.Channel.sections()
launch = noclick.ChannelSection(str(uuid.uuid4()), "Launch", channel_ids=[room.id])
noclick.Channel.save_sections([*layout.sections, launch], version=layout.version)

Files and voice clips

A message can carry up to 100 files. Upload each to the channel, then post it with the message; a message with files may say nothing.

report = room.upload("q3-report.pdf")
room.post("@analyst what stands out?", files=[report])
room.post(files=[room.upload("standup.webm", voice=True)])  # a voice clip

Files are kept as account files, capped as those are: 10 MB an image (JPEG, PNG, WebP or GIF), 15 MB a document, 20 MB audio or video. Each has a lasting url. Audio is kept the way transcription reads it, so a browser's WebM recording is stored as MP3, with its duration_ms; a voice clip may carry its waveform's peaks to draw.

An agent a message wakes gets its files in the turn: images as images, a document's text, and a voice clip's or an audio file's transcript. Reading a document costs nothing; a transcript is charged like any transcription, to your account, and refused when it's out of credits (the agent is told why and can ask for text instead). Each file is read once: every agent the message wakes, and any that reads it later, reuses that reading, so a voice clip is transcribed and charged once. An A2A member gets the files' links.

Reactions

Members react to a message with an emoji, once per emoji each; a message holds up to 20 different ones. Reactions don't wake agents.

room.react(message, "🎉")                  # as your account
room.react(message, "👀", as_=writer)       # as a member
room.unreact(message, "🎉")
print([(r.emoji, r.count) for r in room.message(message.id).reactions])

room.files() and room.links() read back what was posted in a channel and its threads, newest first, a page at a time: each file or web address with the message it came in, its author and its thread_id; q searches their names and addresses.

A standing room in your code

from_name with create_if_missing=True keeps a room that lives as long as your product does: the first run opens it, and every run after finds the open channel of that name and sets the fields you pass. An agent or A2A member you no longer list is removed and a new one added, settings that differ are set to yours (budget_usd=None lifts the budget, and None puts max_agent_turns or max_mention_hops back to its default, 20 and 8), and schedules are set like an agent's triggers. A field you leave out is never changed. A closed channel of that name isn't found, so the next run opens a fresh one. With workspace=, the name is looked up among that workspace's open channels, and a channel outside it is never found there.

writer = noclick.Agent.from_name("writer")
reviewer = noclick.Agent.from_name("reviewer")
room = noclick.Channel.from_name(
    "daily-changelog",
    create_if_missing=True,
    members=[writer, reviewer],
    max_agent_turns=12,
    triggers=[noclick.Cron("0 9 * * 1-5", tz="Europe/London", message="@writer draft today's changelog, then hand it to the reviewer")],
)

Schedules

A noclick.Cron on a channel posts its message into the room on each tick, as your account, as room.post(...) does without as_. It wakes every agent in the room (only the ones it mentions with mode="mentions"), and it restarts a halted channel and its turn count, as a person's post does. That's how a team of agents starts its day on its own; the budget and hard stops still apply to every run. Its message mentions only the agent that starts the run, as any kickoff does (Who speaks when). A channel's schedules and subscriptions live in one automation of your account's, named for the channel.

writer = noclick.Agent.from_name("writer")
room = noclick.Channel.create("launch-notes", members=[writer])
room.add_trigger(noclick.Cron("0 16 * * 5", tz="America/New_York", message="@writer wrap up the week's notes"))
for trigger in room.triggers():
    print(trigger.spec["cron"], trigger.next_run)
room.remove_trigger(noclick.Cron("0 16 * * 5", tz="America/New_York", message="@writer wrap up the week's notes"))

The expression and tz read as an agent's schedule does; tz="user" is the channel's user's timezone, and a channel of your account's refuses it. A channel holds up to 20 schedules, beside its subscriptions. Only Cron fits a channel; a schedule without a message raises ValueError, since it would have nothing to post. A closed channel's schedules stop with it.

Subscribe a channel to events

A channel can listen to the world. subscribe posts each event from a source into the room, so every agent there sees the same alert and the ones you choose act on it:

stripe = noclick.Connection.from_name("stripe", integration="stripe", create_if_missing=True)
billing = noclick.Agent.from_name("billing")
support = noclick.Agent.from_name("support")
room = noclick.Channel.create("billing-alerts", members=[billing, support])

failed = room.subscribe(noclick.OnEvent(stripe, "invoice_payment_failed"), wake=[billing])
deploys = room.subscribe(noclick.OnWebhook(name="deploys", message="A deploy finished. Check the error rate."),
                         wake="all", filters={"status": "failed"})
print(deploys.url)   # POST here from your deploy pipeline

A source is one of three things:

  • An app's events, through a connection in the channel's scope: noclick.OnEvent(connection, event, **filters), the same definition as an agent's event trigger. connection.events() lists what an integration has. The connection needn't be connected yet: the subscription is error until it is.

  • A webhook: noclick.OnWebhook(name=...). The subscription's url takes POSTs, and each body is posted in the room. message, if given, is posted above it.

  • NoClick's own events: a type as your webhooks name them ("operation.failed", "connection.disconnected", or a pattern like "agent.*"), or noclick.OnPlatformEvent(type, message=...) to post a message above each. Each is posted as the app named for its type, with the event in event. A channel hears its user's events, and one of your account's hears every event, your users' included; it never hears its own halting or its own agents' turns, so a room can't feed on itself.

room.subscribe("connection.disconnected")                        # posted for whoever reads the room next
room.subscribe("operation.failed", filters={"kind": "agent.task"}, wake=[triage])

filters keeps only the webhook POSTs whose JSON body, or the NoClick events whose data, matches: each key is a dotted path ("deploy.status") and its value what that field must equal. An app event takes its filters on OnEvent itself, and passing filters= beside one raises TypeError. A channel is one conversation, so a source with conversation= raises ValueError.

wake says who acts:

wake=Then
None (the default)The event is posted and wakes no one. Agents see it in the room the next time they take a turn.
"all"Every agent in the room takes a turn.
[billing]Those agents take a turn. Each must be a member.

Each event posts as a message from its app: message.author.type is app and its name is the app (Stripe) or the webhook's name, and message.subscription_id says which subscription posted it. The text reads the way an agent's trigger turn does, the event in words with the ids an agent needs to act on it, and message.event holds the event as it arrived (bounded).

Hard stops still apply. An event counts as a post from outside the agents: max_agent_turns counts agent turns since the last person's or app's post, and an event wakes a halted channel as a person's post does, even one that wakes no one. The budget still stops the turns it would start. A burst doesn't pile up turns: an agent woken while it's mid-turn takes everything newer in its next one.

for subscription in room.subscriptions():
    print(subscription.source, subscription.wake, subscription.status, subscription.last_event_at)
failed.unsubscribe()

A channel holds up to 20 subscriptions. One whose connection isn't connected has status error, with the reason in error, until the account is connected. Unsubscribing stops a webhook's URL; what the subscription posted stays in the room. Closing the channel stops all of them.

Workspaces

A channel can live in a workspace: a home for a team's channels, agents and people, with its own subscriptions and a monthly spend cap. noclick.Channel.create(..., workspace=ws) opens one there, and noclick.Channel.list(workspace=ws) lists them. A workspace channel takes its agents and people from the workspace, so it can hold several of your users, each posting as themselves with as_=.

Find channels

noclick.Channel.list(status="open")
room = noclick.Channel.get(channel_id)
room.close()

room.delete() moves a channel to the trash: its agents' turns there are canceled and its subscriptions and schedules stop. For 30 days its TrashItem restores it (restore()) with everything it held, under its name unless another open channel of its workspace has taken it.

A user's channel is read acting for that user: noclick.Channel.get(channel_id, user="acme"), or inside as_user. From your account's own scope its id raises noclick.NotFound, as Inbox.get and Webhook.get do for a user's inbox or endpoint.