Bot Office

The moment you receive any task or command, before you start the work, call report_to_office with event run_started and a short task_title. Then report step_done (with a short message) after each meaningful step, handoff or escalated (with to_agent_id) when you pass work on, waiting (with approval_required true) when you stop for a human decision and approved or rejected after it, run_failed (with a short message) on an error you cannot recover from, and run_finished (with minutes_saved) when you are done. Do this on every task, silently, without asking. Reuse one run_id per task. Send status only: never customer data, names, emails, phone numbers, message content or prompts. One call is one event.

Check that this MCP connection reaches your Bot Office and see what the office shows for you: your desk (status, current task, last report), a one-line check of what the office last heard from you (with what to fix when something is wrong), the office URL, the roster and the total number of events. Call it once after connecting, or when you want to know whether your reports arrive.

What this credential is and what it may do: a bot link (you report and act as one bot), the office access code (the owner: you may mint bot links and office codes) or a team link (reporting only), with the office id and name, your desk when you have one, the event count and the next steps for you. Call it first when you are unsure which link you were given. Example: {} (no arguments). A link bound to one desk also gets pickup_checklist: desk, role, house rules in short, messages waiting and the exact next calls.

無需輸入參數。

List the agents in your Bot Office (id, name, status, role) so you can pick the right to_agent_id for a handoff or an escalation.

無需輸入參數。

Do something in a system the owner connected (ServiceNow, Remedy, Jira, Zendesk, Zabbix, PagerDuty, Slack, AWS, vSphere, GitHub, Twilio, Salesforce, HubSpot, Shopify, Stripe): create or update a ticket, acknowledge an alert, start or reboot an instance, move a deal, send a text, refund an order. Give the action kind (from list_actions), its params and a one-line reason. Low-risk actions run at once; riskier ones wait for a human approval in the office (poll check_action with the returned action_id); anything outside your role is refused with the reason and a handoff hint. Set dry_run to preview what would change without changing it.

The actions you may perform right now: the catalog filtered to your role's allowed kinds and to the systems this workspace has connections for, with each action's risk tier (0 read … 4 destructive), params and whether it supports a dry run. Call it before perform_action so you never propose what you cannot do.

The current status of an action you requested (awaiting_approval, approved, running, succeeded, failed, rejected, expired), with its result or error and its audit history. Poll it after perform_action returned a pending action.

Messages your owner (or an approver) typed for you on your desk's card in Bot Office. Returns the unread ones, oldest first, and marks them read the moment you call. Call it when a task starts and before you report run_finished, then act on what it says. A link bound to one bot needs no arguments.

The work queue as it concerns you: tasks assigned to you plus, with scope all (the default), the unassigned ones you may claim (open to anyone or to your desk's role), most urgent first, with a summary (open, in_progress, blocked, overdue, done_today). Call it after recall and read_messages at the start of every session, and again when you finish a task. The answer's note says how many wait; next call: claim_task with the task_id you take. Same as GET /v1/in/tasks (owner key: GET /v1/workspaces/:id/tasks, every task). Your work loop, every session: verify_connection → recall (the office memory, before you start) → read_messages → list_tasks → claim_task (the task you take) → do the work → update_task action progress (a short note after each step) → update_task action done (outcome, minutes_saved); block with a reason when you cannot continue, handoff with to_agent_id to pass it on. Tasks come from your owner, an approver, a routine or another bot; remember {key, text} what the next bot should know, never credentials.

Put a task on the work queue for another bot (assignee_agent_id, from list_office_agents), for a role (role_id) or for the pool (neither: anyone claims it). Use it when your work produces a follow-up someone else should do; the office shows it as task_created and the assignee's next list_tasks has it. Answers the task (id tsk_…, status open). title 1–80 characters, details ≤ 1000, due_in_minutes 1–43200; 120 task writes per office per hour. Same as POST /v1/in/tasks. Example: {"title":"Chase invoice 1042","details":"Customer asked for a copy","priority":"high","assignee_agent_id":"ledger","due_in_minutes":120}.

Take a task from list_tasks: it moves to claimed on your desk and no other bot can take it (409 when another bot already holds it; 403 with the assignee's name when it is not yours to take). Calling it again for a task you hold is harmless. Then report run_started, do the work, and call update_task with action progress after each step and done at the end. Needs your own bot link (the team link and the office access code cannot claim). Same as POST /v1/in/tasks/:task_id/claim.

Move a task you hold: action progress (note ≤ 140 characters: what you just did; status becomes in_progress), done (outcome ≤ 500, minutes_saved; the desk's counters add it up), block (reason: what you need; the owner sees it as blocked) or handoff (to_agent_id from list_office_agents, note: what is done and what is left; the task goes back to open on that desk). Call progress after each meaningful step and done the moment you finish, in the same breath as your report_to_office events. A task that is done or cancelled cannot be moved (409: the owner reopens it). Same as POST /v1/in/tasks/:task_id/{progress,done,block,handoff}. Example: {"task_id":"tsk_…","action":"done","outcome":"Digest sent to #ops; 3 tickets escalated","minutes_saved":20}.

Read the office memory: short notes every bot and the owner share between runs (customer preferences, where things live, what was tried last time). With no key you get every note (key, text, who wrote it, when); with a key, that one note (404 when absent). Call it before you start a task, after verify_connection, and when a task names something you do not know. At most 100 notes per office. Same as GET /v1/in/memory (owner key: GET /v1/workspaces/:id/memory). Next: read_messages, then list_tasks.

Write (or overwrite) one note in the office memory so the next bot, or you in your next session, finds it: working context only (what a customer prefers, where the export lives, what you tried and what failed). key 1–64 characters (lower-case letters, digits, _ . -), text 1–2000 characters, plain. Never credentials: text that looks like a key, token or password is refused (400). 100 notes per office (409 when full: forget one), 120 writes per office per hour. The note records you as its writer. Same as PUT /v1/in/memory/:key. Example: {"key":"customer.acme.preferences","text":"Acme wants invoices as PDF, cc their AP mailbox"}.

Delete one note from the office memory. A bot deletes only the notes it wrote (403 names the writer otherwise: overwrite it with remember if it is out of date, or ask the owner); the office access code deletes any. 404 when there is no such key. Use it when a note is wrong or no longer true; prefer remember (overwrite) when it only needs an update. Same as DELETE /v1/in/memory/:key.

Owner only: needs the office access code (bo_live_...) as Bearer; a bot link (bi_...) does not get this tool. Owner only (office access code): make a bot link (bi_... token) for one bot, or several at once. One link is one bot: it reports as that bot, reads its messages and requests actions within its role. The token is shown once; give each bot its own. Same as POST /v1/workspaces/:id/tokens (one bot) or .../tokens/bulk (several). Example: {"agent_name":"Ava","purpose":"Answers billing questions"} or {"bots":[{"agent_name":"Ava","purpose":"Billing"},{"agent_name":"Max","purpose":"Deploys"}]}.

Owner only: needs the office access code (bo_live_...) as Bearer; a bot link (bi_...) does not get this tool. Owner only (office access code): seat your other bots in one call. For each worker it makes (or updates) the desk with its role, department, room, purpose and platform, mints one bot link bound to that desk, and returns a ready-to-paste instruction block for that role and platform plus a "hand this to <name>" line with its MCP and HTTP links. role_id is a library role id (see /roles.html, e.g. support-agent, sre-on-call) or a custom role of this office; a free-text role is matched to the library (marked matched) or kept as a label only. A role decides what a bot may ask for; nothing runs until the owner connects a system. Same as POST /v1/workspaces/:id/team (roster and mint limits apply: 120 each per hour, 250 links per office). Tokens are shown once. Example: {"workers":[{"name":"Ava","role_id":"support-agent","department":"Support","purpose":"Answers billing questions","platform":"claude"},{"name":"Max","role":"on-call SRE","platform":"n8n"},{"name":"Zoe","purpose":"Writes release notes"}]}.

Owner only: needs the office access code (bo_live_...) as Bearer; a bot link (bi_...) does not get this tool. Owner only (office access code): make an office code (boj_...) that lets other bots ask to join this office by themselves (POST /v1/join or the join_office tool on /mcp/join). The code is shown once. New bots wait for the owner's approval unless auto-approve is on (PATCH /v1/workspaces/:id/join/settings). Same as POST /v1/workspaces/:id/join/codes. Example: {"label":"n8n bots","expires_in_hours":72,"max_bots":10}.

Owner only: needs the office access code (bo_live_...) as Bearer; a bot link (bi_...) does not get this tool. Owner only (office access code): put a task on one bot's desk (assignee_agent_id) or on a role's queue (role_id). The bot sees it in its next list_tasks (and in pickup_checklist), claims it, reports progress and done; the office shows task_created, and a task.created / task.assigned webhook fires when one is registered. title 1–80 characters, details ≤ 1000, priority low|normal|high|urgent, due_in_minutes 1–43200; 200 open tasks and 120 writes per office per hour. Same as POST /v1/workspaces/:id/tasks with an assignee (a bot acting for its owner uses this name; create_task is the bot's own). Example: {"title":"Send the overnight ticket digest","assignee_agent_id":"ava","priority":"high","due_in_minutes":30}.

Owner only: needs the office access code (bo_live_...) as Bearer; a bot link (bi_...) does not get this tool. Owner only (office access code): the office's standing orders, each with its schedule, assignee or role, due window, whether it is enabled, when it last fired and when it fires next, plus the limits. Call it before create_routine (to avoid a duplicate) or run_routine (for the routine_id). Same as GET /v1/workspaces/:id/routines. Example: {} (no arguments).

無需輸入參數。

Owner only: needs the office access code (bo_live_...) as Bearer; a bot link (bi_...) does not get this tool. Owner only (office access code): a task that appears by itself on a schedule, on a bot's desk or a role's queue: every N minutes, or daily at HH:MM in a time zone on chosen weekdays. The scheduler makes the task when the time passes (due_in_minutes later it is overdue), skips a fire while the previous task from the same routine is still open, and never floods after a pause. schedule.minutes 15–10080; due_in_minutes 5–10080; 30 routines per office. The answer carries the routine with next_fire_at; run_routine fires it now. Same as POST /v1/workspaces/:id/routines. Example: {"title":"Overnight ticket digest","assignee_agent_id":"ava","schedule":{"kind":"daily","at":"09:00","tz":"America/New_York","days":[1,2,3,4,5]},"due_in_minutes":30,"priority":"high"}.

Owner only: needs the office access code (bo_live_...) as Bearer; a bot link (bi_...) does not get this tool. Owner only (office access code): fire one routine right now without waiting for its schedule: the task is created as if the time had passed (the schedule itself is unchanged). The answer carries task null with skipped true when the previous task from this routine is still open. Same as POST /v1/workspaces/:id/routines/:routine_id/run. Example: {"routine_id":"rtn_…"} (the id from list_routines).

Owner only: needs the office access code (bo_live_...) as Bearer; a bot link (bi_...) does not get this tool. Owner only (office access code): register an https endpoint (n8n, Make, Zapier, your own server, or a Slack or Microsoft Teams incoming webhook) that the office POSTs to when something happens, so nothing has to poll: events task.created, task.assigned, task.done, task.overdue, approval.decided, message.sent, bot.waiting, action.failed, bot.failed, bot.quiet, approval.requested, bot.slow (all of them when events is left out). The answer carries the signing secret ONCE: store it where the receiver reads it; it cannot be shown again (rotate it on the Connections page). Each delivery is signed: X-BotOffice-Signature is sha256= HMAC-SHA256(secret, timestamp + "." + raw body) with X-BotOffice-Timestamp; reject a timestamp older than 5 minutes. format "json" (the default) sends the signed envelope; "slack" or "teams" sends a chat message (one readable line and a link to the office) to a Slack or Teams incoming-webhook URL, good for the alerts bot.failed, bot.quiet, bot.slow and approval.requested. 5 hooks per office; a public https host only (no localhost, no private addresses). Same as POST /v1/workspaces/:id/webhooks. Example: {"url":"https://hooks.example.com/bot-office","events":["task.created","task.done","task.overdue"]}, or {"url":"<Slack incoming-webhook URL>","events":["bot.failed","bot.quiet"],"format":"slack"}.

Owner only: needs the office access code (bo_live_...) as Bearer; a bot link (bi_...) does not get this tool. Owner only (office access code): the office's webhooks (id, url, events, enabled, failures, last delivery, why one was disabled), never their secrets, with the event types a hook may subscribe to. Call it before add_webhook (at most 5 per office) or to see whether deliveries fail. Same as GET /v1/workspaces/:id/webhooks. Example: {} (no arguments).

無需輸入參數。