配置您的 Copilot 代理以与 Copilot 平台通信

了解如何通过使用 Copilot 代理发送和接收服务器发送事件来与 Copilot 平台交互。

本文内容

注意

GitHub Copilot 扩展程序处于公开预览阶段，可能随时更改。

Copilot 代理以服务器发送事件 (SSE) 的形式与 Copilot 平台通信。无需等待 Copilot 平台请求您的代理更新，反之亦然，您可以使用 SSE 实时向平台发送和接收更新。

要了解有关 SSE 的更多信息，请参阅mdn 文档中的服务器发送事件。

发送服务器发送事件

您的代理每次与 Copilot 平台交互时应只发送一个 SSE。您的代理可以发送四个预定义的 SSE

copilot_confirmation

copilot_confirmation SSE 向用户发送提示以确认操作。此 SSE 通过事件类型和数据字段发送。有关copilot_confirmation SSE 的示例，请参见以下代码

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

目前，在copilot_confirmation中，type仅支持action值。

    "title": "Turn off feature flag",

显示给用户的确认对话框的标题。

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

显示给用户的确认消息。

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

可选字段，代理可以在其中包含任何需要唯一标识此确认并在一旦从客户端收到决定后采取行动所需的数据。

//
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",
    }
}

用户接受或驳回确认后，代理会收到类似于以下示例的消息

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

包含确认状态的字符串。此值是accepted或dismissed。

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

包含用于标识相关操作的数据的字符串数组。

//
{
    "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_errors

copilot_errors SSE 向 Copilot 平台发送遇到的错误列表。此 SSE 通过事件类型和数据字段发送。有关copilot_errors SSE 的示例，请参见以下代码

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

指定错误类型的字符串。type的值可以是reference、function或agent。

    "code": "recentchanges",

代理控制的字符串，描述错误的性质。

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

指定显示给用户的错误消息的字符串。

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

用作唯一标识符的字符串，用于将错误与其他资源（例如引用或函数调用）关联。

//
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

注意

GitHub 移动端中的 Copilot 聊天目前不支持渲染引用。依赖于引用内存生成响应的扩展程序仍然可以工作，但不会向用户显示引用。

copilot_references SSE 向用户发送用于生成响应的引用列表。此 SSE 通过事件类型和数据字段发送。有关copilot_references SSE 的示例，请参见以下代码

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

指定引用类型的字符串。

    "id": "snippet",

指定引用 ID 的字符串。

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

可选字段，代理可以在其中包含任何需要唯一标识此引用的数据。

    "is_implicit": false,

可选布尔值，指示引用是隐式传递还是显式传递。

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

可选字段，代理可以在其中包含任何要在用户环境中显示的元数据。如果缺少以下任何必需字段，则不会在 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

默认 SSE 向用户发送常规聊天消息。此 SSE 未命名，仅通过数据字段发送。有关默认 SSE 的示例，请参见以下代码

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

接收服务器发送事件

正如您的代理向 Copilot 平台发送 SSE 一样，它也会从平台接收resp_message SSE。此 SSE 包含来自用户的邮件列表，以及与代理可以发送的每个 SSE 事件相关的可选数据。有关包含消息的代理的示例 curl 请求，请参见以下代码示例

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": []
            }
        ]
    }'

后续步骤

现在您已经了解了 Copilot 代理如何与 Copilot 平台通信，您可以学习如何将您的代理与 GitHub API 集成。请参阅“配置您的 Copilot 代理以与 GitHub 通信”。