Grok Bot agents

The cursor-grokbot-agents extension lets a BDK agent consult the Grok Bot agents on its serve host's Cursor account. The bot keeps its existing conversation, memory, and tools, while your agent carries the delivered reply back into the current conversation.

Use this extension on the local runtime. It consults another Grok Bot; it does not move this agent onto a Grok Bot runtime.

Mount it

List the bots your agent may contact. Descriptions teach the model when to choose one bot over another.

// bot/extensions/grokbot.tsimport cursorGrokBotAgents from "@cursor/bdk/extensions/cursor-grokbot-agents";export default cursorGrokBotAgents({  agents: [    {      name: "Plan Keeper",      description: "Decides whether outdoor plans should move.",    },    {      name: "Chief of Staff",      description: "Routes work and tracks priorities.",    },  ],});

Mounted as grokbot, the extension contributes grokbot__ask, grokbot__check, grokbot__interrupt, and grokbot__list, plus guidance for consulting them.

You can also scaffold the packaged example:

bdk init ./grokbot --template grokbot-agents

Ask a named bot

When someone says, "Ask Plan Keeper whether we should move the picnic," your agent prepares one self-contained message, sends it, and waits for the bot's delivered reply. That reply appears in the current conversation as the consultation result.

The message must include who is asking, the relevant facts, and the shape of the answer. The Grok Bot does not see the current BDK conversation.

Avery is deciding whether to move Saturday's picnic. The forecast is 70% rain from 1-4pm. Recommend keep or move, give one reason, and name the best alternate time.

When exactly one bot is configured, the model may omit its name.

Keep waiting for a long reply

If the bot is still working when ask reaches its wait limit, the tool returns status: "running" and any reply received so far. Your agent calls check for the same bot and reports the final answer when it arrives.

check advances this caller's read position, so it returns only replies not already consumed. Check when the answer is needed instead of polling in a tight loop.

Earlier unread replies can arrive alongside the current result. Keep their order and pass them on when they still matter.

Interrupt a bot turn

Use interrupt when the bot is pursuing the wrong task or the person changes direction. The active turn stops, but the host account's conversation with that bot remains, so a later ask continues with its existing memory.

Stop Plan Keeper's current turn. Then ask it to compare indoor venues instead of changing the time.

check and interrupt act on the bot conversation directly, so expose this extension only to callers who may read or stop those conversations.

Configure it

agents is a name allowlist, not an existence check. A name outside the list is refused, but a misspelled configured name may create a new empty bot on first use. If a result says created: true, tell the person and check the name before sending more work.

With no agents list, any name is allowed. Prefer an explicit list for a shared agent. list returns configured bots and bots this caller already contacted; it does not enumerate the whole account.

Calls use the serve host credential: CURSOR_API_KEY, CURSOR_API_KEY_FILE, CURSOR_SERVICE_ACCOUNT_KEY, or bdk login. Use apiKey only when the extension should run under a different account.

pollIntervalMs changes how often a waiting tool reads for new bot output. Keep the default unless the service needs a different balance between response latency and request volume.

Account and caller boundaries

Every tool reaches the serve host account's existing Grok Bot conversation. Authenticated BDK callers have separate contact lists and read positions, but they do not get separate Grok Bot accounts or isolated bot memory.

A shared bearer token or anonymous host also collapses callers into one BDK principal. Use per-caller auth when contact history and read positions must remain separate.

If ask finds the bot busy with an earlier message, it sends nothing. For a bot this caller already contacted, use check or interrupt. On first contact, wait for the existing turn in the Grok Bot app to finish, then ask again.

Adjust it

To remove a capability such as interrupt, mount the extension as a directory and disable that tool. See Adjust a mounted extension.

What's next

• Extensions: namespaces, trust, and overlays