> ## Documentation Index
> Fetch the complete documentation index at: https://docs.guild.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> To act on a user's behalf in Guild, use the Guild REST API at https://api.guild.ai/v1.
> The OpenAPI spec is unauthenticated: https://docs.guild.ai/openapi.json (or openapi.yaml).
> Authenticate with an account API key, sent as HTTP Basic (key id as username, secret as password) or as `Authorization: Bearer <api_key_id>:<api_key_secret>`. See https://docs.guild.ai/api-reference/introduction#authentication.
> To run one agent on demand without account-wide access, use an API trigger instead: https://docs.guild.ai/platform/api-triggers.
> To act on Guild from an MCP client, connect to https://api.guild.ai/mcp (OAuth) or run `guild mcp` locally. Setup: https://docs.guild.ai/api-reference/mcp.
> To search these docs from an MCP client, connect to https://docs.guild.ai/mcp. The full page index is https://docs.guild.ai/llms.txt.

# Run and manage Cursor agents from Guild

> Let Guild agents create Cursor cloud coding agents, submit prompts, poll run status, and retrieve PR results with governed, server-side credentials.

Integrations · Cursor

Guild agents create and drive Cursor cloud coding agents, submit prompts, and retrieve pull request outcomes without any manual intervention. API keys are stored and injected by Guild's credential proxy, so agent code never sees the secret. Credential policies and audit let you control exactly which operations each agent may perform.

> [card] [Book a demo](https://guild-ai.cal.com/gtm/meeting-with-guild.ai)
>
> See how teams govern agents that use Cursor.

> [card] [Talk to sales](https://guild.ai/talk-to-sales)
>
> Get access to Guild, then connect Cursor to your first agent.

## What the Cursor integration exposes

The integration provides tools to create agents and enqueue their initial runs, retrieve durable agent metadata for idempotent recovery, fetch per-run and total token usage, list available models, and archive, unarchive, or permanently delete agents. A dedicated get-run tool lets a Guild agent poll run status until a result is ready.

## How it works

**1. Generate a Cursor API key**

Go to cursor.com/dashboard/integrations to generate an API key. The key starts with "crsr\_" and must be converted to base64 before use.

**2. Connect the credential in Guild**

In Guild, go to Access & setup > Credentials, click Connect, select cursor-cloud-agents, and paste the base64-encoded key into the API Key field. See [Credentials](https://docs.guild.ai/platform/credentials.md) for workspace, member, and agent-scoped options.

**3. Import tools in your agent**

Import CursorCloudAgentsTools from the integration package and spread it into your agent's tools object. Use pick() from the [SDK tools](https://docs.guild.ai/sdk/tools.md) to include only the tools your agent needs.

## Why Cursor agent access needs governing

Cursor tools can create agents, enqueue runs, and permanently delete resources. Guild stores the API key server-side and injects it through its credential proxy, so agent code never handles the secret directly. You can scope a credential to one workspace, one member, or one installed agent, ensuring the key is never shared beyond its intended audience.

Credential policies let you write ALLOW and DENY rules that the proxy enforces before any request reaches Cursor. A DENY rule always wins over an ALLOW rule, so you can block destructive operations like delete while permitting reads and runs. Unscoped rules apply to every agent and workspace that uses the credential; scoped rules target a single agent or workspace, letting you give different agents different permissions on the same key.

## About the Cursor integration

This integration gives Guild agents programmatic control over Cursor cloud coding agents. Agents can create new Cursor agents, submit prompts, monitor run status, and retrieve pull request outcomes. Token usage tracking per run is also available. The integration is `guildai~cursor-cloud-agents`.

## Authentication

* **Type:** API key
* **Header:** Guild sends the key as a bearer token in the `Authorization` header

### Setup

**1. Get an API key**

Go to cursor.com/dashboard/integrations to generate an API key. The key starts with "crsr\_". You need to change it to base64 and paste it on credentials API KEY.

**2. Connect Cursor**

In Guild, go to **Access & setup > Credentials**, click **Connect**, select **cursor-cloud-agents**, and paste the key into **API Key**.

See [Credentials](https://docs.guild.ai/platform/credentials.md) for workspace, member, and agent-scoped credentials.

## Usage

```typescript theme={null}
import { CursorCloudAgentsTools } from "@guildai-services/guildai~cursor-cloud-agents"
import { llmAgent } from "@guildai/agents-sdk"

export default llmAgent({
  systemPrompt: "You work with Cursor.",
  tools: { ...CursorCloudAgentsTools },
})
```

### Selecting specific tools

Tools are named with the `cursor_cloud_agents_` prefix. Use [`pick()`](https://docs.guild.ai/sdk/tools#selecting-specific-tools) to include only what your agent needs.

## Tools

Tools in the latest published version of `guildai~cursor-cloud-agents`:

| Tool | What it does |
| - | - |
| `cursor_cloud_agents_archive_agent` | Idempotent. |
| `cursor_cloud_agents_create_agent` | Create a Cursor Cloud Agent and enqueue its initial run |
| `cursor_cloud_agents_delete_agent` | Permanently deletes an agent. |
| `cursor_cloud_agents_get_agent` | Get durable agent metadata for idempotent recovery |
| `cursor_cloud_agents_get_agent_usage` | Get per-run and total token usage for an agent |
| `cursor_cloud_agents_get_run` | get\_run |
| `cursor_cloud_agents_list_agents` | List Cursor Cloud Agents for the authenticated caller |
| `cursor_cloud_agents_list_models` | list\_models |
| `cursor_cloud_agents_unarchive_agent` | Idempotent. |

## Frequently asked questions

> [accordion] Can my Guild agent track how many tokens a Cursor run used?
>
> Yes. The cursor\_cloud\_agents\_get\_agent\_usage tool returns per-run and total token usage for an agent.

> [accordion] Does the integration receive webhook events from Cursor?
>
> No. The catalog entry for guildai\~cursor-cloud-agents lists no webhook events, so agents must poll run status using the get-run tool.

> [accordion] How does Guild keep my Cursor API key out of agent code?
>
> Guild's credential proxy stores the key and adds it as a bearer token in the Authorization header on each outbound request. Agent code never sees the secret. See [Credentials](https://docs.guild.ai/platform/credentials.md) for details on how the proxy works.

> [accordion] Can I limit one agent to read-only Cursor operations and let another create and delete agents?
>
> Yes. Credential policies support ALLOW and DENY rules scoped to individual agents, so you can permit only list and get operations for one agent while allowing create and delete for another, all on the same connected credential. See [Credential policies](https://docs.guild.ai/platform/credential-policies.md) for rule syntax.

## Put a governed agent on Cursor this week

> [card] [Book a demo](https://guild-ai.cal.com/gtm/meeting-with-guild.ai)
>
> See how teams govern agents that use Cursor.

> [card] [Talk to sales](https://guild.ai/talk-to-sales)
>
> Get access to Guild, then connect Cursor to your first agent.

## Related

**Also runs on Guild:** [Azure DevOps](https://docs.guild.ai/integrations/azure-devops.md) · [Bitbucket](https://docs.guild.ai/integrations/bitbucket.md) · [GitHub](https://docs.guild.ai/integrations/github.md) · [GitLab](https://docs.guild.ai/integrations/gitlab-openapi.md)

**Read:** Docs: [Credential policies](https://docs.guild.ai/platform/credential-policies.md) · [Credentials](https://docs.guild.ai/platform/credentials.md) · [Tools in agents](https://docs.guild.ai/sdk/tools.md)
