Облачные сессии

Необходимые условия

Перед созданием облачной сессии убедитесь:

Пользователь имеет доступ к Copilot с правом облачного агента.
Сессия может аутентифицироваться в GitHub либо с помощью пользовательского токена, либо с авторизованной идентификацией Copilot CLI.
Сессию можно связать с репозиторием GitHub. Это необязательно в типе пакета SDK, но рекомендуется, чтобы агент облака имеет правильный контекст репозитория.
Политики организации позволяют проводить удалённое управление и просмотр сессий с облачных поверхностей.

Создание облачной сессии

Настройте опцию создания сессии cloud в облаке. Вы можете включить метаданные репозитория, чтобы связать облачную сессию с репозиторием 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",
        )
    ),
)

Go

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();
}

Rust

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?;

Облачные сеансы инициализируются на двух этапах: createSession разрешается сразу после того, как агент зарезервировал задачу, но удаленный copilot-agent рабочий процесс принимает еще одну секунду или два для подключения и отправки session.start. Если вы вызываете session.send до этого, среда выполнения RemoteSession.send вызывает вызов "Remote session is still starting", но оболочка схемы является fire-and-forget и молча проглотает ошибку , по-прежнему возвращая свежий messageId код. Запрос сбрасывается на сервере и никогда не доходит до работника.

Чтобы отправлять надёжно, подпишитесь на события перед отправкой и ждите первое session.start событие, котороеproducer:"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" });

Несколько примечаний:

Сделайте streaming: true так createSession , чтобы время исполнения assistant.message_delta событий. Без него единственный сигнал помощника — это финальный assistant.message сигнал — это нормально для пакетного использования, но чат будет выглядеть застывшим, если вы рендерите живой интерфейс. См . раздел AUTOTITLE.
Только перваяsession.send чувствительна к этой расе. Последующие отправки на одну и ту же сессию работают нормально, потому что время выполнения остаётся hasSessionStarted установленным на протяжении всей сессии.
Примените время ожидания (например, 60 с) вокруг ready обещания, чтобы застрявший сеанс не повесить ваше приложение навсегда.
Та же схема работает во всех SDK-языках — подписаться на session.start, проверить producer === "copilot-agent", затем вызвать send.

Доступ к URL-адресу сеанса агента

Облачные сеансы по сути являются удаленными: после подключения рабочей роли сеанс публикуется в https://github.com/copilot/tasks/{sessionId} и среда выполнения выдает session.info событие с URL-адресом. Не требуется вызывать remote.enable()этот API только для синхронизации локального сеанса GitHub.

Захватите URL, подписавшись на session.info и отфильтровав по 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);
    // For example, surface in your UI as a shareable link or QR code.
  }
});

Событие запускается вскоре после session.startэтого. Если ваш рендерер монтируется после того, как событие уже сработало, сохраняйте URL вместе с записью сессии в состоянии приложения и восстанавливайтесь при повторном подключении — время выполнения не session.info повторяет работу самостоятельно.

О той же проводке в локальных сессиях, продвигаемых через remote: true, см. AUTOTITLE.

Ассоциация хранилищ

Объект cloud.repository связывает облачную сессию с репозиторием GitHub:

Поле	Обязательный	Description
`owner`	Да	Владелец репозитория или организация.
`name`	Да	Имя репозитория.
`branch`	Нет	Ветка для контекста репозитория. Опустите его, чтобы время выполнения выбрало стандартную ветку или текущий контекст репозитория.

Ассоциация репозитория необязательна в типе SDK, но включайте её, когда ваше приложение знает целевой репозиторий. Он помогает сеансу отображаться с правильным контекстом репозитория на панели агентов и дает облачному агенту более четкую отправную точку.

Используйте branch тогда, когда работа должна начинаться с определённой ветви. Если ваше приложение создаёт сессии из pull request, процессов сортировки или процессов развертывания, передайте ветку, которая соответствует видимой задаче.

Возобновление облачной сессии

Эта cloud опция применяется только при создании новой сессии. Чтобы возобновить существующую облачную сессию, используйте стандартный API resume для языка SDK:

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

Не проходите cloud снова в резюме. Метаданные сохранённой сессии определяют, что сессия поддерживается облаком, и возобновление следует обычному пути возобновления сессии.

Политики и права организации

Создание облачных сессий может провалиться, если пользователь или организация не имеют права на выполнение облачных агентов или если политики на уровне организации блокируют этот поток. В частности, политики для облачных песочниц могут мешать клиентам создавать облачную задачу.

Когда это происходит, среда выполнения сообщает "policy_blocked" о причине отказа создания облачных задач. Рассматривайте это как разрешение или результат политики, а не как временный сбой инфраструктуры.

В TypeScript проверьте причину перед повторной попыткой:

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;
}

В языках, где ошибки SDK представлены по-разному, проверьте поверхностную причину ошибки или код и обрабатывайте "policy_blocked" её явно. Ожидается, что повторная попытка без изменения политики не принесёт успеха.

Идентификатор интеграции и маршрутизация

Облачные сессии имеют заголовок Copilot-Integration-Id, полученный из переменной среды GITHUB_COPILOT_INTEGRATION_ID. Этот идентификатор интеграции используется для маршрутизации, присвоения и поведения, зависят от интеграции.

Для рекомендаций по многопользовательскому серверу и полной информации об идентификаторе интеграции см. раздел AUTOTITLE.

Созданные в пакете SDK облачные сеансы направляются в copilot-developer-sandbox слизь агента. Название является внутренним маршрутизатором для облачного агента и не означает, что сессия использует локальную песочницу Windows.

Продвинутые программы: `COPILOT_MC_BASE_URL`

По умолчанию среда выполнения наследует базовый URL-адрес сеанса агента из настроенного Copilot URL-адреса API. Задайте COPILOT_MC_BASE_URL только в том случае, если необходимо переопределить эту конечную точку сеанса.

Это может потребоваться для развертывания GitHub Enterprise Server. Проверьте правильное значение и статус поддержки с вашим представителем GitHub, прежде чем использовать это в продакшене.

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