Appearance
Cloud agents
The cursor-cloud-agents extension lets an Agent SDK agent hand coding work to Cursor cloud agents. A cloud agent works in a repository checkout and pushes branches and pull requests while your agent keeps talking to the person.
Mount it
ts
// bot/extensions/cloud.ts
import cursorCloudAgents from "@grok/agent-sdk/extensions/cursor-cloud-agents";
export default cursorCloudAgents({
cloud: {
repos: [{ url: "https://github.com/acme/api", startingRef: "main" }],
autoCreatePR: true,
},
});Launches run under the host's signed-in account (agent-sdk login, CURSOR_API_KEY, or CURSOR_SERVICE_ACCOUNT_KEY) and spend its cloud-agent budget.
What the agent can do
With the extension mounted, the agent can launch a cloud agent on a repository or pull request, check its status, read its conversation and edits, steer or stop it, and list the agents it launched. A bundled skill teaches the model when to delegate and how to write a brief a cloud agent can act on alone.
Each caller can only see and steer the cloud agents they launched. If every caller uses the same bearer token, the extension treats them all as one person. Use authored auth to keep callers apart.
When a cloud agent the conversation launched stops, the extension wakes that conversation once. The wake message gives the agent id and its status, and tells the model to call cloud__get. That tool returns the agent's result, the final answer of its latest run.
On Cursor hosting, the wake comes when the agent's run stops. This includes a run that someone else cancels. If the wake does not reach the conversation, the extension tries again every minute, up to 10 times. You configure nothing for this.
Nothing polls the agent. If no wake comes, ask the bot to check the agent with cloud__get. A stop in the middle of a turn does not wake the conversation yet. The extension stops waiting for a wake after 24 hours.
Some launches get no wake: launches off Cursor hosting, launches from a mount that sets its own apiKey, and launches with envVars. A launch that Cursor hosting cannot watch also gets no wake. For these launches, the launch result says watching: false. Ask the bot to check the agent when you need its result.
Read a result from your code
Your own code, such as a tool or a reminder, can launch a cloud agent with launchCloudAgent and read it back with getCloudAgent. When the agent has stopped and its latest run finished, result holds the final answer of that run. An errored or expired run has no result. Ask the agent to end with its report or its JSON, and parse result.
ts
import { getCloudAgent } from "@grok/agent-sdk/extensions/cursor-cloud-agents";
const agent = await getCloudAgent(agentId);
if (agent.status === "finished" && agent.result !== undefined) {
const report = JSON.parse(agent.result);
}getCloudAgent does not check who launched the agent. Pass only ids that your code launched, never an id that a model chose.
launchCloudAgent takes an optional agentId, a bc-<uuid>. When you omit it, the extension makes one. To retry a launch that timed out or failed, pass the same agentId again. If the first launch created the agent, you get that agent back and no second agent starts. The extension returns an existing agent only when this principal launched it through the extension. A launch with cloud.envVars cannot take an agentId.
Configure it
| Option | What it controls |
|---|---|
cloud | Launch defaults for repositories, environment, and pull request behavior. |
cloud.repos | The repositories the agent may hand work to, each with a default branch or pull request. Without it, launches run with no repository, so secrets in cloud.envVars never reach a repository you didn't list. |
cloud.teamMcpServers | Up to 50 team MCP server names that launched agents may use, matched case-insensitively. Omit it to allow every team server the account can use. Personal servers and cloud.mcpServers aren't filtered. |
model | The model launched agents run. Omit it to use the account default. |
apiKey | A Cursor API key to launch with instead of the host's own. |
Adjust it
To remove a capability such as sending follow-ups, mount the extension as a directory and disable that tool. See Adjust a mounted extension.