AI agent allow list verdicts for LangChain4j tools and any other Java code that lets a model browse. Before your agent opens a URL, check asks whether the page is one an unattended agent should act on. The service recognises sensitive page types, including login, checkout, upload and account settings, and replies with a verdict.
<dependency>
<groupId>io.github.explainableaixai</groupId>
<artifactId>aiagentallowlist</artifactId>
<version>1.0.0</version>
</dependency>Java 11+, Jackson as the single runtime dependency.
var guard = new AIAgentAllowlistClient(System.getenv("AQ_API_KEY"));
Map<String, Object> r = guard.check("https://billing.example.com/invoices/pay");
// r.get("verdict") -> e.g. "deny"
// r.get("matched") -> {layer=rules, id=...}check sends its argument as the url parameter:
- For a full URL, the reply includes
verdictand amatchedmap.layerisrulesfor built-in path patterns andpage_type_dbfor pages known from the site catalogue.idnames the page type. - For a bare domain, the reply is the site record:
found,languageand apage_typesmap from type to URL.
LangChain4j exposes Java methods to the model through @Tool. Put the check inside the browsing tool itself, so no code path skips it:
public class WebTools {
private final AIAgentAllowlistClient guard;
private final PageFetcher fetcher;
public WebTools(AIAgentAllowlistClient guard, PageFetcher fetcher) {
this.guard = guard;
this.fetcher = fetcher;
}
@Tool("Open a web page and return its readable text")
public String open(String url) {
Map<String, Object> r;
try {
r = guard.check(url);
} catch (Exception e) {
return "This page could not be cleared by policy. Ask the user to open it.";
}
if ("allow".equals(r.get("verdict"))) {
return fetcher.text(url);
}
Object kind = r.get("matched") instanceof Map ? ((Map<?, ?>) r.get("matched")).get("id") : "restricted";
return "Agents may not act on " + kind + " pages. Ask the user to complete this step.";
}
}Three details carry most of the value:
- Return, do not throw. The model reads the refusal and can explain it or change course. An exception usually ends the run.
- Allow only on an explicit allow. Unknown or future verdicts stop the step.
- Keep the timeout short. Configure it on the client, as below.
The same pattern works with Spring AI function callbacks or a hand-written tool dispatcher.
var guard = AIAgentAllowlistClient.builder()
.apiKey(key)
.timeout(Duration.ofSeconds(4))
.build();A slow policy check should stop an agent step, not stall it. Four seconds is a reasonable ceiling, compared with the default of 30. The client is immutable and thread-safe: one instance can serve every agent in the JVM.
Map<String, Object> site = guard.check("hubspot.com");
if (Boolean.TRUE.equals(site.get("found"))) {
((Map<?, ?>) site.get("page_types")).forEach((k, v) -> System.out.println(k + " -> " + v));
}A list like this, shown before a long run, tells reviewers exactly which steps the agent will hand back. For sites without a catalogue entry, found is false, and full-URL checks still apply the path rules.
| Thrown | Cause | Suggested handling |
|---|---|---|
IllegalArgumentException |
Blank key or URL | Fix configuration |
ApiException 401 or 403 |
Unknown key, inactive plan or used quota | Alert an operator |
ApiException 429 |
Too many requests | Back off |
HttpTimeoutException |
Request timeout reached | Treat as not cleared |
IOException |
Network or JSON problem | Treat as not cleared |
Log every decision with the agent run ID, the URL, the verdict and the page type. With SLF4J:
log.info("agent={} verdict={} type={} url={}", runId, verdict, kind, url);These lines answer the first question after any incident: what did the agent try to do? They also show which workflows keep reaching sensitive pages, and those workflows usually need a human step.
Start by logging verdicts without blocking. After a week you know which flows would be affected. Then enforce, beginning with agents that can pay, send or delete.
The OWASP Top 10 for LLM Applications lists excessive agency as a core risk: agents doing more than intended because nothing limits them. Domain allow lists are too coarse, since reading and acting often happen on the same site. Page-type checks draw the line where the risk actually changes.
Agents also call other AI services, and the same register helps block risky AI queries without shutting down productivity. Look for AI copilots running without approval using shadow AI tools for IT teams. When a policy depends on topic, run a URL category check on the destination page.
Agents written in TypeScript can use the npm package, and Go executors the aiagentallowlist-go module.
MIT