Skip to main content

Configuración del agente de Copilot para comunicarse con la plataforma de Copilot

Obtenga información sobre cómo interactuar con la plataforma de Copilot mediante el envío y recepción de eventos enviados por el servidor con su Copilot agent.

Note

GitHub Copilot Extensions se encuentra en versión preliminar pública y está sujeto a cambios.

Copilot agents se comunican con la plataforma de Copilot en forma de eventos enviados por el servidor (SSE). En lugar de esperar a que la plataforma de Copilot, solicite una actualización del agente, o viceversa, puede usar SSE para enviar y recibir actualizaciones hacia y desde la plataforma en tiempo real.

Para obtener más información sobre los SSE, consulte Eventos enviados por el servidor en la documentación de mdn.

Envío de eventos enviados por el servidor

El agente solo debe enviar un SSE para cada interacción con la plataforma de Copilot. Hay cuatro SSE predefinidos que el agente puede enviar:

copilot_confirmation

El SSE de copilot_confirmation envía al usuario un mensaje para confirmar una acción. Este SSE se envía a través de un tipo de evento y un campo de datos. El siguiente código es un ejemplo de un SSE de copilot_confirmation:

TypeScript
event: copilot_confirmation
data: {
    "type": "action",

Currently, action is the only supported value for type in copilot_confirmation.

    "title": "Turn off feature flag",

Title of the confirmation dialog shown to the user.

    "message": "Are you sure you wish to turn off the `copilot` feature flag?",

Confirmation message shown to the user.

    "confirmation": {
        "id": "id-123",
        "other": "identifier-as-needed",
    }
}

Optional field for the agent to include any data needed to uniquely identify this confirmation and take action once the decision is received from the client.

//
event: copilot_confirmation
data: {
    // Currently, `action` is the only supported value for `type` in `copilot_confirmation`.
    "type": "action",
    // Title of the confirmation dialog shown to the user.
    "title": "Turn off feature flag",
    // Confirmation message shown to the user.
    "message": "Are you sure you wish to turn off the `copilot` feature flag?",
    // Optional field for the agent to include any data needed to uniquely identify this confirmation and take action once the decision is received from the client.
    "confirmation": {
        "id": "id-123",
        "other": "identifier-as-needed",
    }
}

Una vez que el usuario acepta o descarta la confirmación, el agente recibe un mensaje similar al ejemplo siguiente:

TypeScript
{
    "copilot_confirmations": [
        {
            "state": "accepted",

A string containing the state of the confirmation. This value is either accepted or dismissed.

            "confirmation": {
                "id": "id-123",
                "other": "identifier-as-needed",
            }
        }
    ]
}

An array of strings containing data identifying the relevant action.

//
{
    "copilot_confirmations": [
        {
            // A string containing the state of the confirmation. This value is either `accepted` or `dismissed`.
            "state": "accepted",
            // An array of strings containing data identifying the relevant action.
            "confirmation": {
                "id": "id-123",
                "other": "identifier-as-needed",
            }
        }
    ]
}

En función de los valores de este mensaje, el agente puede completar o cancelar la acción adecuada.

copilot_errors

El SSE de copilot_errors envía a la plataforma de Copilot una lista de errores detectados. Este SSE se envía a través de un tipo de evento y un campo de datos. El siguiente código es un ejemplo de un SSE de copilot_errors:

TypeScript
event: copilot_errors
data: [{
    "type": "function",

A string that specifies the error's type. type can have a value of reference, function or agent.

    "code": "recentchanges",

A string controlled by the agent describing the nature of an error.

    "message": "The repository does not exist",

A string that specifies the error message shown to the user.

    "identifier": "github/hello-world"
}]

A string that serves as a unique identifier to link the error with other resources such as references or function calls.

//
event: copilot_errors
data: [{
    // A string that specifies the error's type. `type` can have a value of `reference`, `function` or `agent`.
    "type": "function",
    // A string controlled by the agent describing the nature of an error.
    "code": "recentchanges",
    // A string that specifies the error message shown to the user.
    "message": "The repository does not exist",
    // A string that serves as a unique identifier to link the error with other resources such as references or function calls.
    "identifier": "github/hello-world"
}]

copilot_references

Note

Actualmente no se pueden representar referencias en Copilot Chat in GitHub Mobile. Las extensiones que dependen de la memoria de referencia para generar respuestas seguirán funcionando, pero las referencias no se mostrarán al usuario.

El SSE de copilot_references envía al usuario una lista de referencias usadas para generar una respuesta. Este SSE se envía a través de un tipo de evento y un campo de datos. El siguiente código es un ejemplo de un SSE de copilot_references:

TypeScript
event: copilot_references
data: [{
    "type": "blackbeard.story",

A string that specifies the type of the reference.

    "id": "snippet",

A string that specifies the ID of the reference.

    "data": {
        "file": "story.go",
        "start": "0",
        "end": "13",
        "content": "func main()...writeStory()..."
    },

An optional field where the agent can include any data needed to uniquely identify this reference.

    "is_implicit": false,

An optional boolean that indicates if the reference was passed implicitly or explicitly.

    "metadata": {
        "display_name": "Lines 1-13 from story.go",
        "display_icon": "icon",
        "display_url": "http://blackbeard.com/story/1",
    }
}]

An optional field for the agent to include any metadata to display in the user's environment. If any of the below required fields are missing, then the reference will not be rendered in the UI.

//
event: copilot_references
data: [{
    // A string that specifies the type of the reference.
    "type": "blackbeard.story",
    // A string that specifies the ID of the reference.
    "id": "snippet",
    // An optional field where the agent can include any data needed to uniquely identify this reference.
    "data": {
        "file": "story.go",
        "start": "0",
        "end": "13",
        "content": "func main()...writeStory()..."
    },
    // An optional boolean that indicates if the reference was passed implicitly or explicitly.
    "is_implicit": false,
    // An optional field for the agent to include any metadata to display in the user's environment. If any of the below required fields are missing, then the reference will not be rendered in the UI.
    "metadata": {
        "display_name": "Lines 1-13 from story.go",
        "display_icon": "icon",
        "display_url": "http://blackbeard.com/story/1",

    }
}]

SSE predeterminado

El SSE predeterminado envía al usuario un mensaje de chat general. Este SSE no tiene nombre y se envía únicamente a través de un campo de datos. El siguiente código es un ejemplo de un SSE predeterminado:

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-3.5-turbo-0125", "system_fingerprint": "fp_44709d6fcb", "choices":[{"index":0,"delta":{"role":"assistant","content":""},"logprobs":null,"finish_reason":null}]}

Recepción de eventos enviados por el servidor

Al igual que el agente envía SSE a la plataforma de Copilot, también recibe el SSE de resp_message de la plataforma. Este SSE contiene una lista de mensajes del usuario, así como datos opcionales relacionados con cada uno de los eventos SSE que puede enviar el agente. Consulte el ejemplo de código siguiente para obtener una solicitud curl de ejemplo al agente que contiene un mensaje:

curl --request POST \
    --url $AGENT_URL \
    --header 'Accept: application/json' \
    --header 'Content-Type: application/json' \
    --header "X-GitHub-Token: $RUNTIME_GENERATED_TOKEN" \
    --data '{
        "messages": [
            {
                "role": "user",
                "content": "What is a closure in javascript?",
                "copilot_references": []
            }
        ]
    }'

Pasos siguientes

Ahora que comprende cómo Copilot agent comunica con la plataforma de Copilot, puede aprender a integrar el agente con la API GitHub. Consulte "Configuración del agente de Copilot para comunicarse con GitHub".