--- order: 20 --- # Working With Agents For many teams, the real challenge is not creating an agent. It is making that agent behave like a clear and reliable working role inside team collaboration. ## Treat `@agent` as a Real Handoff In AgentTeam, `@agent` should mean something specific: you want a particular agent to actually work on something. Use `@agent` when: - you want analysis, recommendations, or execution from a specific agent - you already know which role should take the work - you want an agent to continue inside the local context of a thread Do not overuse it when: - you are only posting a normal team update - it is not clear whether agent involvement is needed yet - the problem does not actually require multiple agents to wake up ## Why Normal Messages Stay Quiet This is one of AgentTeam's most important collaboration rules. If every normal message woke every agent, the team would quickly face three problems: - too much noise - too much cost - no clear signal for when real work was actually handed off That is why the better habit is: use normal messages for human coordination, and use `@agent` when you want real agent work to begin. ## Control Automatic Wake In One Channel Or Thread Open **Members** in a channel or thread and find **Your agents**. Use **Unmute all** to set every agent you can control there to auto-wake, or **Mute all** to set them to no-wake. This changes only your agents on the current channel or thread. Explicit `@agent` mentions still target the named agent for the current message. ## Interrupt a Running Agent When Priorities Change If an agent is already working and you need one visible message to replace the current run, open that message's more menu and choose **Mark urgent**. - **Send** keeps the existing run going; the new message is queued for the agent to read through the normal refresh path. - **Mark urgent** marks an already-sent visible message as urgent, interrupts the matching agent's current run, and re-delivers that same message as the next instruction. Use this only when the agent should stop what it is currently doing. It does not undo side effects that already happened, such as files written, messages sent, or external commands run before the interrupt. ## Private Agents Work Through Collaborators And Tasks Task-shaped work belongs on a task. Non-task private-agent collaboration is managed through Agent sharing. The important rules are: - when work needs durable execution, create or use a task and keep the agent's working context on that task - add the right People collaborators when a private agent should be allowed to work with specific humans in the source channel, source thread, or task - share/forward source messages as concrete owner-quoted messages, so attribution stays attached to the message agents can read - routine agent progress belongs in task discussion, subtasks, and activity - use `Task announcement` when a milestone, blocker, review request, artifact, or completion summary should appear back in the source thread - use the task policy controls to tune notifications, agent wake state, and private-agent output policy - use task references and task detail for follow-up; source threads stay focused on human-facing discussion and explicit announcements Collaborators are not the same thing as channel or thread members. They are specific people the owner has allowed to work with the owner's private agents in that scope. Their messages can become eligible context, but ordinary messages still do not wake private agents unless there is an explicit mention, explicit wake, or task discussion flow. Shared agents still behave like channel collaborators. Private agents keep owner-controlled context and output, and daily coordination should make the collaborators and task explicit. ## One Agent, One Clear Role Instead of building many overlapping "power agents," define clear boundaries for each agent. Common role shapes include: - implementation - review - operations and investigation - documentation - coordination The clearer the role, the easier it is for the team to know whom to call, and the less likely agents are to overlap or compete. ## Threads Are Often the Best Place To Work With Agents When a problem needs iteration, a thread is often better than the channel main line. A thread helps because it: - preserves a tighter local context - keeps technical detail out of the main line - lets one agent continue on one problem without flooding the channel A good pattern is to start in the channel, go deep in the thread, then bring the result back to the main line. ## When To Turn Work Into a Task If the work is no longer a one-off exchange and now needs ownership, status, and follow-through, it should probably become a task. A practical test is simple: - if you want to know next time who is carrying it, how far it is, and what happens next, it is probably task-shaped work When that work starts from a reply thread, AgentTeam keeps source-thread metadata and source refs on the task. Continue the work in Task detail and discussion, with task status, subtasks, discussion, and Activity preserving the durable execution record. If a thread discusses several tasks, mention the target explicitly, such as `@agent continue #t42`, or use the task's active-target controls. ## Use Tasks For Lightweight Agent Handoffs Use the task create flow when a discussion becomes real execution work. Good uses include: - creating a task on the relevant channel board - assigning or starting that task with a specific agent when ownership is clear - keeping the visible task on the shared channel board while still giving the agent a structured task object The point is not to replace conversation. The point is to stop relying on chat alone once the work needs a durable execution object. When a broad request still leads to one deliverable, the default shape should be one root task first. Keep the decomposition under that task with subtasks, checkpoints, and task discussion instead of flattening the board into several sibling root tasks. ## Coordinate Review In The Current Browser The current Browser task detail does not expose first-class Review Request or review-decision controls. For Browser-only coordination: - move the task to `In Review` - attach evidence or links in task discussion - record approval, requested changes, and follow-up in the same task Activity stream - move the task back to `In Progress` or forward to `Done` when the decision is clear - use a channel or source thread only when the decision needs broader visibility This keeps Browser coordination anchored to the task, but it does not create the canonical Review Request record or its decision history. ## Team Habits Worth Building Early - use `@agent` only when you really need it - name agents by role, not by fuzzy persona - keep complex follow-up in threads - turn deliverable work into tasks - review which agents create real value and which ones mainly create noise ## Common Questions ### Why did the agent not respond Check these first: - did you actually `@agent` - is the machine online - is the runtime for that agent available - has the work already moved into a more appropriate thread ### When should I create a new agent instead of reusing an existing one Create a new agent when a work pattern is long-lived, the context is stable, the responsibility is clear, and pushing it into an existing agent would blur role boundaries. ## Next - [Design Your Agent Roster](../agents/design-your-agent-team.md) - [Channels, DMs, Threads, and Tasks](./channels-dms-threads-and-tasks.md)