Skip to main content

Passagem de contexto para seu agente

Saiba como usar a passagem de contexto com seu Copilot agent.

Sobre a passagem de contexto

As GitHub Copilot Extensions podem acessar determinadas informações contextuais usando a passagem de contexto. A passagem de contexto permite que os agentes recebam detalhes relevantes sobre o arquivo atual de um usuário, o texto selecionado e o repositório. Isso ocorre automaticamente quando você interage com uma extensão, mas requer sua autorização explícita por meio de permissões do GitHub App para uso em repositórios de propriedade da organização.

Clientes diferentes, como o GitHub Copilot Chat no Visual Studio Code, o Visual Studio e o GitHub, fornecem contexto por meio de diferentes tipos de referência. Por exemplo, IDEs enviam informações como conteúdo de arquivo e seleções, enquanto o Copilot Chat in GitHub inclui a URL atual da página que está sendo exibida.

Pré-requisitos

Antes de configurar seu Copilot agent para se comunicar com o GitHub, você deve entender como seu Copilot agent se comunica com a plataforma Copilot. Confira Configurar o agente do Copilot para se comunicar com a plataforma Copilot.

Noções básicas sobre a passagem de contexto

A passagem de contexto permite que os agentes recebam informações sobre o workspace ativo do usuário. Seu agente recebe SSEs (eventos enviados pelo servidor) que contêm uma lista de mensagens do usuário, bem como referências ao ambiente atual do usuário. Dependendo do cliente, diferentes tipos de contexto são fornecidos.

A tabela a seguir mostra os tipos de referência passados para GitHub Copilot Extensions com base no cliente ou no IDE que você está usando.

Cliente ou IDEclient.fileclient.selectiongithub.repositorygithub.current-urlContextos adicionais
Visual Studio CodeSimSimSimNãoProprietário do repositório e branch
Visual Studio.SimSimSimNãoProprietário do repositório e branch
GitHub.comNãoNãoSimSimInformações do repositório e outros recursos do GitHub

Tipos de referência para Copilot Chat em IDEs

Os seguintes tipos de referência podem ser passados para seu agente de um IDE:

  • client.file: representa o conteúdo completo do arquivo ativo no momento no IDE.
  • client.selection: representa a parte selecionada do texto realçado pelo usuário no arquivo ativo.
  • github.repository: fornece informações sobre o repositório ativo.

Tipos de referência para Copilot Chat in GitHub

Os seguintes tipos de referência podem ser passados para seu agente do GitHub:

  • github.current-url: representa a URL da página do GitHub atual que o usuário está exibindo.
  • github.repository: fornece informações sobre o repositório ativo.

Referências de exemplo

O seguinte código mostra um exemplo da objeto para client.file:

{
    // The reference type.
    "type": "client.file",
    "data": {
        // The full content of the active file. 
        "content": "Lorem ipsum dolor sit amet, consectetur adipiscing elit",
        "language": "plaintext"
    },
    "id": "relative-path/to/file",
    // `is_implicit` indicates whether the reference was automatically provided by the client (true) or manually attached by the user (false).
    "is_implicit": true,
    "metadata": {
        "display_name": "https://github.com/example-user/example-repository",
        "display_icon": "",
        "display_url": ""
    }
}

O seguinte código mostra um exemplo da objeto para client.selection:

{
    // The reference type.
    "type": "client.selection",
    "data": {
        // The currently selected portion of text.
        "content": "<current selection>",
        "end": {
            "col": 80,
            "line": 10
        },
        "start": {
            "col": 0,
            "line": 0
        }
    },
    "id": "relative-path/to/file",
    // `is_implicit` indicates whether the reference was automatically provided by the client (true) or manually attached by the user (false).
    "is_implicit": true,
    "metadata": {
        "display_name": "https://github.com/example-user/example-repository",
        "display_icon": "",
        "display_url": ""
    }
}

O seguinte código mostra um exemplo da objeto para github.repository:

{
    // The reference type.
    "type": "github.repository",
    "data": {
        "type": "repository",
        "id": "abc-123",
        "name": "example-repository",
        "ownerLogin": "example-user",
        "ownerType": "",
        "readmePath": "",
        "description": "",
        "commitOID": "",
        "ref": "",
        "refInfo": {
            "name": "",
            "type": ""
        },
        "visibility": "",
        "languages": null
    },
    "id": "example-user/example-repository",
    // `is_implicit` is always false for github.repository.
    "is_implicit": false,
    "metadata": {
        "display_name": "https://github.com/example-user/example-repository",
        "display_icon": "",
        "display_url": ""
    }
}

O seguinte código mostra um exemplo da objeto para github.current-url:

{
    // The reference type.
    "type": "github.current-url",
    "data": {
        // The GitHub URL the user was on while chatting with the agent.
        "url": "https://github.com/example-user/example-repository"
    },
    "id": "https://github.com/example-user/example-repository",
    // `is_implicit` is always true for github.current-url.
    "is_implicit": true,
    "metadata": {
        "display_name": "https://github.com/example-user/example-repository",
        "display_icon": "",
        "display_url": ""
    }
}

Configurando a passagem de contexto

Para habilitar a passagem de contexto por meio de um cliente do IDE, a permissão Copilot Editor Context precisa ser configurada para o agente. Essa permissão controla apenas o acesso para os tipos de referência client.file e client.selection. Usuários que instalam e usam o agente serão informados claramente de que o agente tem acesso de leitura ao Contexto de Editor do Copilot, que inclui conteúdo como o arquivo ativo e a seleção atual.

github.current-url e github.repository não são afetados pelo Contexto do Editor do Copilot. Esses tipos de referência dependem da filtragem de autorização para garantir que agentes de terceiros recebam apenas referências às quais têm acesso. Para saber como gerenciar a privacidade de github.current-url e github.repository, confira Controles de privacidade.

Siga estas etapas para definir as permissões necessárias para a passagem de contexto de IDEs para seu agente:

  1. No canto superior direito de qualquer página do GitHub, clique na foto do seu perfil.
  2. Acesse as configurações da sua conta.
    • Para um aplicativo de propriedade de uma conta pessoal, clique em Configurações.
    • Para um aplicativo de propriedade de uma organização:
      1. Clique em Suas organizações.
      2. À direita da organização, clique em Configurações.
  3. Na barra lateral esquerda, clique em Configurações do desenvolvedor.
  4. Na barra lateral esquerda, clique em GitHub Apps .
  5. Na lista de GitHub Apps, clique no GitHub App que deseja configurar para a passagem de contexto.
  6. No menu de navegação à esquerda, selecione Permissions & events.
  7. Em Account Permissions, selecione o acesso Read-only para Copilot Editor Context.

Controles de privacidade

Nos casos em que não deseja compartilhar determinados detalhes de contexto com o agente, você pode editar e remover tipos de referência de várias maneiras.

Chat nos IDEs

  • Se um agente não tiver a permissão de acesso de leitura no Contexto do Editor do Copilot, todas as referências client.* serão removidas.
  • Se um agente não tiver acesso de leitura a um repositório, todas as referências client.* serão removidas, e a referência github.repository será editada.

Note

O Visual Studio e o Visual Studio Code fornecem uma opção para excluir o conteúdo do arquivo atual. Os tipos de referência client.* serão removidos se o usuário tiver excluído o conteúdo do arquivo atual.

Chat no GitHub

  • Se um agente não tiver acesso de leitura ao repositório associado à URL GitHub atual, as referências github.current-url e github.repository serão editadas.
  • Se as informações do repositório não puderem ser extraídas da URL do GitHub atual, github.current-url será editado.

Referências editadas

Quando uma referência é editada devido a permissões insuficientes, ela é substituída por um espaço reservado que indica o tipo de informação que foi excluída. No exemplo a seguir, o campo type indica que a referência foi editada, e o campo data.type revela o tipo de referência original.

{
    "role": "user",
    "content": "Current Date and Time (UTC): 2024-10-22 00:43:14\nCurrent User's Login: monalisa\n",
    "name": "_session",
    "copilot_references": [
        {
            "type": "github.redacted",
            "data": {
                "type": "github.current-url"
            },
            "id": "example-id",
            "is_implicit": true,
            "metadata": {
                "display_name": "",
                "display_icon": "",
                "display_url": ""
            }
        }
    ],
    "copilot_confirmations": null
}

Exclusões de contexto

Para proteger informações confidenciais, determinados cenários impedem automaticamente a passagem de contexto para os agentes. Se uma organização tiver definido regras de exclusão de conteúdo para o Copilot, os arquivos que se enquadram nessas regras não serão incluídos no contexto passado aos agentes.

Para saber mais sobre as regras de exclusão de conteúdo, confira Como realizar a exclusão de conteúdo do GitHub Copilot.

Arquivos grandes

Arquivos que excedem o limite de tamanho definido pelo cliente não serão enviados. A referência incluirá metadados que indicam que o arquivo era muito grande para ser processado.

Arquivos ocultos

Arquivos que começam com um ponto, como .env e .config, são excluídos por padrão para impedir o compartilhamento não intencional de configurações confidenciais. No VS Code, você pode especificar arquivos ou diretórios em um arquivo .copilotignore para impedir que eles sejam enviados para agentes do Copilot. Esse mecanismo do lado do cliente oferece controle granular sobre quais arquivos são excluídos.