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

了解如何使用 Copilot agent 发送合接收服务器发送事件来与 Copilot 平台进行交互。

本文内容

Note

GitHub Copilot Extensions 为 公共预览版，可能随时更改。

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

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

发送服务器发送事件

对于与 Copilot 平台的每次交互，代理应只发送一个 SSE。 代理可以发送四种预定义 SSE：

copilot_confirmation

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

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

用户接受或拒绝确认后，代理会收到类似以下示例的消息：

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

根据此消息中的值，代理可以完成或取消相应的操作。

copilot_errors

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

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

Copilot Chat in GitHub Mobile 当前不支持渲染引用。 依赖引用内存生成响应的扩展仍然有效，但不会向用户显示引用。

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

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

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

接收服务器发送事件

正如代理将 SSE 发送到 Copilot 平台一样，代理还从平台接收 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 agent 如何与 Copilot 平台通信，可以学习如何将代理与 GitHub API 集成。 请参阅“配置 Copilot 代理以与 GitHub 通信”。