Skip to content

Latest commit

 

History

2 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

aiagentallowlist (Java)

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

<dependency>
  <groupId>io.github.explainableaixai</groupId>
  <artifactId>aiagentallowlist</artifactId>
  <version>1.0.0</version>
</dependency>

Java 11+, Jackson as the single runtime dependency.

What a check returns

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 verdict and a matched map. layer is rules for built-in path patterns and page_type_db for pages known from the site catalogue. id names the page type.
  • For a bare domain, the reply is the site record: found, language and a page_types map from type to URL.

Guarding a LangChain4j tool

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.

Client configuration

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.

Showing people the sensitive pages up front

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.

Errors

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

Audit logging

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.

Introducing enforcement

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.

Background

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.

Adjacent controls

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.

License

MIT

Releases

Packages

Contributors

Languages