Skip to content

Commit f42a436

Browse files
github-actions[bot]github-actions[bot]
committed
Deploy documentation: v1.0.4
1 parent 2d21483 commit f42a436

648 files changed

Lines changed: 62346 additions & 2757 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎1.0.4/advanced.html‎

Lines changed: 324 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,324 @@
1+
<!DOCTYPE html>
2+
3+
4+
<!--
5+
| Generated by Apache Maven Doxia Site Renderer 2.0.0 from target/filtered-site/markdown/advanced.md at 2026-01-27
6+
| Rendered using Apache Maven Fluido Skin 2.1.0
7+
-->
8+
<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
9+
<head>
10+
<meta charset="UTF-8" />
11+
<meta name="viewport" content="width=device-width, initial-scale=1" />
12+
<meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0" />
13+
<title>Advanced Usage – GitHub Copilot Community SDK :: Java</title>
14+
<link rel="stylesheet" href="./css/apache-maven-fluido-2.1.0.min.css" />
15+
<link rel="stylesheet" href="./css/site.css" />
16+
<link rel="stylesheet" href="./css/print.css" media="print" />
17+
<script src="./js/apache-maven-fluido-2.1.0.min.js"></script>
18+
<style>.github-fork-ribbon:before { background-color: gray; }</style>
19+
</head>
20+
<body class="topBarEnabled">
21+
<a class="github-fork-ribbon right-top" href="https://github.com/copilot-community-sdk/copilot-sdk-java" data-ribbon="Fork me on GitHub">Fork me on GitHub</a>
22+
<header id="topbar" class="navbar navbar-fixed-top ">
23+
<div class="navbar-inner">
24+
<div class="container-fluid">
25+
<a data-target=".nav-collapse" data-toggle="collapse" class="btn btn-navbar">
26+
<span class="icon-bar"></span>
27+
<span class="icon-bar"></span>
28+
<span class="icon-bar"></span>
29+
</a>
30+
<a class="brand" href="index.html">GitHub Copilot SDK for Java
31+
</a>
32+
<ul class="nav">
33+
<li class="dropdown">
34+
<a class="dropdown-toggle" data-toggle="dropdown">Overview <b class="caret"></b></a>
35+
<ul class="dropdown-menu">
36+
<li><a href="index.html">Introduction</a></li>
37+
<li><a href="getting-started.html">Getting Started</a></li>
38+
<li><a href="documentation.html">Documentation</a></li>
39+
<li><a href="mcp.html">MCP Servers</a></li>
40+
<li><a>Advanced Usage</a></li>
41+
<li><a href="apidocs/index.html">API Javadoc</a></li>
42+
</ul>
43+
</li>
44+
<li class="dropdown">
45+
<a class="dropdown-toggle" data-toggle="dropdown">Guides <b class="caret"></b></a>
46+
<ul class="dropdown-menu">
47+
<li><a href="documentation.html#Basic_Usage">Basic Usage</a></li>
48+
<li><a href="documentation.html#Handling_Responses">Handling Responses</a></li>
49+
<li><a href="documentation.html#Streaming_Responses">Streaming</a></li>
50+
<li><a href="documentation.html#Choosing_a_Model">Choosing a Model</a></li>
51+
<li><a href="documentation.html#Session_Management">Session Management</a></li>
52+
</ul>
53+
</li>
54+
<li class="dropdown">
55+
<a class="dropdown-toggle" data-toggle="dropdown">Advanced <b class="caret"></b></a>
56+
<ul class="dropdown-menu">
57+
<li><a href="advanced.html#Custom_Tools">Custom Tools</a></li>
58+
<li><a href="advanced.html#System_Messages">System Messages</a></li>
59+
<li><a href="advanced.html#File_Attachments">File Attachments</a></li>
60+
<li><a href="advanced.html#Bring_Your_Own_Key_.28BYOK.29">BYOK</a></li>
61+
<li><a href="advanced.html#Infinite_Sessions">Infinite Sessions</a></li>
62+
<li><a href="advanced.html#MCP_Servers">MCP Servers</a></li>
63+
</ul>
64+
</li>
65+
<li class="dropdown">
66+
<a class="dropdown-toggle" data-toggle="dropdown">Project Documentation <b class="caret"></b></a>
67+
<ul class="dropdown-menu">
68+
<li class="dropdown-submenu">
69+
<a href="project-info.html">Project Information</a>
70+
<ul class="dropdown-menu">
71+
<li><a href="dependencies.html">Dependencies</a></li>
72+
<li><a href="dependency-info.html">Maven Coordinates</a></li>
73+
<li><a href="index.html">About</a></li>
74+
<li><a href="licenses.html">Licenses</a></li>
75+
<li><a href="plugin-management.html">Plugin Management</a></li>
76+
<li><a href="plugins.html">Plugins</a></li>
77+
<li><a href="scm.html">Source Code Management</a></li>
78+
<li><a href="summary.html">Summary</a></li>
79+
<li><a href="team.html">Team</a></li>
80+
</ul>
81+
</li>
82+
<li class="dropdown-submenu">
83+
<a href="project-reports.html">Project Reports</a>
84+
<ul class="dropdown-menu">
85+
<li><a href="apidocs/index.html">Javadoc</a></li>
86+
</ul>
87+
</li>
88+
</ul>
89+
</li>
90+
</ul>
91+
</div>
92+
</div>
93+
</header>
94+
<div class="container-fluid container-fluid-top">
95+
<header>
96+
<div id="banner">
97+
<div class="pull-left"></div>
98+
<div class="pull-right"></div>
99+
<div class="clear"><hr/></div>
100+
</div>
101+
102+
<div id="breadcrumbs">
103+
<ul class="breadcrumb">
104+
<li id="publishDate">Last Published: 2026-01-27<span class="divider">|</span>
105+
</li>
106+
<li id="projectVersion">Version: 1.0.4<span class="divider">|</span></li>
107+
<li><a href="index.html">Home</a><span class="divider">/</span></li>
108+
<li class="active">Advanced Usage</li>
109+
</ul>
110+
</div>
111+
</header>
112+
<div class="row-fluid">
113+
<header id="leftColumn" class="span2">
114+
<nav class="well sidebar-nav">
115+
<ul class="nav nav-list">
116+
<li class="nav-header">Overview</li>
117+
<li><a href="index.html">Introduction</a></li>
118+
<li><a href="getting-started.html">Getting Started</a></li>
119+
<li><a href="documentation.html">Documentation</a></li>
120+
<li><a href="mcp.html">MCP Servers</a></li>
121+
<li class="active"><a>Advanced Usage</a></li>
122+
<li><a href="apidocs/index.html">API Javadoc</a></li>
123+
<li class="nav-header">Guides</li>
124+
<li><a href="documentation.html#Basic_Usage">Basic Usage</a></li>
125+
<li><a href="documentation.html#Handling_Responses">Handling Responses</a></li>
126+
<li><a href="documentation.html#Streaming_Responses">Streaming</a></li>
127+
<li><a href="documentation.html#Choosing_a_Model">Choosing a Model</a></li>
128+
<li><a href="documentation.html#Session_Management">Session Management</a></li>
129+
<li class="nav-header">Advanced</li>
130+
<li><a href="advanced.html#Custom_Tools">Custom Tools</a></li>
131+
<li><a href="advanced.html#System_Messages">System Messages</a></li>
132+
<li><a href="advanced.html#File_Attachments">File Attachments</a></li>
133+
<li><a href="advanced.html#Bring_Your_Own_Key_.28BYOK.29">BYOK</a></li>
134+
<li><a href="advanced.html#Infinite_Sessions">Infinite Sessions</a></li>
135+
<li><a href="advanced.html#MCP_Servers">MCP Servers</a></li>
136+
<li class="nav-header">Project Documentation</li>
137+
<li><a href="project-info.html"><span class="icon-chevron-right"></span>Project Information</a></li>
138+
<li><a href="project-reports.html"><span class="icon-chevron-right"></span>Project Reports</a></li>
139+
</ul>
140+
</nav>
141+
<div class="well sidebar-nav">
142+
<div id="poweredBy">
143+
<div class="clear"></div>
144+
<div class="clear"></div>
145+
<a href="https://maven.apache.org/" class="builtBy" target="_blank"><img class="builtBy" alt="Built by Maven" src="./images/logos/maven-feather.png" /></a>
146+
</div>
147+
</div>
148+
</header>
149+
<main id="bodyColumn" class="span10">
150+
<section><a id="Advanced_Usage"></a>
151+
<h1>Advanced Usage</h1>
152+
<blockquote>
153+
154+
<p>&#x26a0;&#xfe0f; <strong>Disclaimer:</strong> This is an <strong>unofficial, community-driven SDK</strong> and is <strong>not supported or endorsed by GitHub</strong>. Use at your own risk.</p>
155+
</blockquote>
156+
<p>This guide covers advanced scenarios for extending and customizing your Copilot integration.</p><hr /><section><a id="Custom_Tools"></a>
157+
<h2>Custom Tools</h2>
158+
<p>Let the AI call back into your application to fetch data or perform actions.</p>
159+
160+
<pre class="prettyprint"><code class="language-java">// Define strongly-typed arguments with a record
161+
record IssueArgs(String id) {}
162+
163+
var lookupTool = ToolDefinition.create(
164+
&quot;lookup_issue&quot;,
165+
&quot;Fetch issue details from our tracker&quot;,
166+
Map.of(
167+
&quot;type&quot;, &quot;object&quot;,
168+
&quot;properties&quot;, Map.of(
169+
&quot;id&quot;, Map.of(&quot;type&quot;, &quot;string&quot;, &quot;description&quot;, &quot;Issue identifier&quot;)
170+
),
171+
&quot;required&quot;, List.of(&quot;id&quot;)
172+
),
173+
invocation -&gt; {
174+
IssueArgs args = invocation.getArgumentsAs(IssueArgs.class);
175+
return CompletableFuture.completedFuture(fetchIssue(args.id()));
176+
}
177+
);
178+
179+
var session = client.createSession(
180+
new SessionConfig()
181+
.setTools(List.of(lookupTool))
182+
).get();
183+
</code></pre>
184+
<p>See <a href="apidocs/com/github/copilot/sdk/ToolDefinition.html">ToolDefinition</a> Javadoc for schema details.</p><hr /></section><section><a id="System_Messages"></a>
185+
<h2>System Messages</h2>
186+
<p>Customize the AI's behavior by adding rules or replacing the default prompt.</p><section><a id="Adding_Rules"></a>
187+
<h3>Adding Rules</h3>
188+
<p>Use <code>APPEND</code> mode to add constraints while keeping default guardrails:</p>
189+
190+
<pre class="prettyprint"><code class="language-java">var session = client.createSession(
191+
new SessionConfig()
192+
.setSystemMessage(new SystemMessageConfig()
193+
.setMode(SystemMessageMode.APPEND)
194+
.setContent(&quot;&quot;&quot;
195+
&lt;rules&gt;
196+
- Always check for security vulnerabilities
197+
- Suggest performance improvements
198+
&lt;/rules&gt;
199+
&quot;&quot;&quot;))
200+
).get();
201+
</code></pre></section><section><a id="Full_Control"></a>
202+
<h3>Full Control</h3>
203+
<p>Use <code>REPLACE</code> mode for complete control (removes default guardrails):</p>
204+
205+
<pre class="prettyprint"><code class="language-java">var session = client.createSession(
206+
new SessionConfig()
207+
.setSystemMessage(new SystemMessageConfig()
208+
.setMode(SystemMessageMode.REPLACE)
209+
.setContent(&quot;You are a helpful coding assistant.&quot;))
210+
).get();
211+
</code></pre><hr /></section></section><section><a id="File_Attachments"></a>
212+
<h2>File Attachments</h2>
213+
<p>Include files as context for the AI to analyze.</p>
214+
215+
<pre class="prettyprint"><code class="language-java">session.send(new MessageOptions()
216+
.setPrompt(&quot;Review this file for bugs&quot;)
217+
.setAttachments(List.of(
218+
new Attachment()
219+
.setType(&quot;file&quot;)
220+
.setPath(&quot;/path/to/file.java&quot;)
221+
.setDisplayName(&quot;MyService.java&quot;)
222+
))
223+
).get();
224+
</code></pre><hr /></section><section><a id="Bring_Your_Own_Key_.28BYOK.29"></a>
225+
<h2>Bring Your Own Key (BYOK)</h2>
226+
<p>Use your own OpenAI or Azure OpenAI API key instead of GitHub Copilot.</p>
227+
228+
<pre class="prettyprint"><code class="language-java">var session = client.createSession(
229+
new SessionConfig()
230+
.setProvider(new ProviderConfig()
231+
.setType(&quot;openai&quot;)
232+
.setBaseUrl(&quot;https://api.openai.com/v1&quot;)
233+
.setApiKey(&quot;sk-...&quot;))
234+
).get();
235+
</code></pre><hr /></section><section><a id="Infinite_Sessions"></a>
236+
<h2>Infinite Sessions</h2>
237+
<p>Run long conversations without hitting context limits.</p>
238+
<p>When enabled (default), the session automatically compacts older messages as the context window fills up.</p>
239+
240+
<pre class="prettyprint"><code class="language-java">var session = client.createSession(
241+
new SessionConfig()
242+
.setInfiniteSessions(new InfiniteSessionConfig()
243+
.setEnabled(true)
244+
.setBackgroundCompactionThreshold(0.80) // Start compacting at 80%
245+
.setBufferExhaustionThreshold(0.95)) // Block at 95%
246+
).get();
247+
248+
// Access the workspace where session state is persisted
249+
String workspace = session.getWorkspacePath();
250+
</code></pre>
251+
<p>For short conversations, disable to avoid overhead:</p>
252+
253+
<pre class="prettyprint"><code class="language-java">new InfiniteSessionConfig().setEnabled(false)
254+
</code></pre><hr /></section><section><a id="MCP_Servers"></a>
255+
<h2>MCP Servers</h2>
256+
<p>Extend the AI with external tools via the Model Context Protocol.</p>
257+
258+
<pre class="prettyprint"><code class="language-java">Map&lt;String, Object&gt; server = Map.of(
259+
&quot;type&quot;, &quot;local&quot;,
260+
&quot;command&quot;, &quot;npx&quot;,
261+
&quot;args&quot;, List.of(&quot;-y&quot;, &quot;@modelcontextprotocol/server-filesystem&quot;, &quot;/tmp&quot;),
262+
&quot;tools&quot;, List.of(&quot;*&quot;)
263+
);
264+
265+
var session = client.createSession(
266+
new SessionConfig()
267+
.setMcpServers(Map.of(&quot;filesystem&quot;, server))
268+
).get();
269+
</code></pre>
270+
<p>&#x1f4d6; <strong><a href="mcp.html">Full MCP documentation &#x2192;</a></strong> for local/remote servers and all options.</p><hr /></section><section><a id="Permission_Handling"></a>
271+
<h2>Permission Handling</h2>
272+
<p>Approve or deny permission requests from the AI.</p>
273+
274+
<pre class="prettyprint"><code class="language-java">var session = client.createSession(
275+
new SessionConfig()
276+
.setOnPermissionRequest((request, invocation) -&gt; {
277+
// Inspect request and approve/deny
278+
var result = new PermissionRequestResult();
279+
result.setKind(&quot;user-approved&quot;);
280+
return CompletableFuture.completedFuture(result);
281+
})
282+
).get();
283+
</code></pre><hr /></section><section><a id="Manual_Server_Control"></a>
284+
<h2>Manual Server Control</h2>
285+
<p>Control the CLI lifecycle yourself instead of auto-start.</p>
286+
287+
<pre class="prettyprint"><code class="language-java">var client = new CopilotClient(
288+
new CopilotClientOptions().setAutoStart(false)
289+
);
290+
291+
client.start().get(); // Start manually
292+
// ... use client ...
293+
client.stop().get(); // Stop manually
294+
</code></pre><hr /></section><section><a id="Error_Handling"></a>
295+
<h2>Error Handling</h2>
296+
<p>All SDK methods return <code>CompletableFuture</code>. Errors surface via <code>ExecutionException</code>:</p>
297+
298+
<pre class="prettyprint"><code class="language-java">try {
299+
session.send(new MessageOptions().setPrompt(&quot;Hello&quot;)).get();
300+
} catch (ExecutionException ex) {
301+
System.err.println(&quot;Error: &quot; + ex.getCause().getMessage());
302+
}
303+
</code></pre>
304+
<p>For reactive error handling, use <code>exceptionally()</code> or <code>handle()</code>:</p>
305+
306+
<pre class="prettyprint"><code class="language-java">session.send(new MessageOptions().setPrompt(&quot;Hello&quot;))
307+
.exceptionally(ex -&gt; {
308+
System.err.println(&quot;Failed: &quot; + ex.getMessage());
309+
return null;
310+
});
311+
</code></pre></section></section> </main>
312+
</div>
313+
</div>
314+
<hr/>
315+
<footer>
316+
<div class="container-fluid">
317+
<div class="row-fluid">
318+
<p>© 2026
319+
</p>
320+
</div>
321+
</div>
322+
</footer>
323+
</body>
324+
</html>

0 commit comments

Comments
 (0)