Python SDK 与异步客户端

Python SDK 需要 Python 3.10 或以上，包名为 cursor-sdk，导入名为 cursor_sdk。它自带 Bridge，不要求应用自己编写 TypeScript 层。

pip install cursor-sdk
export CURSOR_API_KEY="your-key"

用户或服务账号 key 均可，Team Admin key 尚不支持。代码可通过 api_key 显式传入；下面例子使用环境变量。

同步运行

import os
from cursor_sdk import Agent, LocalAgentOptions

with Agent.create(
    model="composer-2.5",
    local=LocalAgentOptions(cwd=os.getcwd()),
) as agent:
    print(agent.send("Summarize what this repository does").text())

优先使用 typed dataclasses，短脚本也可传普通字典，snake_case keys 会规范化。Agent.model 是 ModelSelection，可访问 id 和 params。用 CloudAgentOptions 与 CloudRepository 切换云端；默认列表里通过 Filter > Source > SDK 查找。

显式 client

CursorClient（别名 Client）适合多个 workspace、自定义 HTTP 或明确控制生命周期。CursorClient.launch_bridge(workspace=".") 启动服务；已有 Bridge 时用 CursorClient.connect(base_url, auth_token)，ping 和 get_version 检查健康与版本。

资源操作优先使用 client.agents、client.models、client.repositories。同步 Agent/Cursor 顶层 helper 未提供 client 时共用模块级默认 client，进程退出时关闭，也可用 close_default_client() 主动关闭重置。

异步运行

import asyncio
import os
from cursor_sdk import AsyncClient, LocalAgentOptions

async def main():
    async with await AsyncClient.launch_bridge(workspace=os.getcwd()) as client:
        async with await client.agents.create(
            model="composer-2.5",
            local=LocalAgentOptions(cwd=os.getcwd()),
        ) as agent:
            run = await agent.send("Summarize what this repository does")
            print(await run.text())

asyncio.run(main())

没有全局异步默认 client；每个 event loop 显式拥有 AsyncClient，不在同一路径混合同步与异步 client。直接用 AsyncAgent 类方法时必须传 client=。异步清理使用 await agent.close() 和 await client.aclose()，或以上 context manager。

流只消费一次

run.stream() 是 messages 的别名，返回 SDKMessage；直接迭代 run 或调用 events 返回 RunStreamEvent envelope。messages、events、iter_text 共用底层流，都会推进同一游标，不应分别再消费一遍。

run.wait() 排空剩余事件并返回 RunResult；run.text() 等待后返回最终文本。异步对应 async for 与 await。读取已结束结果不要求重新打开流。

HTTP 与分页

DefaultHttpxClient / DefaultAsyncHttpxClient 保留 SDK 的超时和 redirect 默认行为，普通 httpx client 使用 httpx 自身默认值。client.with_options(timeout=5.0, max_retries=2) 创建共享连接设置的浅拷贝；也可分别设置 unary_timeout 和 stream_timeout。

ListResult 的 next_cursor 在末页为空字符串。可用 has_next_page、get_next_page 或 auto_paging_iter，异步版本提供可等待的对应接口；不要照搬 TypeScript 的“字段省略”判断。