|
| 1 | +//// |
| 2 | +This guide is maintained in the main Quarkus repository |
| 3 | +and pull requests should be submitted there: |
| 4 | +https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc |
| 5 | +//// |
| 6 | += Dev Assistant |
| 7 | +include::_attributes.adoc[] |
| 8 | +:categories: writing-extensions |
| 9 | +:summary: Learn more about the Dev Assistant |
| 10 | +:topics: dev-ui, assistant, extension |
| 11 | + |
| 12 | +== General overview |
| 13 | + |
| 14 | +The Quarkus Dev Assistant is an AI-powered helper built directly into Quarkus Dev Mode. Its goal is to make you more productive by helping you troubleshoot and assisting with development tasks. |
| 15 | + |
| 16 | +The assistant runs **only** within dev mode and never affects your production application. |
| 17 | + |
| 18 | +--- |
| 19 | + |
| 20 | +=== What Can It Do? |
| 21 | + |
| 22 | +The Dev Assistant can help with: |
| 23 | + |
| 24 | +- Troubleshooting exceptions and stack traces |
| 25 | +- Generating example client code (e.g., `javascript` client for REST endpoints) |
| 26 | +- Generating javadoc for your code |
| 27 | +- Generating test code for your application |
| 28 | +- Generating test data for your application |
| 29 | +- Explain existing code in you application |
| 30 | +- Complete `//TODO` sections in your code |
| 31 | +- ... and more to come ! |
| 32 | + |
| 33 | +=== How to Add the Dev Assistant |
| 34 | + |
| 35 | +To enable the Dev Assistant in your Quarkus project, add the `quarkus-chappie` extension: |
| 36 | + |
| 37 | +[source,xml] |
| 38 | +---- |
| 39 | +<dependency> |
| 40 | + <groupId>io.quarkiverse.chappie</groupId> |
| 41 | + <artifactId>quarkus-chappie</artifactId> |
| 42 | + <version>${chappie-extension-version}</version> // <1> |
| 43 | +</dependency> |
| 44 | +---- |
| 45 | +<1> Replace `${chappie-extension-version}` with the latest available version. You can find the latest version on https://search.maven.org/artifact/io.quarkiverse.chappie/quarkus-chappie[search.maven.org]. |
| 46 | + |
| 47 | +Once added, open the Dev UI to start using the assistant. |
| 48 | + |
| 49 | +[NOTE] |
| 50 | + |
| 51 | +The assistant interfaces are defined in Quarkus "core", but their implementation are located in Quarkiverse (Chappie). You can, if needed, provide an alternative implementation of the assistant. |
| 52 | + |
| 53 | +=== Configuration and Providers |
| 54 | + |
| 55 | +By default, the assistant is disabled until configured. You can choose from supported AI providers: |
| 56 | + |
| 57 | +- OpenAI (e.g., ChatGPT, Openshift AI, Podman AI Lab, ...) |
| 58 | +- Ollama (local models like `llama3`) |
| 59 | + |
| 60 | +Configuration can be done directly in Dev UI via the assistant settings pane. You'll need: |
| 61 | + |
| 62 | +- An API key (for OpenAI) |
| 63 | +- A local running model (for Ollama or Podman AI) |
| 64 | + |
| 65 | +Settings are stored in local storage per browser. |
| 66 | + |
| 67 | +image::dev_assistant_configuration.png[Dev Assistant Configuration, width=100%] |
| 68 | + |
| 69 | +=== Usage |
| 70 | + |
| 71 | +The Dev Assistant integrates seamlessly into various parts of the Dev UI. Wherever assistant features are available, they are highlighted using a distinctive *pink theme*, making it easy to spot AI-powered interactions. |
| 72 | + |
| 73 | +Currently, assistant functions are available in: |
| 74 | + |
| 75 | +- The *Workspace* view |
| 76 | +- Extension pages that support AI-driven help |
| 77 | + |
| 78 | +Look for pink-highlighted buttons or badges - these indicate actions powered by the Dev Assistant. |
| 79 | + |
| 80 | + |
| 81 | +image::dev_assistant_pink_theme.png[Dev Assistant pink link] |
| 82 | + |
| 83 | +==== Exception help |
| 84 | + |
| 85 | +When an error or exception occurs, the error page includes a `Get help with this` button. |
| 86 | + |
| 87 | +Clicking it takes you directly to the Dev UI's Assistant panel, pre-filled with relevant error context. This allows the assistant to help you: |
| 88 | + |
| 89 | +- Understand what the exception means |
| 90 | +- Suggest likely causes |
| 91 | +- Recommend how to fix the issue |
| 92 | + |
| 93 | +This provides a fast and focused troubleshooting workflow without needing to copy and paste logs manually. |
| 94 | + |
| 95 | +image::dev_assistant_errorpage.png[Dev Assistant Error page, width=100%] |
| 96 | + |
| 97 | +== Assistant log |
| 98 | + |
| 99 | +You can access the log of the assistant in the Dev UI Footer: |
| 100 | + |
| 101 | +image::dev_assistant_log.png[Dev Assistant Log, width=100%] |
| 102 | + |
| 103 | +== Guide for Extension Developers |
| 104 | + |
| 105 | +Quarkus extensions can enhance the developer experience by contributing to the Dev Assistant. This section explains how to integrate your extension with the Dev Assistant, covering: |
| 106 | + |
| 107 | +- Workspace-based assistant actions |
| 108 | +- Assistant-specific pages |
| 109 | +- Backend integration via JSON-RPC |
| 110 | +- UI features for assistant-aware components |
| 111 | + |
| 112 | +An extension can define Assistant features without depending on Chappie directly. The interfaces and associated structures are located in the `assistant` extension. |
| 113 | + |
| 114 | +=== Workspace participation |
| 115 | + |
| 116 | +You can add an assistant function to a workspace item using the same approach as regular https://quarkus.io/guides/dev-ui#workspace[workspace actions], with one key difference: instead of using `.function(...)`, you use `.assistantFunction(...)`. |
| 117 | + |
| 118 | +[source,java] |
| 119 | +---- |
| 120 | + Action.actionBuilder() |
| 121 | + .label("Joke AI") |
| 122 | + .assistantFunction((a, p) -> { // <1> |
| 123 | + Assistant assistant = (Assistant) a; |
| 124 | + Map params = (Map) p; |
| 125 | +
|
| 126 | + return assistant.assistBuilder() |
| 127 | + .systemMessage(JOKE_SYSTEM_MESSAGE) // <2> |
| 128 | + .userMessage(JOKE_USER_MESSAGE) // <3> |
| 129 | + .variables(params) |
| 130 | + .assist(); |
| 131 | +
|
| 132 | + }) |
| 133 | + .display(Display.split) |
| 134 | + .displayType(DisplayType.markdown) |
| 135 | + .filter(Patterns.JAVA_SRC)); |
| 136 | +---- |
| 137 | +<1> Use `assistantFunction` to receive the `Assistant` instance and https://quarkus.io/guides/dev-ui#input[input] parameters. |
| 138 | +<2> Provide an optional *system message* to guide the assistant's behavior. |
| 139 | +<3> Provide a *user message* as the primary prompt. |
| 140 | + |
| 141 | +=== Assistant pages |
| 142 | + |
| 143 | +To add a standalone assistant-powered page to the Dev UI, use the https://quarkus.io/guides/dev-ui#card[`CardPageBuildItem`] and `Page.assistantPageBuilder()`: |
| 144 | + |
| 145 | +[source,java] |
| 146 | +---- |
| 147 | +cardPageBuildItem.addPage(Page.assistantPageBuilder() // <1> |
| 148 | + .title("AI Joke") |
| 149 | + .componentLink("qwc-jokes-ai.js")); |
| 150 | +---- |
| 151 | +<1> Use the assistant page builder. |
| 152 | + |
| 153 | +=== Communicating to the backend |
| 154 | + |
| 155 | +You can invoke the assistant from backend code using https://quarkus.io/guides/dev-ui#communicating-to-the-backend[standard Dev UI JSON-RPC] patterns — both against the *runtime* and *deployment* classpaths. |
| 156 | + |
| 157 | +==== JsonRPC against the Runtime classpath |
| 158 | + |
| 159 | +To use the assistant in a https://quarkus.io/guides/dev-ui#jsonrpc-against-the-runtime-classpath[`JsonRpcService`] on the runtime classpath, inject the `Assistant` like this: |
| 160 | + |
| 161 | +[source,java] |
| 162 | +---- |
| 163 | +public class JokesJsonRPCService { |
| 164 | +
|
| 165 | + @Inject |
| 166 | + Optional<Assistant> assistant; // <1> |
| 167 | +---- |
| 168 | +<1> Inject the assistant as optional, it will only be present if a provider is added and configured. |
| 169 | + |
| 170 | +You can now use this assistant in any JsonRPC method, example: |
| 171 | + |
| 172 | +[source,java] |
| 173 | +---- |
| 174 | + public CompletionStage<Map<String, String>> getAiJoke() { |
| 175 | + if (assistant.isPresent()) { |
| 176 | + return assistant.get().assistBuilder() |
| 177 | + .userMessage("Tell me a funny joke") |
| 178 | + .assist(); |
| 179 | + } |
| 180 | + return CompletableFuture.failedStage(new RuntimeException("Assistant is not available")); |
| 181 | + } |
| 182 | +---- |
| 183 | + |
| 184 | +==== JsonRPC against the Deployment classpath |
| 185 | + |
| 186 | +In https://quarkus.io/guides/dev-ui#jsonrpc-against-the-deployment-classpath[deployment-time] code, use the `BuildTimeActionBuildItem` and register assistant actions via `.addAssistantAction(...)`: |
| 187 | + |
| 188 | +[source,java] |
| 189 | +---- |
| 190 | + BuildTimeActionBuildItem bta = new BuildTimeActionBuildItem(); |
| 191 | +
|
| 192 | + bta.addAssistantAction("getAIJokeInDeployment", (a, p) -> { // <1> |
| 193 | + Assistant assistant = (Assistant) a; |
| 194 | +
|
| 195 | + return assistant.assistBuilder() |
| 196 | + .userMessage(USER_MESSAGE) |
| 197 | + .variables(p) |
| 198 | + .assist(); |
| 199 | + }); |
| 200 | + buildTimeActionProducer.produce(bta); |
| 201 | +---- |
| 202 | +<1> Use `addAssistantAction` instead of `addAction` to access the assistant context. |
| 203 | + |
| 204 | +=== Assistant State in the UI |
| 205 | + |
| 206 | +To conditionally render assistant UI in your Web Component, you can use the https://quarkus.io/guides/dev-ui#assistant-state[assistant state] to |
| 207 | +check the state of the assistant. The state can be: |
| 208 | + |
| 209 | +- notAvailable: No assistant implementation (like Chappie) is present. |
| 210 | +- available: Assistant is available but not yet configured. |
| 211 | +- ready: Assistant is configured and ready to use. |
| 212 | + |
| 213 | +To use this state in your page: |
| 214 | + |
| 215 | +[source,javascript] |
| 216 | +---- |
| 217 | +import { observeState } from 'lit-element-state'; // <1> |
| 218 | +import { assistantState } from 'assistant-state'; // <2> |
| 219 | +
|
| 220 | +export class QwcExtentionPage extends observeState(LitElement) { // <3> |
| 221 | +---- |
| 222 | +<1> import observeState from the LitState library. |
| 223 | +<2> import the state you are interested in, in this case assistant state. |
| 224 | +<3> Wrap the LitElement in `observerState` |
| 225 | + |
| 226 | +Now you can access the assistant state anywhere in your page, and when that state changes it will act exactly the same as a local state - re-render the relevant parts of the page: |
| 227 | + |
| 228 | +[source,javascript] |
| 229 | +---- |
| 230 | +render() { |
| 231 | + if(assistantState.current.isConfigured){ |
| 232 | + return html`<div class="assistantfeature"> |
| 233 | + <span> Magic happends here</span> |
| 234 | + </div>`; |
| 235 | + } |
| 236 | +} |
| 237 | +---- |
| 238 | + |
| 239 | +=== Assistant themes and UI Components |
| 240 | + |
| 241 | +To maintain visual consistency with other Dev Assistant features, use the following components and styles: |
| 242 | + |
| 243 | +- `<qui-assistant-button>`: A pre-styled pink button with a robot icon. |
| 244 | +- `<qui-assistant-warning>`: A standard warning message with the text: `"Quarkus assistant can make mistakes. Check responses."` |
| 245 | + |
| 246 | +You can also use the CSS var `--quarkus-assistant` anywhere you want to apply the assistant's theme color. |
| 247 | + |
| 248 | +== Feedback |
| 249 | + |
| 250 | +The Dev Assistant is evolving! If it gives incorrect answers or misses something obvious, please report it at: |
| 251 | + |
| 252 | +https://github.com/quarkusio/quarkus/issues |
0 commit comments