Java Agent Tool Sandbox Reference

TeaQL enforces strict API guardrails for AI Agents and human developers alike. Any side-effect or IO-bound capability (e.g., HTTP, Message Queues, File System) must be accessed via the UserContext sandbox.

This guarantees that:

1. Capabilities are opt-in: If a module (e.g., teaql-tool-http) is not loaded via JPMS SPI, the Agent cannot use it, keeping Docker images tiny and boundaries strict.
2. Intent is mandatory: Operations cannot be executed without declaring a .purpose() (for reads) or an .auditAs() (for writes).

API Reference

In Java, capabilities are dynamically loaded via the JPMS ServiceLoader SPI mechanism.

Important: If the required Maven module is missing from the classpath, the capability factory (ctx.http(), ctx.mq(), etc.) will throw an IllegalStateException.

Capability Module (Maven)	Action Type	Intent Phase Method	Fluent API Chain Example
teaql-tool-http	Write / Action (POST)	auditAs()	ctx.http().post(url, body).auditAs("Sync inventory data").execute();
teaql-tool-http	Read / Query (GET)	purpose()	ctx.http().get(url).purpose("Fetch exchange rates").execute();
teaql-tool-mq	Write / Send	auditAs()	ctx.mq().send(topic, msg).auditAs("Notify fulfillment system").commit();
teaql-tool-fs	Write / Save	auditAs()	ctx.fs().writeText(path, txt).auditAs("Export invoice backup").commit();
teaql-tool-fs	Read / Query	purpose()	ctx.fs().readText(path).purpose("Load temporary certificate").execute();
teaql-tool-email	Write / Send	auditAs()	ctx.email().send(to, body).auditAs("Send password reset link").commit();