Package ai.confiqure

Annotation Type Confiqure.Tool

Enclosing class:

Confiqure

@Target(METHOD)
@Retention(RUNTIME)
public static @interface Confiqure.Tool

Marks a method as a tool the chat agent can invoke during a session.

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element	Description
boolean	async	Server-side reply discipline (ignored when serverSide=false).
String	name	Tool name.
boolean	serverSide	true (default): a server-side tool — confiqure dispatches an HTTP call to this controller method (returns data / performs a backend action, no UI).

Element Details

name

String name

Tool name. Defaults to the method name when blank.

Default:

""

serverSide

boolean serverSide

true (default): a server-side tool — confiqure dispatches an HTTP call to this controller method (returns data / performs a backend action, no UI).

false: a frontend tool — this method is a contract stub whose handler runs in the host's browser via the embed SDK. The method signature still defines the I/O contract (its @RequestBody DTO is the input, its return type the output), but the body never runs on the backend. Use for anything needing a UI (OAuth, pickers, rendering).

Default:

true

async

boolean async

Server-side reply discipline (ignored when serverSide=false).

false (default) — synchronous: confiqure waits on the HTTP call and takes the method's return value as the tool result. Your handler is plain Spring — the request body IS your DTO (no envelope), and confiqureKey is injected into it:

 @Confiqure.Tool(name = "lookup_supplier")
 @PostMapping("/supplier")
 public SupplierDto lookup(@RequestBody SupplierQuery q) { return service.lookup(q); }
 

true — asynchronous: confiqure ACKs immediately and you deliver the result later. The ai.confiqure:confiqure-spring SDK injects a ConfiqureCallback that does the header-reading + signed POST for you (the same confiqureKey rides your @RequestBody DTO as in the sync case):

 @Confiqure.Tool(name = "analyze_supplier", async = true)
 @PostMapping("/analyze")
 public ResponseEntity<Void> analyze(@RequestBody SupplierQuery q, ConfiqureCallback reply) {
     CompletableFuture.supplyAsync(() -> service.slowAnalysis(q))
         .whenComplete((r, ex) -> { if (ex != null) reply.fail(ex.getMessage()); else reply.reply(r); });
     return ResponseEntity.accepted().build();   // ACK now; the result follows
 }
 

Without the SDK, read the X-Confiqure-Tool-Call-Id + X-Confiqure-Reply-Url headers and POST {"result":…} back yourself. Use async only when the work outlives one request (long jobs, human-in-the-loop, webhooks); ~90% of tools are synchronous, and even a slow sync handler has a 5-minute window before async is warranted.

Default:

false