Manual sync of Copilot SDK docs (#61250)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: sunbrye

assets/images/help/copilot/copilot-sdk/agent-loop-architecture.png

@@ -56,15 +56,15 @@ Use an OAuth {% data variables.product.github %} App to authenticate users throu
 **How it works:**
 1. User authorizes your OAuth {% data variables.product.github %} App.
 1. Your app receives a user access token (`gho_` or `ghu_` prefix).
-1. Pass the token to the SDK via the `githubToken` option.
+1. Pass the token to the SDK via the `gitHubToken` option.
 
 **SDK configuration:**
 
 ```typescript
 import { CopilotClient } from "@github/copilot-sdk";
 
 const client = new CopilotClient({
-    githubToken: userAccessToken,  // Token from OAuth flow
+    gitHubToken: userAccessToken,  // Token from OAuth flow
     useLoggedInUser: false,        // Don't use stored CLI credentials
 });
 ```
@@ -130,7 +130,7 @@ For complete setup instructions, including provider configuration options, limit
 
 When multiple authentication methods are available, the SDK uses them in this priority order:
 
-1. **Explicit `githubToken`** — Token passed directly to the SDK constructor
+1. **Explicit `gitHubToken`** — Token passed directly to the SDK constructor
 1. **Direct API token** — `GITHUB_COPILOT_API_TOKEN` with `COPILOT_API_URL`
 1. **Environment variable tokens** — `COPILOT_GITHUB_TOKEN` → `GH_TOKEN` → `GITHUB_TOKEN`
 1. **Stored OAuth credentials** — From previous `copilot` CLI sign-in

assets/images/help/copilot/copilot-sdk/agent-loop-event-flow.png

@@ -24,7 +24,7 @@ The Microsoft Agent Framework is the unified successor to Semantic Kernel and Au
 | A2A protocol | Agent-to-Agent communication standard supported by the framework |
 
 > [!NOTE]
-> MAF integration packages are available for .NET and Python. For TypeScript and Go, use the {% data variables.copilot.copilot_sdk_short %} directly—the standard SDK APIs provide tool calling, streaming, and custom agents.
+> MAF integration packages are available for .NET and Python. For TypeScript, Go, and Java, use the {% data variables.copilot.copilot_sdk_short %} directly—the standard SDK APIs provide tool calling, streaming, and custom agents.
 
 ## Prerequisites
 
@@ -317,5 +317,7 @@ catch (AgentException ex)
 ## Further reading
 
 * [AUTOTITLE](/copilot/how-tos/copilot-sdk/sdk-getting-started)
+* [AUTOTITLE](/copilot/how-tos/copilot-sdk/use-copilot-sdk/custom-agents)
+* [AUTOTITLE](/copilot/how-tos/copilot-sdk/use-copilot-sdk/custom-skills)
 * [Microsoft Agent Framework documentation](https://learn.microsoft.com/en-us/agent-framework/agents/providers/github-copilot)
 * [Blog: Build AI Agents with GitHub Copilot SDK and Microsoft Agent Framework](https://devblogs.microsoft.com/semantic-kernel/build-ai-agents-with-github-copilot-sdk-and-microsoft-agent-framework/)

assets/images/help/copilot/copilot-sdk/agent-loop-tool-use-loop.png

@@ -144,4 +144,185 @@ unsubscribeIdle();
 
 ## Next steps
 
-To continue getting started with {% data variables.copilot.copilot_sdk_short %}, see [Build Your First Copilot-Powered App](https://github.com/github/copilot-sdk/blob/main/docs/getting-started.md#step-4-add-a-custom-tool) in the `github/copilot-sdk` repository. 
+### Add a custom tool
+
+Give {% data variables.product.prodname_copilot_short %} the ability to call your code by defining a custom tool. Here's a weather lookup tool:
+
+```typescript copy
+import { CopilotClient, defineTool } from "@github/copilot-sdk";
+
+// Define a tool that Copilot can call
+const getWeather = defineTool("get_weather", {
+    description: "Get the current weather for a city",
+    parameters: {
+        type: "object",
+        properties: {
+            city: { type: "string", description: "The city name" },
+        },
+        required: ["city"],
+    },
+    handler: async (args: { city: string }) => {
+        const { city } = args;
+        // In a real app, you'd call a weather API here
+        const conditions = ["sunny", "cloudy", "rainy", "partly cloudy"];
+        const temp = Math.floor(Math.random() * 30) + 50;
+        const condition = conditions[Math.floor(Math.random() * conditions.length)];
+        return { city, temperature: `${temp}°F`, condition };
+    },
+});
+
+const client = new CopilotClient();
+const session = await client.createSession({
+    model: "gpt-4.1",
+    streaming: true,
+    tools: [getWeather],
+});
+
+session.on("assistant.message_delta", (event) => {
+    process.stdout.write(event.data.deltaContent);
+});
+
+session.on("session.idle", () => {
+    console.log(); // New line when done
+});
+
+await session.sendAndWait({
+    prompt: "What's the weather like in Seattle and Tokyo?",
+});
+
+await client.stop();
+process.exit(0);
+```
+
+For examples in Python, Go, .NET, and Rust, see [Getting started](https://github.com/github/copilot-sdk/blob/main/docs/getting-started.md#step-4-add-a-custom-tool) in the `github/copilot-sdk` repository. {% data reusables.copilot.copilot-sdk.java-sdk-link %}
+
+When you define a tool, you're telling {% data variables.product.prodname_copilot_short %}:
+
+1. **What the tool does** (description)
+1. **What parameters it needs** (schema)
+1. **What code to run** (handler)
+
+{% data variables.product.prodname_copilot_short %} decides when to call your tool based on the user's question. When it does, the {% data variables.copilot.copilot_sdk_short %} runs your handler function and sends the result back to {% data variables.product.prodname_copilot_short %}, which incorporates it into the response.
+
+### Build an interactive assistant
+
+Combine everything into an interactive chat assistant:
+
+```typescript copy
+import { CopilotClient, defineTool } from "@github/copilot-sdk";
+import * as readline from "readline";
+
+const getWeather = defineTool("get_weather", {
+    description: "Get the current weather for a city",
+    parameters: {
+        type: "object",
+        properties: {
+            city: { type: "string", description: "The city name" },
+        },
+        required: ["city"],
+    },
+    handler: async ({ city }) => {
+        const conditions = ["sunny", "cloudy", "rainy", "partly cloudy"];
+        const temp = Math.floor(Math.random() * 30) + 50;
+        const condition = conditions[Math.floor(Math.random() * conditions.length)];
+        return { city, temperature: `${temp}°F`, condition };
+    },
+});
+
+const client = new CopilotClient();
+const session = await client.createSession({
+    model: "gpt-4.1",
+    streaming: true,
+    tools: [getWeather],
+});
+
+session.on("assistant.message_delta", (event) => {
+    process.stdout.write(event.data.deltaContent);
+});
+
+const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+});
+
+console.log("Weather Assistant (type 'exit' to quit)");
+console.log("   Try: 'What's the weather in Paris?'\n");
+
+const prompt = () => {
+    rl.question("You: ", async (input) => {
+        if (input.toLowerCase() === "exit") {
+            await client.stop();
+            rl.close();
+            return;
+        }
+
+        process.stdout.write("Assistant: ");
+        await session.sendAndWait({ prompt: input });
+        console.log("\n");
+        prompt();
+    });
+};
+
+prompt();
+```
+
+Run with:
+
+```bash copy
+npx tsx weather-assistant.ts
+```
+
+For examples in Python, Go, .NET, and Rust, see [Getting started](https://github.com/github/copilot-sdk/blob/main/docs/getting-started.md#step-5-build-an-interactive-assistant) in the `github/copilot-sdk` repository. {% data reusables.copilot.copilot-sdk.java-sdk-link %}
+
+### Connect to MCP servers
+
+MCP (Model Context Protocol) servers provide pre-built tools. Connect to {% data variables.product.github %}'s MCP server to give {% data variables.product.prodname_copilot_short %} access to repositories, issues, and pull requests:
+
+```typescript copy
+const session = await client.createSession({
+    mcpServers: {
+        github: {
+            type: "http",
+            url: "https://api.githubcopilot.com/mcp/",
+        },
+    },
+});
+```
+
+For more information, see [AUTOTITLE](/copilot/how-tos/copilot-sdk/use-copilot-sdk/mcp-servers).
+
+### Create custom agents
+
+Define specialized AI personas for specific tasks:
+
+```typescript copy
+const session = await client.createSession({
+    customAgents: [{
+        name: "pr-reviewer",
+        displayName: "PR Reviewer",
+        description: "Reviews pull requests for best practices",
+        prompt: "You are an expert code reviewer. Focus on security, performance, and maintainability.",
+    }],
+});
+```
+
+For more information, see [AUTOTITLE](/copilot/how-tos/copilot-sdk/use-copilot-sdk/custom-agents).
+
+### Customize the system message
+
+Control the AI's behavior and personality by appending instructions:
+
+```typescript copy
+const session = await client.createSession({
+    systemMessage: {
+        content: "You are a helpful assistant for our engineering team. Always be concise.",
+    },
+});
+```
+
+### Further reading
+
+* [AUTOTITLE](/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/choosing-a-setup-path)
+* [AUTOTITLE](/copilot/how-tos/copilot-sdk/use-copilot-sdk/agent-loop)
+* [Connecting to an external CLI server](https://github.com/github/copilot-sdk/blob/main/docs/getting-started.md#connecting-to-an-external-cli-server) in the `github/copilot-sdk` repository
+* [Telemetry and observability](https://github.com/github/copilot-sdk/blob/main/docs/getting-started.md#telemetry-and-observability) in the `github/copilot-sdk` repository