Note
As GitHub Copilot Extensions estão em versão prévia pública e sujeitas a alterações.
Os Copilot agents se comunicam com a plataforma Copilot na forma de eventos enviados pelo servidor (SSEs). Em vez de esperar que a plataforma Copilot solicite uma atualização ao seu agente, ou vice-versa, você pode usar SSEs para enviar e receber atualizações de/para a plataforma em tempo real.
Para saber mais sobre SSEs, consulte Eventos enviados pelo servidor na documentação do mdn.
Enviando eventos enviados pelo servidor
Seu agente deve enviar apenas um SSE para cada interação com a plataforma Copilot. Há quatro SSEs predefinidos que seu agente pode enviar:
copilot_confirmation
O SSE copilot_confirmation envia ao usuário um prompt para confirmar uma ação. Esse SSE é enviado por meio de um tipo de evento e campo de dados. Veja o seguinte código para obter um exemplo de um SSE copilot_confirmation:
//
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",
}
}
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",
}
}
Depois que o usuário aceita ou ignora a confirmação, o agente recebe uma mensagem semelhante ao seguinte exemplo:
//
{
"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",
}
}
]
}
{
"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",
}
}
]
}
Com base nos valores dessa mensagem, o agente pode concluir ou cancelar a ação apropriada.
copilot_errors
O SSE copilot_errors envia à plataforma Copilot uma lista de erros encontrados. Esse SSE é enviado por meio de um tipo de evento e campo de dados. Veja o seguinte código para obter um exemplo de um SSE copilot_errors:
//
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"
}]
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
No momento, não há suporte para referências de renderização para Copilot Chat in GitHub Mobile. As extensões que dependem da memória de referência para gerar respostas ainda funcionarão, mas as referências não serão exibidas para o usuário.
O SSE copilot_references envia ao usuário uma lista de referências utilizadas para gerar uma resposta. Esse SSE é enviado por meio de um tipo de evento e campo de dados. Veja o seguinte código para obter um exemplo de um SSE copilot_references:
//
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",
}
}]
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 padrão
O SSE padrão envia ao usuário uma mensagem de chat geral. Esse SSE não tem nome e é enviado exclusivamente por meio de um campo de dados. Veja o código a seguir para obter um exemplo de SSE padrão:
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}]}
Receber eventos enviados pelo servidor
Assim como seu agente envia SSEs para a plataforma Copilot, ele também recebe o SSE resp_message da plataforma. Esse SSE contém uma lista de mensagens do usuário, bem como dados opcionais relacionados a cada um dos eventos de SSE que o agente pode enviar. Consulte o exemplo de código a seguir para obter um exemplo de solicitação curl para seu agente contendo uma mensagem:
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": []
}
]
}'
Próximas etapas
Agora que você entende como seu Copilot agent se comunica com a plataforma Copilot, aprenda a integrar seu agente à API GitHub. Confira "Configurar o agente do Copilot para se comunicar com o GitHub".