Sesiones en la nube

Prerequisites

Antes de crear una sesión en la nube, asegúrese de que:

El usuario tiene acceso a Copilot con derechos de agente en la nube.
La sesión puede autenticarse con GitHub, ya sea con un token de usuario o con una identidad de Copilot CLI con sesión iniciada.
Puede asociar la sesión a un repositorio de GitHub. Esto es opcional en el tipo de SDK, pero se recomienda para que Mission Control y el agente en la nube tengan contexto de repositorio.
Las directivas de la organización permiten el control remoto y la visualización de sesiones desde superficies en la nube.

Creación de una sesión en la nube

Establezca la opción create-session cloud para crear una sesión en la nube. Puede incluir metadatos del repositorio para asociar la sesión en la nube a un repositorio de GitHub.

TypeScript

import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient();
await client.start();

const session = await client.createSession({
  onPermissionRequest: async () => ({ kind: "approve-once" }),
  cloud: {
    repository: {
      owner: "github",
      name: "copilot-sdk",
      branch: "main",
    },
  },
});

Python

from copilot import (
    CloudSessionOptions,
    CloudSessionRepository,
    CopilotClient,
    PermissionHandler,
)

client = CopilotClient()
await client.start()

session = await client.create_session(
    on_permission_request=PermissionHandler.approve_all,
    cloud=CloudSessionOptions(
        repository=CloudSessionRepository(
            owner="github",
            name="copilot-sdk",
            branch="main",
        )
    ),
)

Ir

package main

import (
    "context"

    copilot "github.com/github/copilot-sdk/go"
    "github.com/github/copilot-sdk/go/rpc"
)

func main() {
    _ = run(context.Background())
}

func run(ctx context.Context) error {
    client := copilot.NewClient(nil)
    if err := client.Start(ctx); err != nil {
        return err
    }

    session, err := client.CreateSession(ctx, &copilot.SessionConfig{
        Cloud: &copilot.CloudSessionOptions{
            Repository: &copilot.CloudSessionRepository{
                Owner:  "github",
                Name:   "copilot-sdk",
                Branch: "main",
            },
        },
        OnPermissionRequest: func(_ copilot.PermissionRequest, _ copilot.PermissionInvocation) (rpc.PermissionDecision, error) {
            return &rpc.PermissionDecisionApproveOnce{}, nil
        },
    })
    _ = session
    return err
}

client := copilot.NewClient(nil)
if err := client.Start(ctx); err != nil {
    return err
}

session, err := client.CreateSession(ctx, &copilot.SessionConfig{
    Cloud: &copilot.CloudSessionOptions{
        Repository: &copilot.CloudSessionRepository{
            Owner:  "github",
            Name:   "copilot-sdk",
            Branch: "main",
        },
    },
    OnPermissionRequest: func(req copilot.PermissionRequest, inv copilot.PermissionInvocation) (rpc.PermissionDecision, error) {
        return &rpc.PermissionDecisionApproveOnce{}, nil
    },
})
_ = session

.NET

await using var client = new CopilotClient();

var session = await client.CreateSessionAsync(new SessionConfig
{
    Cloud = new CloudSessionOptions
    {
        Repository = new CloudSessionRepository
        {
            Owner = "github",
            Name = "copilot-sdk",
            Branch = "main",
        },
    },
    OnPermissionRequest = (req, inv) =>
        Task.FromResult(PermissionDecision.ApproveOnce()),
});

Java

import com.github.copilot.CopilotClient;
import com.github.copilot.rpc.*;

try (var client = new CopilotClient()) {
    client.start().get();

    var session = client.createSession(
        new SessionConfig()
            .setCloud(new CloudSessionOptions()
                .setRepository(new CloudSessionRepository()
                    .setOwner("github")
                    .setName("copilot-sdk")
                    .setBranch("main")))
            .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
    ).get();
}

Óxido

use std::sync::Arc;
use github_copilot_sdk::{CloudSessionOptions, CloudSessionRepository, SessionConfig};
use github_copilot_sdk::handler::ApproveAllHandler;

let session = client.create_session(
    SessionConfig::default()
        .with_cloud(CloudSessionOptions::with_repository(
            CloudSessionRepository::new("github", "copilot-sdk").with_branch("main"),
        ))
        .with_permission_handler(Arc::new(ApproveAllHandler)),
).await?;

Las sesiones en la nube se inicializan en dos fases: createSession se ejecuta tan pronto como Mission Control ha reservado una tarea, pero el proceso remoto copilot-agent tarda uno o dos segundos más en conectarse y emitir session.start. Si llama a session.send antes de eso, el método RemoteSession.send del entorno de ejecución lanza el error "Remote session is still starting"; sin embargo, el envoltorio de esquema funciona según el principio fire-and-forget e ignora silenciosamente el error mientras sigue devolviendo un nuevo messageId a su código. La indicación se descarta en el servidor y nunca llega al trabajador.

Para enviar eventos de forma confiable, suscríbase a eventos antes de enviar y esperar el primer session.start evento cuyo producer es "copilot-agent":

import { CopilotClient, type CopilotSession } from "@github/copilot-sdk";

const client = new CopilotClient();
await client.start();

const session: CopilotSession = await client.createSession({
  streaming: true, // required for assistant.message_delta to fire
  cloud: { repository: { owner: "github", name: "copilot-sdk" } },
  onPermissionRequest: async () => ({ kind: "approve-once" }),
});

// Subscribe BEFORE sending so you don't miss the start event.
const ready = new Promise<void>((resolve) => {
  const off = session.on("session.start", (event) => {
    if (event.data?.producer === "copilot-agent") {
      off();
      resolve();
    }
  });
});

await ready;
await session.send({ prompt: "Summarize the README" });

Algunas notas:

Configure streaming: true en createSession para que el entorno de ejecución emita eventos assistant.message_delta. Sin ella, la única señal del asistente que recibes es el assistant.message final, adecuado para el procesamiento por lotes, pero el chat parecerá bloqueado si estás renderizando una interfaz en vivo. Consulte Eventos de la sesión de transmisión.
Solo el primersession.send es susceptible a esta condición de carrera. Los envíos posteriores en la misma sesión funcionan con normalidad porque el entorno de ejecución mantiene hasSessionStarted activado durante toda la sesión.
Aplique un tiempo de espera (por ejemplo, 60 s) a la promesa ready para que, si el aprovisionamiento de Mission Control se queda bloqueado, no deje la aplicación colgada indefinidamente.
El mismo patrón funciona en todos los lenguajes del SDK: suscríbase a session.start, compruebe producer === "copilot-agent"y llame a send.

Acceso a la dirección URL de Mission Control

Las sesiones en la nube son intrínsecamente remotas: una vez que el worker se conecta, Mission Control publica la sesión en https://github.com/copilot/tasks/{sessionId} y el entorno de ejecución emite un evento session.info con la URL. No es necesario llamar a remote.enable() — esa API solo sirve para ascender una sesión local a Mission Control.

Capture la URL suscribiéndose a session.info y filtrando por infoType: "remote":

session.on("session.info", (event) => {
  if (event.data?.infoType === "remote" && event.data.url) {
    console.log("Open from web or mobile:", event.data.url);
    // e.g. surface in your UI as a shareable link or QR code.
  }
});

El evento se desencadena poco después de session.start. Si su renderizador se monta después de que el evento ya se haya activado, guarde la URL junto con el registro de sesión en el estado de su aplicación y recupérela al volver a montar; el entorno de ejecución no vuelve a emitir session.info por sí solo.

Para obtener información sobre la misma configuración en sesiones locales promovidas mediante remote: true, consulte Sesiones remotas.

Asociación de repositorio

El objeto cloud.repository asocia la sesión en la nube a un repositorio de GitHub:

Campo	Required	Description
`owner`	Sí	Propietario o organización del repositorio.
`name`	Sí	Nombre del repositorio.
`branch`	No	Rama que se utilizará como contexto del repositorio. Omita para permitir que el entorno de ejecución elija la rama predeterminada o el contexto del repositorio actual.

La asociación del repositorio es opcional en el tipo de SDK, pero incluyela siempre que la aplicación conozca el repositorio de destino. Ayuda a Mission Control a mostrar la sesión en el contexto correcto y proporciona al agente en la nube un punto de partida más claro.

Use branch cuando el trabajo se inicie desde una rama específica. Si su aplicación crea sesiones a partir de solicitudes de incorporación de cambios, flujos de clasificación de incidencias o flujos de trabajo de implementación, indique la rama que corresponda a la tarea visible para el usuario.

Reanudación de una sesión en la nube

La cloud opción solo se aplica al crear una nueva sesión. Para reanudar una sesión en la nube existente, use la API de reanudación estándar para el lenguaje del SDK:

import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient();
await client.start();

const session = await client.resumeSession("session-id", {
  onPermissionRequest: async () => ({ kind: "approve-once" }),
});
void session;

const session = await client.resumeSession("session-id", {
  onPermissionRequest: async () => ({ kind: "approve-once" }),
});

No vuelva a enviar cloud al reanudar. Los metadatos de sesión guardados indican que la sesión está respaldada en la nube y la reanudación sigue el proceso normal de reanudación de la sesión.

Directivas y derechos de la organización

Se puede producir un error en la creación de sesiones en la nube cuando el usuario o la organización no tienen derecho a la ejecución del agente en la nube o cuando las directivas de nivel de organización bloquean el flujo. En concreto, las directivas del entorno aislado en la nube pueden impedir que los clientes creen la tarea en la nube.

Cuando esto ocurre, el entorno de ejecución indica el motivo de error "policy_blocked" en la creación de tareas en la nube. Trate esto como un resultado de autorización o directiva, no como un error transitorio de infraestructura.

En TypeScript, compruebe el motivo antes de reintentar:

import {
  CopilotClient,
  type CloudSessionRepository,
} from "@github/copilot-sdk";

const client = new CopilotClient();
await client.start();

const repository: CloudSessionRepository = {
  owner: "github",
  name: "copilot-sdk",
};

try {
  await client.createSession({
    cloud: { repository },
    onPermissionRequest: async () => ({ kind: "approve-once" }),
  });
} catch (error) {
  if ((error as { reason?: string }).reason === "policy_blocked") {
    // Show an admin-facing message or link to org policy settings.
  }
  throw error;
}

try {
  await client.createSession({ cloud: { repository } });
} catch (error) {
  if ((error as { reason?: string }).reason === "policy_blocked") {
    // Show an admin-facing message or link to org policy settings.
  }
  throw error;
}

En los lenguajes en los que los errores del SDK se representan de forma diferente, inspeccione la razón del error o el código mostrado y gestione "policy_blocked" explícitamente. No se espera que volver a intentarlo sin un cambio en la directiva tenga éxito.

Identificador de integración y enrutamiento

Las sesiones en la nube se marcan con un encabezado derivado de la variable de entorno /> <c1. Mission Control usa este identificador de integración para el comportamiento específico del enrutamiento, la atribución y la integración.

Para obtener instrucciones de servidor multiusuario y detalles completos del identificador de integración, consulte Implementaciones multiinquilino y servidor.

Mission Control redirige las sesiones en la nube creadas mediante el SDK al agente copilot-developer-sandbox. El nombre es un identificador interno de enrutamiento para el agente en la nube y no implica que la sesión utilice el espacio aislado local de Windows.

Avanzado: `COPILOT_MC_BASE_URL`

De forma predeterminada, el entorno de ejecución obtiene la URL base de Mission Control a partir de la URL de la API de Copilot configurada. Establezca COPILOT_MC_BASE_URL solo cuando necesite invalidar ese punto de conexión de Mission Control.

Esto puede ser necesario para las implementaciones de GitHub Enterprise Server. Confirme el valor correcto y el estado de soporte técnico con su representante de GitHub antes de confiar en él en producción.

COPILOT_MC_BASE_URL="https://example.com/agents"