Copilot プラットフォームと通信するように Copilot エージェントを構成する

Copilot agent を使用してサーバー送信イベントを送受信し、Copilot プラットフォームとやり取りする方法について説明します。

この記事の内容

Note

GitHub Copilot Extensions は パブリック プレビュー 段階であり、変更される可能性があります。

Copilot agents は、サーバー送信イベント (SSE) の形式で Copilot プラットフォームと通信します。 Copilot プラットフォームがエージェントに更新プログラムを要求するのを待ったり、その逆をする代わりに、SSE を使用してプラットフォームとの間でリアルタイムで更新プログラムを送受信できます。

SSE の詳細については、mdn ドキュメントの「サーバー送信イベント」を参照してください。

サーバー送信イベントの送信

エージェントは、Copilot プラットフォームとの対話ごとに 1 つの SSE のみを送信する必要があります。 エージェントが送信できる定義済みの 4 つの 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}]}

サーバー送信イベントの受信

エージェントが 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 agent が Copilot プラットフォームと通信する方法を理解できましたので、エージェントを GitHub API と統合する方法を学習できます。 「GitHub と通信するように Copilot エージェントを構成する」をご覧ください。