Sessions à plusieurs tours et entrée en continu¶

Cette rubrique décrit les principaux moyens d’envoyer des invites au SDK Cortex Code Agent : requêtes à invite unique quand vous voulez que query() gère le cycle de vie de la session pour vous, entrée diffusée pour la livraison incrémentielle des invites, et les sessions à plusieurs tours pour les conversations interactives qui préservent le contexte à travers les échanges.

Modèles d’entrée¶

Le SDK fournit trois modèles d’entrée :


Mode	Quand utiliser	API
Saisie d’une invite unique	Envoyez une invite avec `query()` et laissez le SDK gérer le cycle de vie des sessions pour vous. La sortie continue d’être diffusée jusqu’à ce que l’agent produise un `ResultMessage`.	`query()` dans TypeScript et Python
Entrée diffusée	Envoyer des messages utilisateur de manière incrémentielle à partir d’un itérable asynchrone au lieu d’une seule chaîne d’invite	`query()` dans TypeScript et Python, plus `Query.streamInput()` dans TypeScript
Session à plusieurs tours	Conversations interactives : envoyer plusieurs invites, conserver le contexte, contrôler le cycle de vie de la session	`createCortexCodeSession()` (TypeScript) ou``CortexCodeSDKClient`` (Python)

Requêtes à invite unique¶

La fonction query() est le moyen le plus simple d’utiliser un SDK. Elle peut envoyer soit une chaîne à invite unique, soit un itérable asynchrone des messages utilisateur du SDK, et elle renvoie les événements jusqu’à ce que l’agent produise un ResultMessage. Dans ce mode, « invite unique » fait référence au modèle d’entrée : la sortie continue normalement.

import { query } from "cortex-code-agent-sdk";

for await (const message of query({
  prompt: "Explain how the auth module works",
  options: { cwd: process.cwd() },
})) {
  if (message.type === "assistant") {
    for (const block of message.content) {
      if (block.type === "text") process.stdout.write(block.text);
    }
  }
}

import asyncio
from cortex_code_agent_sdk import query, AssistantMessage, CortexCodeAgentOptions

async def main():
    async for message in query(
        prompt="Explain how the auth module works",
        options=CortexCodeAgentOptions(cwd="."),
    ):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text, end="")

asyncio.run(main())

La fonction query() gère le cycle de vie complet de la session pour vous : elle crée une session, envoie l’invite, produit des événements et ferme la session lorsque le résultat arrive ou que l’itérateur est épuisé.

Ceci est différent des maxTurns/max_turns. Une requête à invite unique permet toujours à l’agent de prendre autant de tours internes que nécessaire, sous réserve de la limite de tours configurée. Le paramètre maxTurns: 1 ou max_turns=1 est une contrainte séparée qui limite l’agent à un tour interne et peut produire un résultat error_max_turns.

Sessions à plusieurs tours¶

Pour les conversations qui nécessitent plusieurs échanges, utilisez une session. L’agent conserve le contexte entre les tours, de sorte que les invites ultérieures puissent faire référence aux fichiers lus, aux analyses effectuées et aux sujets abordés dans les tours précédents.

import { createCortexCodeSession } from "cortex-code-agent-sdk";

const session = await createCortexCodeSession({ cwd: process.cwd() });

// First turn
await session.send("Read the database connection module");
for await (const event of session.stream()) {
  if (event.type === "assistant") {
    for (const b of event.content) {
      if (b.type === "text") process.stdout.write(b.text);
    }
  }
  if (event.type === "result") break;
}

// Second turn -- context from the first turn is preserved
await session.send("What error handling patterns does it use?");
for await (const event of session.stream()) {
  if (event.type === "assistant") {
    for (const b of event.content) {
      if (b.type === "text") process.stdout.write(b.text);
    }
  }
  if (event.type === "result") break;
}

await session.close();

from cortex_code_agent_sdk import CortexCodeSDKClient, CortexCodeAgentOptions, AssistantMessage, ResultMessage

async with CortexCodeSDKClient(CortexCodeAgentOptions(cwd=".")) as client:
    # First turn
    await client.query("Read the database connection module")
    async for msg in client.receive_response():
        if isinstance(msg, AssistantMessage):
            for block in msg.content:
                if hasattr(block, "text"):
                    print(block.text, end="")

    # Second turn -- context from the first turn is preserved
    await client.query("What error handling patterns does it use?")
    async for msg in client.receive_response():
        if isinstance(msg, AssistantMessage):
            for block in msg.content:
                if hasattr(block, "text"):
                    print(block.text, end="")

Cycle de vie de la session¶

Appelez createCortexCodeSession(options) pour démarrer une session. Cela génère le processus CLI.
Appelez session.send(prompt) pour envoyer un message utilisateur.
Itérez session.stream() pour recevoir des réponses. Arrêtez l’itération lorsque vous voyez un événement result.
Répétez les étapes 2-3 pour des tours supplémentaires.
Appelez session.close() pour terminer la session et nettoyer le processus.

Créez un CortexCodeSDKClient et appelez connect() (ou utilisez async with).
Appelez client.query(prompt) pour envoyer un message utilisateur.
Itérez client.receive_response() pour recevoir des messages jusqu’à un ResultMessage (inclus).
Répétez les étapes 2-3 pour des tours supplémentaires.
Appelez client.disconnect() (ou laissez le bloc async with quitter).

Poursuivre une session précédente¶

Vous pouvez reprendre une conversation à partir d’une session précédente. L’agent charge l’historique de la conversation précédente et reprend là où il s’est arrêté.

import { createCortexCodeSession } from "cortex-code-agent-sdk";

// Continue the most recent conversation
const session = await createCortexCodeSession({
  cwd: process.cwd(),
  continue: true,
});

await session.send("What were we working on?");
for await (const event of session.stream()) {
  if (event.type === "result") break;
}
await session.close();

from cortex_code_agent_sdk import CortexCodeSDKClient, CortexCodeAgentOptions

# Continue the most recent conversation
async with CortexCodeSDKClient(
    CortexCodeAgentOptions(continue_conversation=True)
) as client:
    await client.query("What were we working on?")
    async for msg in client.receive_response():
        pass  # process messages

Vous pouvez également reprendre une session spécifique par ID :

const session = await createCortexCodeSession({
  cwd: process.cwd(),
  resume: "previous-session-id",
});

async with CortexCodeSDKClient(
    CortexCodeAgentOptions(resume="previous-session-id")
) as client:
    ...

Faire un fork de session¶

Le fork crée une nouvelle session qui commence par l’historique complet de la conversation d’une session existante. La session originale n’est pas modifiée. Ceci est utile pour explorer des approches alternatives sans perdre la conversation initiale.

import { createCortexCodeSession } from "cortex-code-agent-sdk";

const forked = await createCortexCodeSession({
  cwd: process.cwd(),
  resume: "previous-session-id",
  forkSession: true,
});

await forked.send("Let's try a different approach");
for await (const event of forked.stream()) {
  if (event.type === "result") break;
}
await forked.close();

from cortex_code_agent_sdk import CortexCodeSDKClient, CortexCodeAgentOptions

async with CortexCodeSDKClient(
    CortexCodeAgentOptions(resume="previous-session-id", fork_session=True)
) as client:
    await client.query("Let's try a different approach")
    async for msg in client.receive_response():
        pass  # process messages

Interrompre un tour¶

Votre application peut demander une interruption pendant que l’agent traite un tour. Cela a le même effet que d’appuyer sur Esc dans la CLI. La session reste active pour d’autres invites.

Appel d’interruption direct¶

Appelez la méthode interrupt() pour envoyer directement une requête d’interruption :

import { createCortexCodeSession } from "cortex-code-agent-sdk";

const session = await createCortexCodeSession({ cwd: process.cwd() });

await session.send("Analyze every file in this large codebase");

// Interrupt after 10 seconds
setTimeout(() => session.interrupt(), 10_000);

for await (const event of session.stream()) {
  if (event.type === "result") break;
}

// Session is still alive -- send another prompt
await session.send("Just summarize the top-level structure instead");
for await (const event of session.stream()) {
  if (event.type === "result") break;
}

await session.close();

import asyncio
from cortex_code_agent_sdk import CortexCodeSDKClient, CortexCodeAgentOptions, ResultMessage

async with CortexCodeSDKClient(CortexCodeAgentOptions(cwd=".")) as client:
    await client.query("Analyze every file in this large codebase")

    # Interrupt after 10 seconds
    async def interrupt_later():
        await asyncio.sleep(10)
        await client.interrupt()

    asyncio.create_task(interrupt_later())

    async for msg in client.receive_response():
        pass

    # Session is still alive -- send another prompt
    await client.query("Just summarize the top-level structure instead")
    async for msg in client.receive_response():
        pass

Contrôleur d’annulation/événement d’annulation¶

Vous pouvez également envoyer un signal d’annulation au moment de la création de la session. Lorsque le signal se déclenche, le SDK envoie automatiquement la même requête d’interruption.

import { createCortexCodeSession } from "cortex-code-agent-sdk";

const controller = new AbortController();

const session = await createCortexCodeSession({
  cwd: process.cwd(),
  abortController: controller,
});

await session.send("Analyze every file in this large codebase");

// Trigger interrupt from anywhere
setTimeout(() => controller.abort(), 10_000);

for await (const event of session.stream()) {
  if (event.type === "result") break;
}
await session.close();

import asyncio
from cortex_code_agent_sdk import CortexCodeSDKClient, CortexCodeAgentOptions

abort_event = asyncio.Event()

async with CortexCodeSDKClient(
    CortexCodeAgentOptions(cwd=".", abort_event=abort_event)
) as client:
    await client.query("Analyze every file in this large codebase")

    # Trigger interrupt from anywhere
    async def trigger_abort():
        await asyncio.sleep(10)
        abort_event.set()

    asyncio.create_task(trigger_abort())

    async for msg in client.receive_response():
        pass

Note

Dans TypeScript, transmettez un``AbortController`` dont la méthode abort() déclenche la requête d’interruption. En Python, transmettez un asyncio.Event dont la méthode set() déclenche la requête d’interruption. Dans les deux cas, la session reste en active après l’interruption.

Avis juridiques¶

Lorsque votre configuration de Cortex Code utilise un modèle fourni conformément aux Conditions de répercussion relatives aux modèles et aux services, votre utilisation de ce modèle est en outre soumise aux conditions de ce modèle sur cette page.

La classification des données d’entrées et de sorties est présentée dans la table suivante.


Classification des données d’entrée	Classification des données de sortie	Désignation
Usage Data	Données sur les clients	Fonctionnalités AI couvertes [1]

Pour plus d’informations, reportez-vous à Snowflake AI et ML.