Skip to content

Commit 20a0398

Browse files
github-actions[bot]github-actions[bot]
committed
Deploy documentation: snapshot
1 parent b8dfbc5 commit 20a0398

524 files changed

Lines changed: 7460 additions & 2666 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.

‎snapshot/advanced.html‎

Lines changed: 168 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33

44
<!--
5-
| Generated by Apache Maven Doxia Site Renderer 2.0.0 from target/filtered-site/markdown/advanced.md at 2026-03-22
5+
| Generated by Apache Maven Doxia Site Renderer 2.0.0 from target/filtered-site/markdown/advanced.md at 2026-03-25
66
| Rendered using Apache Maven Fluido Skin 2.1.0
77
-->
88
<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
@@ -121,7 +121,7 @@
121121

122122
<div id="breadcrumbs">
123123
<ul class="breadcrumb">
124-
<li id="publishDate">Last Published: 2026-03-22<span class="divider">|</span>
124+
<li id="publishDate">Last Published: 2026-03-25<span class="divider">|</span>
125125
</li>
126126
<li id="projectVersion">Version: 0.1.33-java.0-SNAPSHOT<span class="divider">|</span></li>
127127
<li><a href="index.html">Home</a><span class="divider">/</span></li>
@@ -187,15 +187,22 @@ <h2>Table of Contents</h2>
187187
<ul>
188188

189189
<li><a href="#Overriding_Built-in_Tools">Overriding Built-in Tools</a></li>
190+
<li><a href="#Skipping_Permission_for_Safe_Tools">Skipping Permission for Safe Tools</a></li>
190191
</ul></li>
191192
<li><a href="#Switching_Models_Mid-Session">Switching Models Mid-Session</a></li>
192193
<li><a href="#System_Messages">System Messages</a>
193194
<ul>
194195

195196
<li><a href="#Adding_Rules">Adding Rules</a></li>
196197
<li><a href="#Full_Control">Full Control</a></li>
198+
<li><a href="#Fine-grained_Customization">Fine-grained Customization</a></li>
197199
</ul></li>
198-
<li><a href="#File_Attachments">File Attachments</a></li>
200+
<li><a href="#File_Attachments">File Attachments</a>
201+
<ul>
202+
203+
<li><a href="#Inline_Blob_Attachments">Inline Blob Attachments</a></li>
204+
</ul></li>
205+
<li><a href="#OpenTelemetry">OpenTelemetry</a></li>
199206
<li><a href="#Bring_Your_Own_Key_BYOK">Bring Your Own Key (BYOK)</a></li>
200207
<li><a href="#Infinite_Sessions">Infinite Sessions</a>
201208
<ul>
@@ -248,6 +255,7 @@ <h2>Table of Contents</h2>
248255
<li><a href="#Custom_Event_Error_Handler">Custom Event Error Handler</a></li>
249256
<li><a href="#Event_Error_Policy">Event Error Policy</a></li>
250257
</ul></li>
258+
<li><a href="#OpenTelemetry">OpenTelemetry</a></li>
251259
</ul><hr /></section><section><a id="Custom_Tools"></a>
252260
<h2>Custom Tools</h2>
253261
<p>Let the AI call back into your application to fetch data or perform actions.</p>
@@ -304,7 +312,30 @@ <h3>Overriding Built-in Tools</h3>
304312
.setTools(List.of(customGrep))
305313
.setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
306314
).get();
307-
</code></pre><hr /></section></section><section><a id="Switching_Models_Mid-Session"></a>
315+
</code></pre></section><section><a id="Skipping_Permission_for_Safe_Tools"></a>
316+
<h3>Skipping Permission for Safe Tools</h3>
317+
<p>When a tool performs only read-only or non-destructive operations, you can mark it to skip the
318+
permission prompt entirely using <code>ToolDefinition.createSkipPermission()</code>:</p>
319+
320+
<pre class="prettyprint"><code class="language-java">var safeLookup = ToolDefinition.createSkipPermission(
321+
&quot;safe_lookup&quot;,
322+
&quot;Look up a record by ID (read-only, no side effects)&quot;,
323+
Map.of(
324+
&quot;type&quot;, &quot;object&quot;,
325+
&quot;properties&quot;, Map.of(
326+
&quot;id&quot;, Map.of(&quot;type&quot;, &quot;string&quot;)
327+
),
328+
&quot;required&quot;, List.of(&quot;id&quot;)
329+
),
330+
invocation -&gt; {
331+
String id = (String) invocation.getArguments().get(&quot;id&quot;);
332+
return CompletableFuture.completedFuture(&quot;Record: &quot; + lookupRecord(id));
333+
}
334+
);
335+
</code></pre>
336+
<p>The CLI bypasses the permission request for this tool invocation, so no <code>PermissionRequestedEvent</code>
337+
is emitted and the <code>onPermissionRequest</code> handler is not called.</p>
338+
<p>See <a href="apidocs/com/github/copilot/sdk/json/ToolDefinition.html">ToolDefinition</a> Javadoc for details.</p><hr /></section></section><section><a id="Switching_Models_Mid-Session"></a>
308339
<h2>Switching Models Mid-Session</h2>
309340
<p>You can change the model used by an existing session without losing conversation history.
310341
The new model takes effect starting with the next message sent.</p>
@@ -317,9 +348,14 @@ <h2>Switching Models Mid-Session</h2>
317348
// Switch to a different model mid-conversation
318349
session.setModel(&quot;gpt-4.1&quot;).get();
319350

351+
// Switch with a specific reasoning effort level
352+
session.setModel(&quot;claude-sonnet-4.6&quot;, &quot;high&quot;).get();
353+
320354
// Next message will use the new model
321355
session.sendAndWait(new MessageOptions().setPrompt(&quot;Continue with the new model&quot;)).get();
322356
</code></pre>
357+
<p>The <code>reasoningEffort</code> parameter accepts <code>&quot;low&quot;</code>, <code>&quot;medium&quot;</code>, <code>&quot;high&quot;</code>, or <code>&quot;xhigh&quot;</code> for models
358+
that support reasoning. Pass <code>null</code> (or use the single-argument overload) to use the default.</p>
323359
<p>The session emits a <a href="apidocs/com/github/copilot/sdk/events/SessionModelChangeEvent.html"><code>SessionModelChangeEvent</code></a>
324360
when the switch completes, which you can observe with <code>session.on(SessionModelChangeEvent.class, event -&gt; ...)</code>.</p>
325361
<p>See <a href="apidocs/com/github/copilot/sdk/CopilotSession.html#setModel.28java.lang.String.29">CopilotSession.setModel()</a> Javadoc for details.</p><hr /></section><section><a id="System_Messages"></a>
@@ -349,7 +385,50 @@ <h3>Full Control</h3>
349385
.setMode(SystemMessageMode.REPLACE)
350386
.setContent(&quot;You are a helpful coding assistant.&quot;))
351387
).get();
352-
</code></pre><hr /></section></section><section><a id="File_Attachments"></a>
388+
</code></pre></section><section><a id="Fine-grained_Customization"></a>
389+
<h3>Fine-grained Customization</h3>
390+
<p>Use <code>CUSTOMIZE</code> mode to override individual sections of the default system prompt without
391+
replacing it entirely. You can replace, remove, append, prepend, or transform specific sections
392+
using the section identifiers from <code>SystemPromptSections</code>.</p>
393+
<p><strong>Static overrides:</strong></p>
394+
395+
<pre class="prettyprint"><code class="language-java">var session = client.createSession(
396+
new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
397+
.setSystemMessage(new SystemMessageConfig()
398+
.setMode(SystemMessageMode.CUSTOMIZE)
399+
.setSections(Map.of(
400+
// Replace the tone section
401+
SystemPromptSections.TONE,
402+
new SectionOverride()
403+
.setAction(SectionOverrideAction.REPLACE)
404+
.setContent(&quot;Be concise and formal in all responses.&quot;),
405+
// Remove the code-change-rules section entirely
406+
SystemPromptSections.CODE_CHANGE_RULES,
407+
new SectionOverride()
408+
.setAction(SectionOverrideAction.REMOVE)
409+
))
410+
// Optional: extra content appended after all sections
411+
.setContent(&quot;Always mention quarterly earnings.&quot;))
412+
).get();
413+
</code></pre>
414+
<p><strong>Transform callbacks</strong> let you inspect and modify section content at runtime:</p>
415+
416+
<pre class="prettyprint"><code class="language-java">var session = client.createSession(
417+
new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
418+
.setSystemMessage(new SystemMessageConfig()
419+
.setMode(SystemMessageMode.CUSTOMIZE)
420+
.setSections(Map.of(
421+
SystemPromptSections.IDENTITY,
422+
new SectionOverride()
423+
.setTransform(content -&gt;
424+
CompletableFuture.completedFuture(
425+
content + &quot;\nAlways end your reply with DONE.&quot;))
426+
)))
427+
).get();
428+
</code></pre>
429+
<p>See <a href="apidocs/com/github/copilot/sdk/json/SystemMessageConfig.html">SystemMessageConfig</a>,
430+
<a href="apidocs/com/github/copilot/sdk/json/SectionOverride.html">SectionOverride</a>, and
431+
<a href="apidocs/com/github/copilot/sdk/json/SystemPromptSections.html">SystemPromptSections</a> Javadoc for details.</p><hr /></section></section><section><a id="File_Attachments"></a>
353432
<h2>File Attachments</h2>
354433
<p>Include files as context for the AI to analyze. The <code>Attachment</code> record takes three parameters:</p>
355434
<table class="table table-striped">
@@ -388,7 +467,40 @@ <h2>File Attachments</h2>
388467
new Attachment(&quot;file&quot;, &quot;/src/main/NewImpl.java&quot;, &quot;New Implementation&quot;)
389468
))
390469
).get();
391-
</code></pre><hr /></section><section><a id="Bring_Your_Own_Key_.28BYOK.29"></a>
470+
</code></pre><section><a id="Inline_Blob_Attachments"></a>
471+
<h3>Inline Blob Attachments</h3>
472+
<p>Use <code>BlobAttachment</code> to pass inline base64-encoded binary data &#x2014; for example, an image captured
473+
at runtime &#x2014; without writing it to disk first:</p>
474+
475+
<pre class="prettyprint"><code class="language-java">// Load image bytes and base64-encode them
476+
byte[] imageBytes = Files.readAllBytes(Path.of(&quot;/path/to/screenshot.png&quot;));
477+
String base64Data = Base64.getEncoder().encodeToString(imageBytes);
478+
479+
session.send(new MessageOptions()
480+
.setPrompt(&quot;Describe this screenshot&quot;)
481+
.setAttachments(List.of(
482+
new BlobAttachment()
483+
.setData(base64Data)
484+
.setMimeType(&quot;image/png&quot;)
485+
.setDisplayName(&quot;screenshot.png&quot;)
486+
))
487+
).get();
488+
</code></pre>
489+
<p>See <a href="apidocs/com/github/copilot/sdk/json/BlobAttachment.html">BlobAttachment</a> Javadoc for details.</p>
490+
<p>Both <code>Attachment</code> and <code>BlobAttachment</code> implement the sealed <code>MessageAttachment</code> interface.
491+
For a mixed list with both types, use an explicit type hint:</p>
492+
493+
<pre class="prettyprint"><code class="language-java">session.send(new MessageOptions()
494+
.setPrompt(&quot;Analyze these&quot;)
495+
.setAttachments(List.&lt;MessageAttachment&gt;of(
496+
new Attachment(&quot;file&quot;, &quot;/path/to/file.java&quot;, &quot;Source&quot;),
497+
new BlobAttachment()
498+
.setData(base64Data)
499+
.setMimeType(&quot;image/png&quot;)
500+
.setDisplayName(&quot;screenshot.png&quot;)
501+
))
502+
).get();
503+
</code></pre><hr /></section></section><section><a id="Bring_Your_Own_Key_.28BYOK.29"></a>
392504
<h2>Bring Your Own Key (BYOK)</h2>
393505
<p>Use your own OpenAI or Azure OpenAI API key instead of GitHub Copilot.</p>
394506
<p>Supported providers:</p>
@@ -1054,7 +1166,56 @@ <h3>Event Error Policy</h3>
10541166
// Later, switch to lenient mode (suppress errors, continue)
10551167
session.setEventErrorPolicy(EventErrorPolicy.SUPPRESS_AND_LOG_ERRORS);
10561168
</code></pre>
1057-
<p>See <a href="apidocs/com/github/copilot/sdk/EventErrorPolicy.html">EventErrorPolicy</a> and <a href="apidocs/com/github/copilot/sdk/EventErrorHandler.html">EventErrorHandler</a> Javadoc for details.</p><hr /></section></section><section><a id="Next_Steps"></a>
1169+
<p>See <a href="apidocs/com/github/copilot/sdk/EventErrorPolicy.html">EventErrorPolicy</a> and <a href="apidocs/com/github/copilot/sdk/EventErrorHandler.html">EventErrorHandler</a> Javadoc for details.</p><hr /></section></section><section><a id="OpenTelemetry"></a>
1170+
<h2>OpenTelemetry</h2>
1171+
<p>Enable OpenTelemetry tracing in the Copilot CLI server by configuring a <code>TelemetryConfig</code>
1172+
on the <code>CopilotClientOptions</code>. This is useful for observability, performance monitoring,
1173+
and debugging.</p>
1174+
1175+
<pre class="prettyprint"><code class="language-java">var options = new CopilotClientOptions()
1176+
.setTelemetry(new TelemetryConfig()
1177+
.setOtlpEndpoint(&quot;http://localhost:4318&quot;) // OTLP/HTTP exporter
1178+
.setSourceName(&quot;my-app&quot;));
1179+
1180+
var client = new CopilotClient(options);
1181+
</code></pre>
1182+
<p>To export to a local file instead:</p>
1183+
1184+
<pre class="prettyprint"><code class="language-java">var options = new CopilotClientOptions()
1185+
.setTelemetry(new TelemetryConfig()
1186+
.setExporterType(&quot;file&quot;)
1187+
.setFilePath(&quot;/tmp/copilot-traces.json&quot;)
1188+
.setCaptureContent(true)); // include message content in spans
1189+
</code></pre>
1190+
<table class="table table-striped">
1191+
<thead>
1192+
<tr class="a">
1193+
<th>Property</th>
1194+
<th>Environment Variable</th>
1195+
<th>Description</th></tr></thead><tbody>
1196+
<tr class="b">
1197+
<td><code>otlpEndpoint</code></td>
1198+
<td><code>OTEL_EXPORTER_OTLP_ENDPOINT</code></td>
1199+
<td>OTLP exporter endpoint URL</td></tr>
1200+
<tr class="a">
1201+
<td><code>filePath</code></td>
1202+
<td><code>COPILOT_OTEL_FILE_EXPORTER_PATH</code></td>
1203+
<td>File path for the file exporter</td></tr>
1204+
<tr class="b">
1205+
<td><code>exporterType</code></td>
1206+
<td><code>COPILOT_OTEL_EXPORTER_TYPE</code></td>
1207+
<td><code>&quot;otlp-http&quot;</code> or <code>&quot;file&quot;</code></td></tr>
1208+
<tr class="a">
1209+
<td><code>sourceName</code></td>
1210+
<td><code>COPILOT_OTEL_SOURCE_NAME</code></td>
1211+
<td>Source name for telemetry spans</td></tr>
1212+
<tr class="b">
1213+
<td><code>captureContent</code></td>
1214+
<td><code>OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT</code></td>
1215+
<td>Whether to capture message content</td></tr></tbody>
1216+
</table>
1217+
1218+
<p>See <a href="apidocs/com/github/copilot/sdk/json/TelemetryConfig.html">TelemetryConfig</a> Javadoc for details.</p><hr /></section><section><a id="Next_Steps"></a>
10581219
<h2>Next Steps</h2>
10591220
<ul>
10601221

0 commit comments

Comments
 (0)