Interface PromptAssist

All Known Implementing Classes:
AbstractSchemaPromptAssist, ComponentPromptAssist, DatasourcePromptAssist, FilePromptAssist, LibraryPromptAssist, NamedQueryParameterPromptAssist, NamedQuerySchemaPromptAssist, OpcPromptAssist, PropertyPromptAssist, QueryBrowserSchemaPromptAssist, ReportDataPromptAssist, SystemLibraryPromptAssist, TagPromptAssist, TargetFolderPromptAssist, UdtPromptAssist, UserLibraryPromptAssist

public interface PromptAssist
Pluggable source of in-prompt assistance — the rows that appear when the user triggers the autocomplete popup in the embedded assistant's prompt area. The current trigger is the literal @ character; future triggers (e.g. / for slash commands) will reuse this same interface, so implementations should not encode the trigger into their behavior.

Pass PromptAssists to EmbeddedAssistantBuilder.promptAssists(PromptAssist...). The embedded controller always renders an implicit chooser: at the top level the popup shows one drill-in per assist keyed on label(), and drilling into one routes subsequent queries to that single assist with the routing prefix stripped on the way in and re-applied to any PromptAssist.Option.DrillIn the child returns. Mounting two assists with the same id() or the same label() on one surface is a configuration error and fails fast at mount time.

Token namespace. Every assist owns the token namespace @<id>: — the framework constructs each inserted literal as @<id>:<path> from this assist's id() and the selected option's PromptAssist.Option.Insert.path.

Async + hierarchical by design. options(String) returns a future so providers can fetch directly from the gateway, traverse remote trees, or cache as they see fit. Hierarchical sources return PromptAssist.Option.DrillIn rows that the framework treats as "open this folder": selecting a drill-in rewrites the query to the row's PromptAssist.Option.DrillIn.nextQuery and triggers a fresh options(String) call. The provider sees the new query string and decides what to return next; it never knows whether the new query came from the user typing or from a drill-in row being selected.

Cancellation. The framework cancels stale futures (via CompletableFuture.cancel(boolean)) when the query advances. Providers that hit a network boundary should observe the cancellation and stop work so the gateway is not asked to do work the user no longer wants.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static interface 
    One row in the popup.
  • Method Summary

    Modifier and Type
    Method
    Description
    default Optional<String>
    Self-description appended to the embedded agent's system prompt.
    id()
     
     
    options(String query)
    Fetch the rows to show for query.
    default String
    Separator the embedded controller places between this assist's label() and its query when building the routing prefix, and that the assist itself should use inside its PromptAssist.Option.DrillIn.nextQuery values.
  • Method Details

    • id

      String id()
      Returns:
      the machine identifier owning this assist's @<id>: token namespace. Lowercase [a-z0-9-]+, short (e.g. "tag", "opc").
      See Also:
    • label

      String label()
      Returns:
      a short friendly label for this assist to show in the UI.
    • separator

      default String separator()
      Separator the embedded controller places between this assist's label() and its query when building the routing prefix, and that the assist itself should use inside its PromptAssist.Option.DrillIn.nextQuery values.

      Default is "/".

      Returns:
      a non-empty separator string the controller uses both to recognize the routing prefix this assist owns and to re-prefix child PromptAssist.Option.DrillIns on the way back out.
    • agentContext

      default Optional<String> agentContext()
      Self-description appended to the embedded agent's system prompt. The embed concatenates the fragments from every mounted assist into a single addendum so each provider documents its own token shape and reference-body schema in one place, decoupled from any specific agent's translation rules. Fragments are expected to be Markdown; the embed adds a heading for each assist using label() and joins them with blank lines.

      The embed's framing already tells the model every token is shaped @<id>:<path> and announces this assist's @<id>: prefix in its section heading, so the fragment should not restate the generic shape. It should cover:

      • the grammar of the <path> portion, with a concrete example token;
      • the schema of the <reference token="...">body</reference> body the embed will attach when one of those tokens appears — the line names (Path:, Type:, …) the agent should look for and what they mean;
      • a one-line statement of what the reference represents semantically (so the agent can reason about it without knowing this assist exists).
      Fragments should stay host-language-agnostic — say what the reference is, not how to spell it in a particular tool's syntax. The hosting agent's own system prompt is responsible for translating the body's identifier into whatever expression/script/query syntax it speaks.
      Returns:
      the Markdown fragment, or Optional.empty() when the assist has nothing to contribute (e.g. unit-test stubs).
    • options

      Fetch the rows to show for query.
      Parameters:
      query - the text the user has typed past the trigger character, or the PromptAssist.Option.DrillIn.nextQuery of a row the user just selected. Empty when the user has just typed the trigger and has not yet typed anything else.
      Returns:
      the rows to render. The framework discards stale results silently, so an implementation that completes after a newer query has been issued does not need to special-case the race.