Cursor Python SDK

cursor-sdk paketi, kendi Python kodunuzdan Cursor agent'ını çağırmanızı sağlar. Cursor IDE, CLI ve web uygulamasında çalışan agent; senkronize edilmiş ve asenkron istemciler, türlendirilmiş dataclass'ler, akışlar ve sayfalar için standart yineleme ile Python'dan betik olarak kullanılabilir. Başlamak için Cursor'da /sdk yeteneğini çalıştırın.

REST API için bulut ajanı API sayfasına bakın. Diğer diller için SDK Bridge sayfasına bakın.

Genel Bakış

SDK, yerel ve bulut çalışma zamanlarını tek bir arayüzde birleştirir. Agent'in nerede çalıştığından bağımsız olarak aynı kodu yazarsınız.

Agent.create() işlevine local veya cloud geçirerek çalışma zamanını ayarlayın.

Kimlik doğrulama

Bir agent oluşturmadan önce CURSOR_API_KEY ayarlayın veya api_key iletin.

SDK, hem yerel hem de bulut çalıştırmaları için kullanıcı API anahtarlarını ve servis hesabı API anahtarlarını kabul eder. Team Admin API anahtarları henüz desteklenmemektedir.

• Cursor Dashboard -> API Keys sayfasındaki Kullanıcı API anahtarı
• Team settings sayfasındaki Servis hesabı API anahtarı. Bkz. Servis hesapları

export CURSOR_API_KEY="your-key"

Kullanım ve faturalandırma

SDK çalıştırmaları, IDE ve bulut ajanı çalıştırmalarıyla aynı fiyatlandırma, istek havuzları ve Gizlilik Modu kurallarına tabidir. Harcamalar, ekibinizin kullanım panelinde SDK etiketi altında görünür.

Kodda çalıştırma başına token sayılarını okumak için Token kullanımı bölümüne bakın. Bir agent'ın çalıştırmalarına ilişkin faturalandırılan kullanımı ve dolar maliyetini almak için agent.get_usage() bölümüne bakın.

Temel kavramlar

Kurulum

pip install cursor-sdk

Python 3.10 veya sonraki bir sürüm gerektirir.

Hızlı başlangıç

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

Akış olayları, asistan metninin nasıl alınacağını, araç çağrılarının nasıl işleneceğini ve çalıştırma durumunun nasıl okunacağını gösterir. Tek seferlik bir istem (oluştur, çalıştır, tamamla) için Agent.prompt() bölümüne bakın.

Bulutta hızlı başlangıç

Python SDK, Cursor'ın bulut ajanları için yerleşik destek sunar. Bağlı repoları listeleyebilir, bunlardan biri için bir agent başlatabilir, çalışmanın tamamlanmasını bekleyebilir ve nihai sonucu inceleyebilirsiniz.

from cursor_sdk import Agent, CloudAgentOptions, CloudRepositorywith Agent.create(    model="composer-2.5",    api_key="crsr_key",    cloud=CloudAgentOptions(        repos=[CloudRepository(url="https://github.com/your-org/your-repo", starting_ref="main")],        auto_create_pr=True,    ),) as agent:    print(agent.send("Add structured logging to the auth middleware").text())

SDK tarafından başlatılan bulut ajanları varsayılan ajan listesinde gösterilmez. Bunları Cursor Web'de veya Cursor agents penceresinde görüntülemek için Filter > Source > SDK seçeneğine tıklayın.

Asenkron kullanım

Asenkron istemci, senkronize edilmiş istemciyle aynı arayüzü sunar ve sunucular, botlar ve eşzamanlı agent orkestrasyonu için önerilir. AsyncAgent, AsyncClient, AsyncRun ve AsyncCursor, hem cursor_sdk hem de cursor_sdk.asyncio paketlerinden dışa aktarılır.

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

Genel bir asenkron varsayılan istemci yoktur. Her olay döngüsünün kendi istemcisine sahip olması için AsyncClient örneğini açıkça oluşturun veya AsyncClient.launch_bridge(...) işlevini asenkron bağlam yöneticisi olarak kullanın. Aynı kod yolunda senkronize edilmiş ve asenkron istemcileri karıştırmayın.

Agent oluşturma

Agent.create() seçenekleri doğrular ve hemen bir tutamaç döndürür. Çalışma zamanını seçmek için local veya cloud değerini iletin.

from cursor_sdk import Agent, CloudAgentOptions, CloudRepository, LocalAgentOptionsagent = Agent.create(    model="composer-2.5",    local=LocalAgentOptions(cwd="."),)cloud_agent = Agent.create(    model="composer-2.5",    cloud=CloudAgentOptions(        repos=[CloudRepository(url="https://github.com/your-org/your-repo", starting_ref="main")],        auto_create_pr=True,    ),)

agent.agent_id hemen atanır. Yerel agent'lara agent-<uuid>, bulut agent'lara ise bc-<uuid> kimliği atanır. agent.model, türlendirilmiş bir ModelSelection olduğundan agent.model.id ve agent.model.params doğrudan kullanılabilir.

Oturum ortam değişkenleri

Bulut ajanlarında, bir çalıştırma kısa süreli kimlik bilgileri veya yalnızca ilgili ajan için geçerli olması gereken başka değerler gerektirdiğinde env_vars parametresini iletin.

agent = Agent.create(    model="composer-2.5",    cloud=CloudAgentOptions(        repos=[CloudRepository(url="https://github.com/your-org/your-repo")],        env_vars={            "STAGING_API_TOKEN": os.environ["STAGING_API_TOKEN"],        },    ),)

Bu değerler durağan halde şifrelenir, cloud agent'ın shell'ine aktarılır ve agent silindiğinde silinir. env_vars, çağıranın sağladığı bir agent_id ile kullanılamaz; agent_id değerini belirtmeyin ve sunucunun oluşturduğu kimliği agent.agent_id üzerinden okuyun. Değişken adları CURSOR_ ile başlayamaz.

Yalnızca tek bir çalıştırma boyunca var olması gereken değerler için bunları agent.send() ile iletin. Çalıştırma başına ortam değişkenleri bölümüne bakın.

Agent meta verileri

Bir cloud agent oluştururken kendi tanımlayıcılarınızı ekleyin. Meta verileri, agent'ı sisteminizdeki bir kullanıcı, tenant, iş akışı veya ticket ile ilişkilendirebilir. Bu veriler, client.agents.get() ve client.agents.list() çağrılarında SDKAgentInfo.metadata üzerinden okunabilir.

from cursor_sdk import Agent, CloudAgentOptions, CloudRepositorywith Agent.create(    model="composer-2.5",    cloud=CloudAgentOptions(        repos=[CloudRepository(url="https://github.com/your-org/your-repo")],        metadata={            "end_user_id": "user-123",            "ticket_id": "ENG-456",        },    ),) as agent:    print(agent.agent_id)

Bulut ajanları için meta veriler oluşturma sırasında kullanılabilir. En fazla 50 anahtar-değer çifti ekleyebilirsiniz. Anahtarlar boş olmamalı ve 255 karakteri aşmamalıdır. Değerler, 4096 bayttan büyük olmayan dizeler olmalıdır. Boş dize değerlerine izin verilir ve boş bir eşleme meta veri yokmuş gibi değerlendirilir.

Model parametreleri

Akıl yürütme eforu veya Cursor Router'ın optimize_for değeri gibi modele özgü seçenekleri iletmek için ModelSelection.params kullanın. Parametre kimlikleri ve değerleri modele göre değişir. Hesabınız için desteklenen parametreleri ve önceden tanımlı varyantları görmek üzere Cursor.models.list() kullanın.

from cursor_sdk import Agent, LocalAgentOptions, ModelParameterValue, ModelSelectionagent = Agent.create(    model=ModelSelection(        id="composer-2.5",        params=[ModelParameterValue(id="fast", value="true")],    ),    local=LocalAgentOptions(cwd="."),)

Belirli bir modelin parametre kimliklerini ve önceden tanımlı varyantlarını görmek için Cursor.models.list() kullanın. auto-smart seçim sözleşmesi için Cursor Router bölümüne bakın.

Cursor Router

Cursor Router, her Auto isteği için bir model seçer. SDK'de Router, optimize_for parametresine sahip auto-smart modelidir. Teams ve Enterprise'ta kullanılabilir. auto-smart katalogda görünmeden önce Kurumsal yöneticilerin ekip için Router'ı etkinleştirmesi gerekir.

Cursor SDK, bağımsız bir model çıkarımı veya sohbet tamamlama API'si değil, bir agent SDK'sidir. Router; çalışma alanı üzerinde akıl yürütebilen, araç çağırabilen, komut çalıştırabilen ve dosya düzenleyebilen Cursor agent çalıştırmaları için model seçer. Cursor şu anda rastgele model çağrıları için ham bir Router uç noktasını belgelemez.

Maliyet, Denge veya Zekâ'yı seçin

auto-smart parametresini iletin ve optimize_for değerini açıkça ayarlayın:

Ürün metinlerinde Denge kullanın. balanced değerini yalnızca SDK'daki iletim değeri olarak kullanın.

import osfrom cursor_sdk import Agent, LocalAgentOptions, ModelParameterValue, ModelSelectionwith Agent.create(    model=ModelSelection(        id="auto-smart",        params=[ModelParameterValue(id="optimize_for", value="balanced")],    ),    local=LocalAgentOptions(cwd=os.getcwd()),) as agent:    run = agent.send("Find and fix the failing authentication test")    result = run.wait()    print(result.status)

optimize_for değerini her zaman iletin. Bu parametreyi atlamayın veya eski bir default değeri göndermeyin; desteklenen yöntem, katalog aracılığıyla keşiftir.

Model kataloğunda Router'ı keşfedin

Cursor.models.list(), API anahtarının mevcut hesabı ve ekibi için kullanılabilir modelleri, parametre tanımlarını ve önceden ayarlanmış varyantları döndürür. Router kullanılabilir olduğunda Cursor Router, auto-smart olarak görünür. Ekip yöneticileri Router'ı devre dışı bırakabilir veya üyelerin seçebileceği optimizasyon modlarını kısıtlayabilir.

Bir seçimi sabit kodlamadan önce kataloğu doğruluk kaynağı olarak kullanın:

from cursor_sdk import Cursor, ModelParameterValue, ModelSelectionmodels = Cursor.models.list()router = next((model for model in models if model.id == "auto-smart"), None)optimize_for = next(    (        parameter        for parameter in (router.parameters if router else [])        if parameter.id == "optimize_for"    ),    None,)if router is None or optimize_for is None:    raise RuntimeError(        "Cursor Router is not available for this API key. "        "Verify that Router is enabled for the key's team."    )requested_mode = "balanced"allowed_values = {entry.value for entry in optimize_for.values}if requested_mode not in allowed_values:    raise RuntimeError(        f'Router mode "{requested_mode}" is not enabled for this team.'    )model = ModelSelection(    id=router.id,    params=[ModelParameterValue(id=optimize_for.id, value=requested_mode)],)

Her çalıştırmada mod değiştirme

Bir çalıştırma için Router modunu değiştirmek üzere agent.send() çağrısında modeli geçersiz kılın:

from cursor_sdk import ModelParameterValue, ModelSelection, SendOptionsrun = agent.send(    "Handle this complex migration",    SendOptions(        model=ModelSelection(            id="auto-smart",            params=[ModelParameterValue(id="optimize_for", value="intelligence")],        ),    ),)

Çalıştırma başına model geçersiz kılmaları korunur. Sonraki gönderimlerde geçersiz kılma belirtilmezse yeni seçim kullanılmaya devam edilir. Bkz. Çalıştırma başına model geçersiz kılma.

Model kimlikleri: auto-smart, auto ve default

Faturalandırma ve yönlendirme havuzu

• Cost, klasik Auto davranışını ve paket Auto fiyatlandırmasını kullanır.
• Balance ve Intelligence, Cursor Router'ı kullanır ve planınız veya sözleşmeniz kapsamındaki yönlendirilen model ücretinden faturalandırılır.
• Temel model istekler arasında değişebilir. Tekrarlanabilir karşılaştırmalar için sabit bir model kimliği tercih edin.
• Kurumsal model izin listeleri yönlendirme havuzunu belirler. Gerekli modellerin engellenmesi Router'ı devre dışı bırakabilir.

Güncel ücretler ve yönlendirme havuzu için Cursor Router ve Modeller & Fiyatlandırma sayfalarına bakın.

Router'ın görünmemesi durumunda sorun giderme

auto-smart görünmüyorsa veya bir optimizasyon modu reddediliyorsa:

1. Cursor.models.list() çağrısını yapın.
2. Sonuçta auto-smart'ın yer aldığını doğrulayın.
3. optimize_for özelliğinin istediğiniz değeri (cost, balanced veya intelligence) içerdiğini doğrulayın.
4. Router'ın API anahtarına bağlı ekip için etkin olduğunu doğrulayın.
5. Birden fazla ekibe üyeyseniz anahtarın hedeflenen ekip bağlamında çalıştığını doğrulayın.
6. Router kullanılamıyorsa veya geçerli bir temel model seçemiyorsa ekibin model-access ilkesini kontrol edin.

Ham sözlükler

IDE'lerde otomatik tamamlama ve tür denetimi daha iyi çalıştığı için uygulama kodlarında türlendirilmiş dataclass'lar tercih edilir. SDK, kısa betikler veya harici olarak sağlanan JSON'lar için düz sözlükleri de kabul eder. Snake-case anahtarlar normalleştirilir.

from cursor_sdk import Agentwith Agent.create(    {        "api_key": "crsr_key",        "model": {"id": "composer-2.5"},        "local": {"cwd": "."},    }) as agent:    ...

Agent

Agent.create(), Agent.resume(), client.agents.create() ve client.agents.resume() tarafından döndürülen tutamaç.

class Agent:    agent_id: str    model: ModelSelection | None    client: CursorClient    def send(        self,        message: str | Mapping[str, Any] | UserMessage,        options: SendOptions | Mapping[str, Any] | None = None,        *,        idempotency_key: str | None = None,    ) -> Run: ...    def reload(self) -> None: ...    def close(self) -> None: ...    def list_messages(        self, options: Mapping[str, Any] | None = None    ) -> list[AgentMessage]: ...    def list_artifacts(self) -> list[SDKArtifact]: ...    def download_artifact(self, path: str) -> bytes: ...    def archive(self, options: Mapping[str, Any] | None = None) -> None: ...    def unarchive(self, options: Mapping[str, Any] | None = None) -> None: ...    def delete(self, options: Mapping[str, Any] | None = None) -> None: ...

Otomatik temizleme için bir bağlam yöneticisi kullanın:

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

Senkronize edilmiş Agent.* veya Cursor.* yardımcılarını client= belirtmeden kullandığınızda SDK, modül düzeyinde varsayılan bir istemciyi başlatır veya yeniden kullanır. Bu istemci, işlem sonlanırken otomatik olarak kapatılır; isterseniz açıkça da kapatabilirsiniz:

from cursor_sdk import close_default_clientclose_default_client()

Agent.prompt()

Agent.prompt(    message: str | Mapping[str, Any] | UserMessage,    options: AgentOptions | Mapping[str, Any] | None = None,    *,    client: CursorClient | None = None,) -> RunResult

Tek seferlik kolaylık: bir agent oluşturur, tek bir istem gönderir, çalıştırmanın tamamlanmasını bekler ve agent'ı serbest bırakır.

from cursor_sdk import Agent, AgentOptions, LocalAgentOptionsresult = Agent.prompt(    "What does the auth middleware do?",    AgentOptions(model="composer-2.5", local=LocalAgentOptions(cwd=".")),)print(result.result)

Asenkron karşılığı (AsyncClient'ın zaten açık olduğu varsayılır):

from cursor_sdk import AgentOptions, AsyncAgent, LocalAgentOptionsresult = await AsyncAgent.prompt(    "What does the auth middleware do?",    AgentOptions(model="composer-2.5", local=LocalAgentOptions(cwd=".")),    client=client,)

CursorClient

Yaşam döngüsünü açıkça denetlemek, özel bir bridge uç noktası veya HTTP seçenekleri kullanmak ya da tek bir işlemde birden fazla çalışma alanıyla çalışmak istediğinizde CursorClient kullanın. Client, diğer ad olarak kullanılmaya devam eder.

from cursor_sdk import CursorClient, LocalAgentOptionswith CursorClient.launch_bridge(workspace=".") as client:    with client.agents.create(        model="composer-2.5",        api_key="crsr_key",        local=LocalAgentOptions(cwd="."),    ) as agent:        print(agent.send("Summarize what this repository does").text())

Kaynaklar

Açıkça tanımlanmış istemciler, kaynak ad alanlarını sunar:

client.create_agent(...) ve client.list_agents(...) gibi üst düzey yöntemler kullanılmaya devam eder; ancak uygulama kodunda kaynak ad alanlarının kullanılması tercih edilir.

Özel HTTP istemcileri

Hem senkronize edilmiş hem de asenkron istemciler, proxy'ler, iletimler ve diğer gelişmiş HTTP yapılandırmaları için özel bir httpx istemcisi kabul eder:

from cursor_sdk import CursorClient, DefaultHttpxClientwith CursorClient.launch_bridge(    workspace=".",    http_client=DefaultHttpxClient(proxy="http://proxy.example.com"),) as client:    ...

from cursor_sdk import AsyncClient, DefaultAsyncHttpxClientasync with await AsyncClient.launch_bridge(    workspace=".",    http_client=DefaultAsyncHttpxClient(proxy="http://proxy.example.com"),) as client:    ...

DefaultHttpxClient ve DefaultAsyncHttpxClient, SDK'nın varsayılan zaman aşımı ve yönlendirme davranışını korur. Buna karşılık, sade httpx.Client ve httpx.AsyncClient, httpx'in varsayılan ayarlarını kullanır.

Zaman aşımlarını ve yeniden denemeleri yapılandırma

Her iki istemci de bağlantı ayarlarını paylaşan ve varsayılan değerleri geçersiz kılan sığ bir kopya döndüren with_options(...) yöntemini sunar:

short = client.with_options(timeout=5.0, max_retries=2)agent = short.agents.create(model="composer-2.5", local=LocalAgentOptions(cwd="."))

Asenkron karşılığı:

short_async = async_client.with_options(timeout=5.0, max_retries=2)agent = await short_async.agents.create(model="composer-2.5", local=LocalAgentOptions(cwd="."))

Mesaj gönderme

Her agent.send() bir Run döndürür. Her await async_agent.send() bir AsyncRun döndürür. Agent, çalıştırmalar arasında konuşma bağlamını korur; çalıştırma, tek bir istemin iş birimidir.

print(agent.send("Find the bug in src/auth.py").text())# Aynı agent, konuşma bağlamının tamamını korur.print(agent.send("Fix it and add a regression test").text())

Asenkron eşdeğeri:

run = await agent.send("Find the bug in src/auth.py")print(await run.text())run = await agent.send("Fix it and add a regression test")print(await run.text())

Metinle birlikte görseller göndermek için:

run = agent.send(    {        "text": "What's in this screenshot?",        "images": [{"data": base64_png, "mime_type": "image/png"}],    })

Yardımcı dataclass'leri de kullanabilirsiniz. SDKImage.from_file(path) dosyayı diskten okur ve base64 kodlamasını sizin için gerçekleştirir:

from cursor_sdk import SDKImage, UserMessagerun = agent.send(    UserMessage(        text="What's in this screenshot?",        images=[SDKImage.from_file("screenshot.png")],    ))

Kodlanmış baytlara veya uzak bir URL'ye zaten sahip olan kullanıcılar SDKImage.data_image(base64_data, mime_type) ve SDKImage.url_image(url) yöntemlerini de kullanabilir.

Çalıştırma

class Run:    id: str    agent_id: str    status: str  # "running" | "finished" | "error" | "cancelled" | "expired"    result: str    model: ModelSelection | None    duration_ms: int    git: RunGitInfo | None    created_at: str | None    usage: TokenUsage | None  # birikimli; etkin tutamacın özelliği    def stream(self) -> Iterator[SDKMessage]: ...    def messages(self) -> Iterator[SDKMessage]: ...    def events(self) -> Iterator[RunStreamEvent]: ...    def iter_text(self) -> Iterator[str]: ...    def text(self) -> str: ...    def wait(self) -> RunResult: ...    def cancel(self) -> None: ...    def conversation(self) -> list[ConversationTurn]: ...    def conversation_json(self) -> str: ...    def observe(self, *, after_offset: str | None = None) -> Iterator[RunStreamEvent]: ...    def supports(self, operation: str) -> bool: ...    def unsupported_reason(self, operation: str) -> str | None: ...    def on_did_change_status(        self, listener: Callable[[str], None]    ) -> Callable[[], None]: ...

run.stream(), run.messages() için bir takma addır. run üzerinde doğrudan yineleme yapmak, run.events() gibi RunStreamEvent zarflarını döndürür.

AsyncRun, usage dâhil aynı durum alanlarını sunar. G/Ç gerçekleştiren yöntemler asenkrondur: async for message in run.stream(), async for message in run.messages(), async for event in run.events(), async for text in run.iter_text(), await run.text(), await run.wait(), await run.cancel(), await run.conversation(), await run.conversation_json() ve async for event in run.observe().

Akış

run = agent.send("Find the bug in src/auth.py")for message in run.messages():    if message.type == "assistant":        for block in message.message.content:            if block.type == "text":                print(block.text, end="")    elif message.type == "thinking":        print(message.text, end="")    elif message.type == "tool_call":        print(f"[tool] {message.name}: {message.status}")    elif message.type == "status":        print(f"[status] {message.status}")    elif message.type == "usage":        print(f"[usage] turn total={message.usage.total_tokens}")

Bir çalıştırma akışı yalnızca bir kez tüketilebilir. run.messages(), run.events() ve run.iter_text() aynı temel akıştan veri alır ve akışı ilerletir. Akış tamamlandığında çalıştırma, nihai sonucu (run.result, run.status, run.usage, run.git, ...) içerir. Kalan etkinlikleri tüketip türlendirilmiş RunResult döndürmek için run.wait() çağrısını yapın.

Akış kullanmadan bekleme

result = run.wait()print(result.status)       # "finished" | "error" | "cancelled" | "expired"print(result.result)       # varsa nihai asistan metniprint(result.model)        # bu çalıştırmada kullanılan çözümlenmiş ModelSelectionprint(result.duration_ms)print(result.usage)        # toplam TokenUsage; kullanılamıyorsa Noneprint(result.git)          # buluttaki RunGitInfo

Asenkron karşılığı:

result = await run.wait()

Token kullanımı

Çalıştırmalar, çalışma zamanı sağladığında token kullanımını bildirir. Kümülatif toplamı canlı tutamaçtaki run.usage alanından (akış sırasında veya wait() sonrasında) ya da run.wait() tarafından döndürülen RunResult nesnesindeki result.usage alanından okuyun. Her ikisi de kullanım bildiren tüm turların toplamını içeren bir TokenUsage tutar; hiçbir tur kullanım bildirmediyse None olur. Örneğin, hiç tur tamamlamamış iptal edilmiş bir çalıştırmada, kullanım bilgisini sunmayan bir çalışma zamanında veya kullanım bilgisi henüz uzlaştırılmamış ayrılmış bir bulut snapshot'ında böyledir.

@dataclass(frozen=True)class TokenUsage:    input_tokens: int    output_tokens: int    cache_read_tokens: int    cache_write_tokens: int    total_tokens: int    reasoning_tokens: int | None = None

result = run.wait()if result.usage is not None:    print(f"total: {result.usage.total_tokens}")    print(f"in: {result.usage.input_tokens}, out: {result.usage.output_tokens}")    print(        f"cache read/write: {result.usage.cache_read_tokens}/{result.usage.cache_write_tokens}"    )else:    print("no usage reported for this run")

reasoning_tokens, output_tokens içinde zaten sayıldığından total_tokens, çifte sayımı önlemek için bunu hariç tutar.

Akış sırasında tur başına değerler için usage akış olayını (SDKUsageMessage) işleyin. Bu olay, kullanım bildiren her turun sonunda bir kez tetiklenir ve ilgili turun TokenUsage bilgisini içerir. run.usage ve result.usage, çalıştırma boyunca kümülatif kalır. Akış turlarından sonra tutamaç bu toplamları tercih eder; aksi takdirde bridge sağlıyorsa wait() sonucundaki kullanımı veya get_run / list_runs anlık görüntüsündeki kullanım bilgisini kullanır.

for message in run.messages():    if message.type == "usage":        print(f"turn used {message.usage.total_tokens} tokens")# Ya da mesajları kendiniz tüketmeden, wait işleminden sonra:result = run.wait()print(run.usage, result.usage)

Asenkron karşılığı: async for message in run.messages() ve await run.wait(). run.usage, AsyncRun üzerinde hâlâ senkron bir özelliktir.

TokenUsage, cursor_sdk üzerinden dışa aktarılır (ileri düzey çağıranlar için to_token_usage / sum_token_usage da sağlanır). Aktarım JSON’u camelCase kullanır (inputTokens, …); Python dataclass’ları ise snake_case kullanır.

Token sayıları, çalışma zamanının bildirdiği değerlerdir; maliyet hakkında bilgi vermezler. Faturalandırılan kullanım ve bir agent’ın çalıştırmalarının dolar maliyeti için agent.get_usage() çağrısını kullanın.

Metin çıktısını okuma

iter_text(), akış sırasında asistan metnini getirir. Çalıştırma hâlâ devam ediyorsa text(), wait() ile bekleyip nihai terminal metnini döndürür.

for chunk in run.iter_text():    print(chunk, end="")final_text = run.text()

Asenkron karşılığı:

async for chunk in run.iter_text():    print(chunk, end="")final_text = await run.text()

Bir çalıştırmayı iptal etme

run.cancel()

Asenkron karşılığı:

await run.cancel()

run.cancel(), etkin bir çalıştırmanın iptal edilmesini talep eder. Durum "cancelled" olarak değişir, canlı akış durur, devam eden araç çağrıları sonlandırılır ve run.wait(), status: "cancelled" ile tamamlanır. Kısmi çıktı (o ana kadar yazılmış asistan metni) Run nesnesinde kalır.

Zaten sonlanmış ("finished", "error", "cancelled", "expired") bir çalıştırmayı iptal etmeye çalışmak UnsupportedRunOperationError hatasına yol açar. Emin değilseniz run.status ile kontrol edin:

if run.status == "running":    run.cancel()

Çalıştırma durumunu okuma

print(run.id)print(run.status)  # "running" | "finished" | "error" | "cancelled" | "expired"stop = run.on_did_change_status(lambda status: print(f"status changed to {status}"))stop()  # dinleyiciyi kaldırturns = run.conversation()

run.conversation(), türlendirilmiş bir list[ConversationTurn] döndürür. Canlı akışa abone olmadan yapılandırılmış geçmişi görüntülemek veya kalıcı olarak saklamak için bunu kullanın. run.conversation_json(), ham JSON dizesini döndürür.

asenkron çalıştırmalar için await run.conversation() ve await run.conversation_json() kullanın.

Çalıştırma başına model geçersiz kılma

agent.send() işlevine ilettiğiniz model, o çalıştırma için agent'ın model seçimini değiştirir ve ardından kalıcı hâle gelir: geçersiz kılma belirtilmeden yapılan sonraki gönderimler yeni modeli kullanmaya devam eder. Önceki modele dönmek için başka bir model geçersiz kılması iletin veya geçerli seçimi agent.model üzerinden okuyun.

from cursor_sdk import ModelParameterValue, ModelSelection, SendOptionsrun = agent.send(    "Plan the refactor",    SendOptions(        model=ModelSelection(            id="composer-2.5",            params=[ModelParameterValue(id="fast", value="true")],        ),    ),)

run.model ve result.model, bu çalıştırmada kullanılan seçimi yansıtır ve çalıştırma başladıktan sonra değiştirilemez.

Çalıştırma başına ortam değişkenleri

Bulut ajanları, tek bir çalıştırma için ortam değişkenleri de alabilir. SendOptions içinde cloud.env_vars iletin; değerler yalnızca bu çalıştırma için agent'ın shell'ine eklenir — çalıştırma tamamlandığında VM'den kaldırılır ve sonraki çalıştırmada görünmez. Bu yaklaşım, agent'tan kullanmasını istemeden hemen önce oluşturduğunuz kısa ömürlü dağıtım token'ı gibi, turlar arasında değişen kimlik bilgileri için uygundur.

from cursor_sdk import CloudSendOptions, SendOptionsrun = agent.send(    "Deploy the preview environment",    SendOptions(        cloud=CloudSendOptions(env_vars={"DEPLOY_TOKEN": mint_short_lived_token()}),    ),)

Çalıştırma kapsamındaki bir değişkenin adı, CloudAgentOptions üzerindeki env_vars içindeki agent kapsamındaki bir değişkenle aynıysa, o çalıştırmada çalıştırma kapsamındaki değer kullanılır; sonraki çalıştırmada ise agent kapsamındaki değer yeniden geçerli olur.

Çalıştırma başına değişkenler ilk gönderimde de kullanılabilir. SDK bunları, ilk çalıştırmayla sınırlı olacak şekilde agent oluşturulurken iletir; dolayısıyla agent üzerinde kalıcı olarak saklanmazlar. Agent kapsamındaki değişkenler gibi durağan halde şifrelenir ve adları CURSOR_ ile başlayamaz.

Çalıştırma başına ortam değişkenleri yalnızca bulut ajanlarında kullanılabilir ve herkese açık repolarda çalışan agent'lar için kullanılamaz. Yerel agent'larda agent işlemi kendi ortamınızı devralır; bu nedenle send() çağrısından önce işlemde değişkenleri ayarlayın.

Konuşma modu

Bir çalıştırmanın önce keşfedip planlama yapmasını mı, yoksa değişiklikleri doğrudan uygulamasını mı belirlemek için mode="plan" veya mode="agent" parametresini iletin. Plan modunun üründe nasıl çalıştığını öğrenmek için Plan modu sayfasına bakın.

İlk çalıştırmayı başlatmak için Agent.create() işlevine iletilen AgentOptions içinde mode ayarlayın. Takip agent.send() çağrılarında, konuşmanın mevcut modunu korumak için mode parametresini atlayın; yalnızca o çalıştırma için mod değiştirmek üzere mode parametresini iletin.

from cursor_sdk import Agent, AgentOptions, CloudAgentOptions, CloudRepository, SendOptionswith Agent.create(    AgentOptions(        model="composer-2.5",        mode="plan",        cloud=CloudAgentOptions(            repos=[CloudRepository(url="https://github.com/your-org/your-repo")],        ),    )) as agent:    agent.send("Design the auth refactor").wait()    agent.send(        "Looks good, start building",        SendOptions(mode="agent"),    ).wait()

Ham delta akışı

Düşük seviyeli güncellemeler için SendOptions içinde on_delta ve on_step geri çağrılarını iletin. Senkron geri çağrılar inline olarak çağrılır. Asenkron geri çağrılar senkron veya asenkron olabilir; await edilebilir dönüş değerleri, sonraki event işlenmeden önce beklenir.

from cursor_sdk import SendOptionsdef on_delta(update):    if update.type in ("text-delta", "thinking-delta"):        print(update.text, end="")run = agent.send(    "Refactor the utils module",    SendOptions(on_delta=on_delta, on_step=lambda step: print(f"[step] {step.type}")),)run.wait()

Somut güncelleme ve adım alt sınıfları cursor_sdk.events modülünde bulunur:

from cursor_sdk.events import TextDeltaUpdate, ToolCallStartedUpdateif isinstance(update, TextDeltaUpdate):    print(update.text)

Geriye dönük uyumluluk için cursor_sdk üzerinden içe aktarılabilirler, ancak yeni kod cursor_sdk.events üzerinden içe aktarılmalıdır.

SendOptions

Sonraki üç bölüm, SDKMessage, InteractionUpdate ve ConversationTurn için ayrıntılı başvuru niteliğindedir. İlk okumada göz atabilir veya atlayabilirsiniz; Agent'ları sürdürme anlatıma kaldığı yerden devam eder.

Akış olayları

run.messages() türlendirilmiş SDK mesaj dataclass'lerini döndürür. message.type değerine göre ayrım yapın. Çalışma zamanı sağladığında tüm mesajlar agent_id ve run_id içerir.

SDKMessage = (    SDKSystemMessage    | SDKUserMessageEvent    | SDKAssistantMessage    | SDKThinkingMessage    | SDKToolUseMessage    | SDKStatusMessage    | SDKTaskMessage    | SDKRequestMessage    | SDKUsageMessage    | Mapping[str, Any])

SDKToolUseMessage, çoğu araç çağrısı için iki kez gönderilir: önce status="running" ve doldurulmuş args ile, ardından işlem tamamlandığında status="completed" (veya "error") ve doldurulmuş result ile. truncated, yük çok büyük olduğu için SDK'nın args veya result değerini kısaltıp kısaltmadığını gösterir.

SDKUsageMessage, token kullanımı bildirilen her turun sonunda bir kez gönderilir ve o turun TokenUsage bilgisini içerir. Turların toplamı run.usage ve result.usage içinde tutulur. Bkz. Token kullanımı.

@dataclass(frozen=True)class SDKUsageMessage:    type: Literal["usage"]    agent_id: str    run_id: str    usage: TokenUsage

Sonuç verileri (nihai metin, model, süre, kümülatif token kullanımı, git meta verileri), akış tamamlandıktan sonra Run nesnesinde yer alır. Çalışma zamanı bu bilgiyi bildirdiyse result.usage dahil, okumak için run.wait() kullanın.

Araç çağrısı şeması kararlı değildir. tool_call olaylarındaki args ve result yükleri her aracın iç yapısını yansıtır ve araçlar geliştikçe değişebilir. Araç adları da yeniden adlandırılabilir veya değiştirilebilir. args ve result değerlerini türsüz veri olarak ele alın ve savunmacı bir şekilde ayrıştırın. Olay zarfı (type, call_id, name, status) kararlıdır.

run.events() daha alt düzeyde RunStreamEvent zarfları döndürür. Ofsetlere, nihai sonuç zarflarına veya ham etkileşim güncellemelerine ihtiyacınız olduğunda kullanın:

for event in run.events():    print(event.kind, event.offset)

Etkileşim güncellemeleri

InteractionUpdate, agent.send() içindeki on_delta geri çağrısına iletilen ham delta türüdür. Güncellemeler, SDKMessage etkinliklerinden daha ayrıntılıdır: metin token token aktarılır ve araç çağrıları, args biriktikçe kısmi durum bilgisi bildirir.

InteractionUpdate = (    TextDeltaUpdate    | ThinkingDeltaUpdate    | ThinkingCompletedUpdate    | ToolCallStartedUpdate    | ToolCallCompletedUpdate    | PartialToolCallUpdate    | TokenDeltaUpdate    | StepStartedUpdate    | StepCompletedUpdate    | TurnEndedUpdate    | UserMessageAppendedUpdate    | SummaryUpdate    | SummaryStartedUpdate    | SummaryCompletedUpdate    | ShellOutputDeltaUpdate    | UnknownInteractionUpdate    | Mapping[str, Any])

PartialToolCallUpdate, model bir araç çağrısına argümanları aktarırken, taahhütte bulunmadan önce yayımlanır. SDKToolUseMessage.args için geçerli olan aynı kararlılık uyarısı burada da geçerlidir.

Konuşma türleri

run.conversation() tarafından döndürülen, bir çalıştırmanın tur başına yapılandırılmış görünümü. Her öğe, turn içindeki türlendirilmiş yükün yanı sıra turun type ayırıcısını da taşıyan bir sarmalayıcıdır.

@dataclass(frozen=True)class ConversationTurn:    type: str  # "agentConversationTurn" | "shellConversationTurn"    turn: AgentConversationTurn | ShellConversationTurn | Mapping[str, Any]@dataclass(frozen=True)class AgentConversationTurn:    user_message: Mapping[str, Any] | None = None    steps: Sequence[ConversationStep] = ()@dataclass(frozen=True)class ShellConversationTurn:    shell_command: ShellCommand | None = None    shell_output: ShellOutput | None = NoneConversationStep = (    AssistantConversationStep    | ToolCallConversationStep    | ThinkingConversationStep    | Mapping[str, Any])

turn.type değerine göre ayrım yapın ve yükü turn.turn üzerinden okuyun:

for turn in run.conversation():    if turn.type == "agentConversationTurn":        for step in turn.turn.steps:            print(step.type)    elif turn.type == "shellConversationTurn":        print(turn.turn.shell_command, turn.turn.shell_output)

on_step geri çağrılarındaki run.conversation(), her turda değil, her ConversationStep için tetiklenir. Araç çağrısı içeren konuşma adımları Mapping[str, Any] yükü taşır. Araç çağrısı yükü ayrıntılarını türsüz veri olarak ele alın; Stream events altındaki kararlılık notuna bakın.

Agent oturumlarına devam etme

Agent.resume(    agent_id: str,    options: AgentOptions | Mapping[str, Any] | None = None,    *,    client: CursorClient | None = None,) -> Agent

Kimliğini kullanarak mevcut bir agente yeniden bağlanmak için Agent.resume() veya client.agents.resume() kullanın. Yaygın kullanım senaryoları: daha önce başlatılmış, uzun süredir çalışan bir bulut agente yeniden bağlanmak veya yerel işlem yeniden başlatıldıktan sonra bir konuşmaya devam etmek. Çalışma zamanı, kimlik ön ekinden otomatik olarak algılanır (bc- bulutu, diğer tüm ön ekler yereli belirtir).

agent = Agent.resume("bc-abc123")run = agent.send("Also update the changelog")run.wait()

Eşzamansız karşılığı:

agent = await client.agents.resume("bc-abc123")run = await agent.send("Also update the changelog")await run.wait()

model değerini yeniden iletmezseniz, devam ettirildiğinde agent.model None olur. Satır içi MCP sunucuları devam ettirmeler arasında kalıcı değildir; genellikle gizli bilgiler içerir ve yalnızca bellekte tutulur. Devam ettirirken bunları yeniden iletin veya kalıcı olması gereken sunucular için dosya tabanlı MCP yapılandırmasını (.cursor/mcp.json ve local.setting_sources) kullanın.

Yerel kalıcılık

Yerel agent'lar, konuşma durumunu ve çalıştırma meta verilerini bridge aracılığıyla kalıcı olarak saklar; böylece takip mesajları ve Agent.resume() işlem yeniden başlatıldıktan sonra da devam eder. Bridge, bunları varsayılan olarak diskte, her çalışma alanı için ayrı bir durum kökü altında tutar. Bulut ajanları sunucu tarafında kalıcı olarak saklanır; bu nedenle bir bulut ajanını herhangi bir yerden sürdürdüğünüzde aynı konuşma döner.

Yerel kalıcılık çalışma alanı kapsamındadır. Bridge uzun ömürlü bir yardımcı işlem veya alt işlem olarak çalışıyorsa, yerel listeleme, alma ve sürdürme çağrılarının doğru agent'ları bulması için bridge'e agent ile aynı çalışma alanını verin. Bunu istemcide bir kez ayarlayın ve yerel listeleme ve alma çağrılarına cwd iletin:

from cursor_sdk import CursorClientwith CursorClient.launch_bridge(workspace="/path/to/repo") as client:    agents = client.agents.list(runtime="local", cwd="/path/to/repo")    info = client.agents.get(agents.items[0].agent_id, cwd="/path/to/repo")

Agent'leri ve çalıştırmaları inceleme

Listeleme, alma ve sayfalama API'leri için CursorClient kullanın.

from cursor_sdk import CursorClientwith CursorClient.launch_bridge(workspace=".") as client:    agents = client.agents.list(runtime="local", cwd=".")    for agent_info in agents.auto_paging_iter():        print(agent_info.agent_id)    info = client.agents.get(agents.items[0].agent_id)    runs = client.agents.list_runs(info.agent_id)    run = client.agents.get_run(runs.items[0].id)

Eşzamansız karşılığı:

agents = await client.agents.list(runtime="local", cwd=".")async for agent_info in agents.auto_paging_iter():    print(agent_info.agent_id)info = await client.agents.get(agents.items[0].agent_id)runs = await client.agents.list_runs(info.agent_id)run = await client.agents.get_run(runs.items[0].id)

Mesaj geçmişini okumak için bir agent tutamacı üzerinden agent.list_messages() kullanın. Yalnızca bir kimliğiniz varsa, aynı çağrı için Agent.messages.list(agent_id) türlendirilmiş özniteliklere kolay erişim sağlar.

Liste uç noktaları ListResult[T] döndürür. .items ve .next_cursor öğelerini doğrudan kullanın, geçerli sayfadaki öğeleri for item in page ile veya tüm sayfalardaki öğeleri .auto_paging_iter() ile yineleyin. Asenkron liste uç noktaları AsyncListResult[T] döndürür; async for item in page geçerli sayfadaki öğeleri, async for item in page.auto_paging_iter() ise sonuç kümesindeki tüm sayfalardaki öğeleri yineler.

SDKAgentInfo

Agent.list(), Agent.get(), client.agents.list() ve client.agents.get() tarafından döndürülen meta veri yapısı.

@dataclass(frozen=True)class SDKAgentInfo:    agent_id: str    name: str    summary: str    last_modified: str | None = None    status: str | None = None  # "running" | "finished" | "error"    created_at: str | None = None    archived: bool = False    runtime: Literal["local", "cloud"] | None = None    cwd: str = ""    env: CloudEnvironment | None = None    repos: Sequence[str] = ()    metadata: Mapping[str, str] = {}  # CloudAgentOptions.metadata'dan; yerel agent'lar için boş

Bulut ajanı yaşam döngüsü

Bulut ajanları, arşivlenene veya silinene kadar ekibinizin çalışma alanında kalır. client.agents.list(runtime="cloud") varsayılan olarak arşivlenmiş ajanları gizler; görmek için include_archived=True parametresini iletin. Belirli bir pull request'i açan ajanı bulmak için pr_url ile filtreleyin.

# Kimlik kullanılır, agent tutamacı gerekmez:Agent.archive(agent_id)Agent.unarchive(agent_id)Agent.delete(agent_id)# Doğrudan belirtilen bir istemci aracılığıyla:client.agents.archive(agent_id)client.agents.unarchive(agent_id)client.agents.delete(agent_id)# Mevcut bir agent tutamacı üzerinde:agent.archive()agent.unarchive()agent.delete()

archive, transkript okunabilir kalacak şekilde agent'ı geçici olarak siler. unarchive agent'ı geri yükler. delete kalıcıdır; sonraki okumalar NotFoundError döndürür.

Asenkron yaşam döngüsü yöntemleri aynı adları kullanır ve await edilebilir.

agent.get_usage()

Bir agent’in çalıştırmalarına ait faturalandırılan token kullanımını ve dolar maliyetini getirir. Bulut ajanları çalıştırma başına, yerel agent'lar ise tur başına döküm döndürür. Sonucu tek bir kayıtla sınırlamak için run_id parametresini iletin: bulut ajanları için run-<uuid> biçiminde bir çalıştırma kimliği, yerel agent'lar içinse önceki bir get_usage().runs[].run_id değerinden alınan kimlik.

usage = agent.get_usage()print(f"tokens: {usage.usage.total_tokens}")if usage.cost is not None:    print(f"charged: ${usage.cost.charged_cents / 100:.2f}")for run in usage.runs:    print(run.run_id, run.usage.total_tokens)

@dataclass(frozen=True)class AgentUsage:    usage: TokenUsage              # `runs` genelinde toplam    runs: Sequence[RunUsage] = ()    cost: UsageCost | None = None  # `runs` genelinde toplam@dataclass(frozen=True)class RunUsage:    run_id: str    usage: TokenUsage    cost: UsageCost | None = None@dataclass(frozen=True)class UsageCost:    raw_cost_cents: float  # indirimsiz model token maliyeti; istek başına fiyatlandırılan kullanım için 0    charged_cents: float   # indirimler ve Cursor Token Oranı dahil, ücretlendirilen tutar

Maliyet indirimleri içerir ve bir çalıştırma sona erdikten sonra kesinleşmesi biraz zaman alabilir; bu gerçekleşene kadar cost, None olur. charged_cents, plana dâhil kullanım, BYOK kullanımı ve kredi hibesi kapsamında 0.0 değerindedir.

Bu, Token kullanımı bölümünden farklı bir görünümdür: run.usage tek bir çalıştırmanın anlık token sayısıyken, get_usage() agent'ın tüm çalıştırmalarındaki faturalandırılmış kayıttır. Asenkron agent'larda await agent.get_usage() ile aynı kayıt alınır. AgentUsage, RunUsage ve UsageCost, cursor_sdk tarafından dışa aktarılır.

Cursor ad alanı

Hesap düzeyinde ve katalogdan okuma işlemleri. Senkronizasyon yöntemleri isteğe bağlı api_key parametresini alır; aksi takdirde CURSOR_API_KEY kullanılır.

from cursor_sdk import Cursorme = Cursor.me()models = Cursor.models.list()repositories = Cursor.repositories.list()

Açık istemci için eşdeğeri:

me = client.me()models = client.models.list()repositories = client.repositories.list()

Eşzamansız karşılığı:

from cursor_sdk import AsyncCursorme = await AsyncCursor.me(client=client)models = await AsyncCursor.models.list(client=client)repositories = await AsyncCursor.repositories.list(client=client)

Agent.create() veya agent.send() çağrılmadan önce geçerli model kimliklerini ve modele özgü parametreleri öğrenmek için Cursor.models.list() kullanın. Parametreler modele özgüdür. Yaygın örnekler arasında reasoning effort ve auto-smart için Cursor Router’ın optimize_for seçeneği bulunur.

Katalog, hesaba ve ekibe özeldir. Cursor Router, yalnızca API anahtarının ekibi için Router kullanılabiliyorsa auto-smart olarak görünür. Bkz. Cursor Router.

models = Cursor.models.list()composer = next((model for model in models if model.id == "composer-2.5"), None)print(composer.parameters if composer else [])# [#   ModelParameterDefinition(#       id="fast",#       display_name="Fast",#       values=(#           ModelParameterDefinitionValue(value="false"),#           ModelParameterDefinitionValue(value="true", display_name="Fast"),#       ),#   ),# ]

Her SDKModel için önceden tanımlanmış variants, geçerli params değerlerini zaten içerir; bunları bir ModelSelection içine kopyalayabilirsiniz.

Hedef model mevcut değilse ve Cost, Balance veya Intelligence istiyorsanız açıkça bir Router seçin (auto-smart + optimize_for). Router modu seçmeden sunucunun belirlediği Auto'yu istiyorsanız yalnızca ModelSelection(id="auto") kullanın. Cursor Router için optimize_for değerini her zaman açıkça iletin.

Cursor.repositories.list(), çağrıyı yapan hesap veya ekipdeki bulut ajanlarının kullanabileceği SCM repolarını (bağlı hizmete göre GitHub, GitLab, Bitbucket, Azure DevOps) döndürür. Her öğe bir url sunar. Bunları CloudAgentOptions.repos alanını doldurmak için kullanın.

MCP sunucuları

Agent'lar, çalışma zamanına bağlı olarak MCP sunucularını satır içi tanımlardan, proje/kullanıcı ayarlarından, eklentilerden ve kontrol paneli tarafından yönetilen yapılandırmalardan alabilir.

from cursor_sdk import (    Agent,    AgentOptions,    HttpMcpServerConfig,    LocalAgentOptions,    McpAuth,    StdioMcpServerConfig,)agent = Agent.create(    AgentOptions(        model="composer-2.5",        local=LocalAgentOptions(cwd="."),        mcp_servers={            "docs": HttpMcpServerConfig(                url="https://example.com/mcp",                auth=McpAuth(client_id="client-id", scopes=["read", "write"]),            ),            "filesystem": StdioMcpServerConfig(                command="npx",                args=["-y", "@modelcontextprotocol/server-filesystem", "."],            ),        },    ))

Düz sözlükler ({"type": "http", "url": ...} ve {"type": "stdio", "command": ...}), hızlı betik yazımı için pratik bir seçenek olarak da kabul edilir.

Yüklenenler

Yerel agent'lar, ad çakışmalarında ilk eşleşenin öncelikli olduğu en fazla beş kaynaktan sunucu yükler:

1. agent.send() içindeki mcp_servers. Bu çalıştırmada oluşturma sırasında tanımlanan sunucuları tamamen değiştirir (birleştirilmez).
2. Agent.create() içindeki mcp_servers. Gönderim bazında geçersiz kılma sağlanmadığında kullanılır.
3. local.setting_sources "plugins" içeriyorsa eklenti sunucuları.
4. local.setting_sources "project" içeriyorsa .cursor/mcp.json içindeki proje sunucuları.
5. local.setting_sources "user" içeriyorsa ~/.cursor/mcp.json içindeki kullanıcı sunucuları.

local.setting_sources olmadan yalnızca satır içi sunucular yüklenir. Yerel bir MCP sunucusu OAuth ile oturum açmayı gerektiriyorsa SDK, Cursor uygulamasında kaydedilmiş bir oturumu yeniden kullanabilir; ancak oturum açmanız için tarayıcı açamaz.

Bulut ajanları sunucuları şunlardan yükler:

1. agent.send() içindeki mcp_servers. Bu çalıştırmada oluşturma sırasında tanımlanan sunucuları tamamen değiştirir (birleştirilmez).
2. Agent.create() içindeki mcp_servers. Gönderim bazında geçersiz kılma sağlanmadığında kullanılır.
3. cursor.com/agents üzerindeki kullanıcı ve ekip MCP sunucularınız.

Satır içi bir sunucu auth veya headers içermiyorsa ve bu sunucu URL'sine daha önce cursor.com/agents üzerinde yetki verdiyseniz, kişisel API belirteciyle kimliği doğrulanmış çalıştırmalar bu OAuth belirteçlerini otomatik olarak yeniden kullanır. Servis hesabı API anahtarları bir kullanıcıyla ilişkilendirilmediğinden kullanıcı kimlik doğrulamasına geri dönemez.

local.setting_sources bulut ajanları için geçerli değildir.

Bulut

Bulut ajanları, kimlik doğrulaması yapılmış MCP yapılandırmalarını satır içi olarak da kabul eder. Bulut MCP, HTTP ve stdio iletimlerini destekler. Statik API anahtarları veya Bearer token'ları için HTTP headers kullanın. OAuth ile korunan sunucular için HTTP auth kullanın. Sunucu bulut VM'de çalışıyor ve kimlik bilgilerini ortam değişkenlerinden okuyorsa stdio env kullanın.

from cursor_sdk import (    Agent,    AgentOptions,    CloudAgentOptions,    CloudRepository,    HttpMcpServerConfig,    StdioMcpServerConfig,)agent = Agent.create(    AgentOptions(        model="composer-2.5",        cloud=CloudAgentOptions(            repos=[CloudRepository(url="https://github.com/your-org/your-repo")],        ),        mcp_servers={            "linear": HttpMcpServerConfig(                url="https://mcp.linear.app/mcp",                headers={"Authorization": "Bearer linear_pat_xxx"},            ),            "github": StdioMcpServerConfig(                command="npx",                args=["-y", "@modelcontextprotocol/server-github"],                env={"GITHUB_TOKEN": "ghp_xxx"},            ),        },    ))

• HTTP headers ve auth, Cursor'ın backend'i tarafından işlenir. Hassas alanlar maskelenir ve VM'ye aktarılmaz.
• Sunucu VM'de çalıştığı için Stdio env değerleri VM'ye aktarılır. Bunları diğer çalışma zamanı gizli bilgileri gibi ele alın.
• cursor.com/agents üzerinde yapılandırılan MCP sunucularının OAuth'u, ekip düzeyindeki sunucularda bile kullanıcı bazında kalır.

Tam yapılandırma formatı için MCP, buluta özgü davranış için Cloud Agent capabilities bölümüne bakın.

Alt ajanlar

Ana agentin Agent aracıyla başlatabileceği adlandırılmış alt ajanları tanımlayın. Bunları satır içi olarak iletin:

from cursor_sdk import Agent, AgentDefinition, AgentOptions, LocalAgentOptionsagent = Agent.create(    AgentOptions(        model="composer-2.5",        local=LocalAgentOptions(cwd="."),        agents={            "code-reviewer": AgentDefinition(                description="Expert code reviewer for quality and security.",                prompt="Review code for bugs, security issues, and proven approaches.",                model="inherit",            ),            "test-writer": AgentDefinition(                description="Writes tests for code changes.",                prompt="Write comprehensive tests for the given code.",            ),        },    ))

.cursor/agents/*.md konumunda repoya commit edilmiş (name, description ve isteğe bağlı model frontmatter içeren) alt ajanlar da algılanır. Inline tanımlar, aynı ada sahip dosya tabanlı tanımların yerine geçer.

İç içe alt ajanlar

Alt ajanlar, iç içe geçme limiti dahilinde kendi alt ajanlarını oluşturabilir. Bir alt ajan Agent aracını kullandığında, üst agentın eriştiği alt ajan yürütücüsüne erişir; böylece üst agent, kendi alt ajanlarına daha fazla görev devredebilen bir alt ajana görev devredebilir. Her düzey aynı adlandırılmış alt ajan kümesini görür. Üst düzey agent ve doğrudan alt ajanları alt ajan başlatabilir; ancak başka bir alt ajan tarafından başlatılan alt ajanlar daha fazla alt ajan başlatamaz.

Araç setini kısıtlama

tools, modele sunulan yerleşik araçlar için izin listesi oluşturur; disallowed_tools ise araçları kaldırır ve SDK sürümünüz yayımlandıktan sonra platforma eklenenler de dahil olmak üzere diğer araçları korur. Her ikisi de şimdilik yalnızca yerel agent'larda kullanılabilir ve agent'ta kalıcı olarak saklanmaz: kısıtlamayı korumak için devam ederken bunları yeniden iletin.

from cursor_sdk import Agent, AgentOptions, LocalAgentOptions# Salt okunur agent: yalnızca bu araçlar kullanılabilir.reader = Agent.create(    AgentOptions(        model="composer-2.5",        tools=["read", "grep", "glob", "ls"],        local=LocalAgentOptions(cwd="."),    ))# Shell erişimi dışında her şey.no_shell = Agent.create(    AgentOptions(        model="composer-2.5",        disallowed_tools=["shell"],        local=LocalAgentOptions(cwd="."),    ))

• tools belirtilmezse seçili model için standart araç seti sunulur; tools=[] yerleşik araç sunmaz, dolayısıyla model yalnızca metinle yanıt verebilir.
• Her iki alan da herkese açık adları ("read", "edit", "task", "webSearch", ...) ve "shell" ile "mcp" yetenek gruplarını kabul eder. Bilinmeyen adlar, oluşturma sırasında BadRequestError hatasına yol açar.
• Yasaklama önceliklidir: Bir aracın sunulabilmesi için tools içinde (ayarlanmışsa) yer alması ve disallowed_tools içinde yer almaması gerekir.
• "mcp" yasaklandığında özel araçlar da kaldırılır. "task" yasaklandığında alt ajanlar engellenir; aksi takdirde alt ajanlar kendi özenle seçilmiş araç setlerini kullanmaya devam eder.

Özel araçlar

Özel araçlarla, ayrı bir MCP sunucusu kurmadan Python işlevlerini yerel agent'lara sunabilirsiniz. Bunları LocalAgentOptions.custom_tools içinde belirtin.

from cursor_sdk import Agent, CustomTool, CustomToolContext, LocalAgentOptionsdef get_deployment_status(args, context: CustomToolContext):    service = args["service"]    return f"Service {service} is healthy."with Agent.create(    model="composer-2.5",    local=LocalAgentOptions(        cwd=".",        custom_tools={            "get_deployment_status": CustomTool(                description="Look up the current deployment status for a service.",                input_schema={                    "type": "object",                    "properties": {                        "service": {"type": "string", "description": "Service name"},                    },                    "required": ["service"],                },                execute=get_deployment_status,            ),        },    ),) as agent:    agent.send("Is the checkout service healthy?").wait()

execute, ayrıştırılmış argümanları ve varsa tool_call_id içeren bir CustomToolContext alır. Bir dize, JSON uyumlu bir değer veya content listesi içeren bir eşleme döndürebilir. Özel araçlar yalnızca yerel agent'lar tarafından kullanılabilir.

Hook'lar

Hook'lar yalnızca dosya tabanlıdır. Programatik hook geri çağrıları desteklenmez. Hook'lar, çalıştırma başına ayarlanabilen bir seçenek değil, proje ilkesi sınırıdır.

• Yerel: local.cwd aracılığıyla belirtilen repo'ya .cursor/hooks.json ekleyin veya kullanıcı düzeyindeki hook'lar için ~/.cursor/hooks.json ekleyin.
• Bulut: .cursor/hooks.json dosyasını ve betiklerini cloud.repos içinde belirtilen repo'ya commit edin. SDK ile oluşturulan bulut ajanları proje hook'larını otomatik olarak yükler. Kurumsal planlarda ekip hook'larını ve kurumsal olarak yönetilen hook'ları da çalıştırırlar.

Yapılandırma biçimi için Hook'lar, bulut davranışı için ise Cloud Agents hook desteği bölümüne bakın.

Çıktılar

Agent çalışma alanındaki dosyaları listeleyin ve indirin.

@dataclass(frozen=True)class SDKArtifact:    path: str    size_bytes: int = 0    updated_at: str = ""

from pathlib import Pathartifacts = agent.list_artifacts()for artifact in artifacts:    print(artifact.path, artifact.size_bytes)# Tek bir çıktıyı diske indirin.content = agent.download_artifact(artifacts[0].path)Path("review.md").write_bytes(content)

Asenkron agent'lar await agent.list_artifacts() ve await agent.download_artifact(path) yöntemlerini sunar.

Çıktı desteği çalışma zamanına bağlıdır. Yerel SDK agent'ları list_artifacts() çağrısında boş bir liste döndürür ve download_artifact() çağrısında hata verir.

Kaynak yönetimi

İşiniz bittiğinde agent'ları her zaman kapatın. En temiz senkronizasyon yöntemi bağlam yöneticisi kullanmaktır:

from cursor_sdk import Agent, LocalAgentOptionswith Agent.create(model="composer-2.5", local=LocalAgentOptions(cwd=".")) as agent:    agent.send("Summarize the repository").wait()

Açıkça serbest bırakmak için:

agent.close()

Asenkron agent'lar ve istemciler, asenkron bağlam yöneticilerini ve await ile temizleme işlemini destekler:

from cursor_sdk import AsyncClient, LocalAgentOptionsasync with await AsyncClient.launch_bridge(workspace=".") as client:    async with await client.agents.create(        model="composer-2.5",        local=LocalAgentOptions(cwd="."),    ) as agent:        run = await agent.send("Summarize the repository")        await run.wait()

Açıkça serbest bırakmak için:

await agent.close()await client.aclose()

Modül düzeyindeki senkronize varsayılan istemci, işlem sonlandığında otomatik olarak kapatılır. Uzun süre çalışan işlemler, istemciyi açıkça kapatıp sıfırlayabilir:

from cursor_sdk import close_default_clientclose_default_client()

Yapılandırma başvurusu

Python SDK, yardımcı dataclass'ları ve ham sözlükleri kabul eder. Dataclass'lar Python'da snake_case alanları kullanır ve uygulama kodlarında tercih edilir.

AgentOptions

LocalAgentOptions

CloudAgentOptions

AgentDefinition

CustomTool

@dataclassclass CustomTool:    execute: Callable[[Mapping[str, Any], CustomToolContext], Any]    description: str | None = None    input_schema: Mapping[str, Any] | None = Noneclass CustomToolContext:    tool_call_id: str | None = None

ModelSelection

@dataclass(frozen=True)class ModelSelection:    id: str    params: Sequence[ModelParameterValue] = ()@dataclass(frozen=True)class ModelParameterValue:    id: str    value: str

id, model kimliğidir (örneğin "composer-2.5" veya "auto-smart"). params, efor veya Router'ın optimize_for değeri gibi modele özgü parametreleri içerir. Hesabınız için geçerli kimlikleri, parametre tanımlarını ve önceden ayarlanmış varyantları görmek üzere Cursor.models.list() kullanın. Router seçim sözleşmesi için Cursor Router bölümüne bakın.

McpServerConfig

from cursor_sdk.types import McpServerConfig@dataclass(frozen=True)class HttpMcpServerConfig:    url: str    type: Literal["http", "sse"] | str = "http"    headers: Mapping[str, str] | None = None    auth: McpAuth | Mapping[str, Any] | None = None@dataclass(frozen=True)class SseMcpServerConfig(HttpMcpServerConfig):    type: Literal["sse"] = "sse"@dataclass(frozen=True)class StdioMcpServerConfig:    command: str    args: Sequence[str] | None = None    env: Mapping[str, str] | None = None    cwd: str | os.PathLike | None = None  # yalnızca yerelde kullanılır; bulut bu alanı kabul etmez@dataclass(frozen=True)class McpAuth:    client_id: str    client_secret: str | None = None    scopes: Sequence[str] = ()

Bulutta çalışan HTTP sunucularında headers ve auth, Cursor'ın arka ucu tarafından işlenir. Hassas alanlar VM'ye ulaşmadan önce gizlenir. Buluttaki stdio sunucularında env değerleri VM'ye aktarılır (bunları diğer tüm çalışma zamanı gizli bilgileri gibi ele alın).

UserMessage

@dataclass(frozen=True)class UserMessage:    text: str    images: Sequence[SDKImage | Mapping[str, Any]] | None = None

agent.send() mesaj bağımsız değişkeninin yapılandırılmış biçimi. Metinle birlikte imaj göndermek için kullanın.

SDKImage

@dataclass(frozen=True)class SDKImage:    url: str | None = None    data: str | None = None    mime_type: str | None = None    dimension: SDKImageDimension | Mapping[str, Any] | None = None    @classmethod    def from_url(cls, url: str, dimension=None) -> SDKImage: ...    @classmethod    def from_data(cls, data: bytes | str, mime_type: str, dimension=None) -> SDKImage: ...    @classmethod    def url_image(cls, url: str, dimension=None) -> SDKImage: ...    @classmethod    def data_image(cls, data: str, mime_type: str, dimension=None) -> SDKImage: ...    @classmethod    def from_file(cls, path, *, mime_type=None, dimension=None) -> SDKImage: ...

Uzak bir url veya mime_type ile birlikte base64 data iletin. from_data() baytları veya base64 dizgesini kabul eder. from_file() diskten bir dosya okur ve base64 ile kodlar.

SettingSource

SettingSource, cursor_sdk.types içinden erişilebilir.

from cursor_sdk.types import SettingSource

Yerel bir agent'ın yükleyeceği disk üzerindeki ayar katmanlarını belirler. Bulut ajanları her zaman project, team ve plugins ayarlarını yükler ve bu alanı yoksayar.

ListResult

@dataclass(frozen=True)class ListResult(Generic[T]):    items: list[T]    next_cursor: str = ""    def to_dict(self) -> dict[str, Any]: ...    def has_next_page(self) -> bool: ...    def next_page_info(self) -> dict[str, str]: ...    def get_next_page(self) -> ListResult[T]: ...    def auto_paging_iter(self) -> Iterator[T]: ...

client.agents.list(), client.agents.list_runs() ve Agent.list() tarafından döndürülür. Başka sayfa kalmadığında next_cursor boştur. Asenkron liste uç noktaları, beklenebilir eşdeğerleriyle AsyncListResult[T] döndürür.

Hatalar

Tüm SDK hataları CursorAgentError sınıfından türetilir. CursorSDKError, eski çağıranlar için geriye dönük uyumlu kök takma addır. Yeniden deneme mantığını belirlemek için is_retryable ve retry_after kullanın.

class CursorAgentError(Exception):    message: str    code: str | None    status: int | None    status_code: int | None    details: list[Mapping[str, Any]]    is_retryable: bool    cause: BaseException | None    request_id: str | None    headers: Mapping[str, str]    retry_after: str | None

Gecikmeli yeniden deneme

is_retryable ve retry_after, çağıran tarafın yeniden deneme mantığını belirler. retry_after, ayarlandığında sunucu tarafından sağlanan HTTP biçiminde bir dizedir (saniye veya HTTP tarihi).

import timefrom cursor_sdk import Agent, AgentOptions, CursorAgentError, LocalAgentOptions, RateLimitErrorfor attempt in range(3):    try:        result = Agent.prompt(            "Audit the auth middleware for missing input validation",            AgentOptions(model="composer-2.5", local=LocalAgentOptions(cwd=".")),        )        break    except RateLimitError as err:        time.sleep(float(err.retry_after) if err.retry_after else 2**attempt)    except CursorAgentError as err:        if not err.is_retryable:            raise        time.sleep(2**attempt)

Sunucu bir request_id döndürdüğünde, her CursorAgentError bunu içerir. Bir hatayı gösterdiğinizde bunu günlüğe kaydedin; böylece destek ekibi sorunu takip edebilir.

IntegrationNotConnectedError

class IntegrationNotConnectedError(ConfigurationError):    provider: str   # ör. "github", "gitlab", "azuredevops"    help_url: str   # yeniden bağlanma için kontrol paneli bağlantısı

Kullanıcıyı uygun yeniden bağlanma akışına yönlendirmek için help_url kullanın. SDK sürümü yayımlanmadan yeni sağlayıcılar eklenebilir.

AgentBusyError

Bulut ajanları aynı anda yalnızca bir etkin çalıştırmaya izin verir. Aynı agent üzerindeki başka bir çalıştırma hâlâ CREATING veya RUNNING durumundayken agent.send() çağrısı yaptığınızda (veya başka bir şekilde çalıştırma oluşturduğunuzda) AgentBusyError yükseltilir.

is_retryable değeri False olur. Etkin çalıştırma son duruma ulaşana veya siz iptal edene kadar hemen yeniden denemek başarısız olmaya devam eder. agent_archived gibi diğer 409 yanıtları bunun yerine ConfigurationError yükseltir.

Yeniden göndermeden önce etkin çalıştırmanın tamamlanmasını bekleyin, run.cancel() ile iptal edin veya Agent.list_runs() ile yoklayın:

from cursor_sdk import Agent, AgentBusyErroragent = Agent.resume("bc-00000000-0000-0000-0000-000000000001")try:    agent.send("Also add tests for the auth middleware.")except AgentBusyError:    runs = Agent.list_runs(agent.agent_id, {"runtime": "cloud", "limit": 1})    active = runs.items[0] if runs.items else None    if active is not None and active.status == "running":        active.cancel()    agent.send("Also add tests for the auth middleware.")

Yerel agent'lar AgentBusyError hatası vermez. Takılmış bir yerel çalıştırmayı sonlandırıp yenisini başlatmak için send() çağrısına local={"force": True} iletin.

UnsupportedRunOperationError

class UnsupportedRunOperationError(ConfigurationError):    operation: str

Bir Run işleminin mevcut çalıştırmada izinli olmaması durumunda oluşturulur. En yaygın durum, zaten sonlanmış bir çalıştırmada run.cancel() çağrılmasıdır.

run.supports(operation) ve run.unsupported_reason(operation), bir işlem adı ("stream", "wait", "cancel", "conversation") için SDK düzeyindeki desteği bildirir; çalıştırmanın durumunu denetlemez. Duruma duyarlı çağrıları korumak için run.status değerini okuyun.

Sorun Giderme

SDK’nin kendi günlükçüsüne bir stderr işleyicisi eklemek için CURSOR_SDK_LOG=debug (veya info) değerini ayarlayın. SDK yalnızca kendi cursor_sdk günlükçüsünü yapılandırdığından, host uygulamanın günlük kaydı kurulumuna müdahale etmez.

CURSOR_SDK_LOG=debug python my_script.py

Paketle birlikte, PATH'e cursor-sdk-bridge adıyla bridge ikili dosyası kurulur. Wheel'inizle birlikte gelen derlemeyi doğrulamak için doğrudan çalıştırın:

cursor-sdk-bridge --help

Bilinen sınırlamalar

• Araç çağrısı yük şemaları kasıtlı olarak güçlü biçimde türlendirilmemiştir.
• Satır içi MCP sunucuları Agent.resume() çağrıları arasında kalıcı değildir. Gerekirse devam ederken bunları tekrar iletin.
• Özel araçlar (local.custom_tools) ve araç seti kısıtlamaları (tools, disallowed_tools) yalnızca yerel agent'lar içindir. Kısıtlamalar agent üzerinde kalıcı değildir; devam ederken bunları tekrar iletin.
• Yerel agent'lar için çıktı indirme özelliği uygulanmamıştır.
• local.setting_sources (ve denetlediği dosya tabanlı MCP ve alt agent yolları) bulut ajanları için geçerli değildir. Bulut, project, team ve plugins öğelerini her zaman yükler.
• Hook'lar yalnızca dosya tabanlıdır (.cursor/hooks.json). Programatik geri çağrı desteklenmez.