Java SDK Quickstart
3 minutes
Secure your Java AI agents with enterprise-grade security. Supports LangChain4j and Spring AI.
100% TESTS PASSING
Enterprise-Ready Java SDK
The Java SDK provides enterprise security features including SecurityLogger, RiskDetector, and AttestationCache for production deployments.
Full integration with LangChain4j, Spring AI, and standard Java applications
Prerequisites
- • AIM running at
http://localhost:8080(see Installation) - • Java 17+ and Maven or Gradle
- • SDK Token from AIM Dashboard (Settings → SDK Tokens)
1
Add the Dependency
Add the AIM SDK to your project using Maven or Gradle:
Maven
<dependency>
<groupId>org.opena2a</groupId>
<artifactId>aim-sdk</artifactId>
<version>1.0.0</version>
</dependency>Gradle
implementation 'org.opena2a:aim-sdk:1.0.0'Local Installation: If using local JAR, install with: mvn install:install-file -Dfile=aim-sdk-1.0.0.jar -DgroupId=org.opena2a -DartifactId=aim-sdk -Dversion=1.0.0 -Dpackaging=jar
2
Initialize the SDK
Create an AIMClient and register your agent:
import org.opena2a.aim.client.AIMClient;
import org.opena2a.aim.client.AgentType;
import java.util.Arrays;
public class MyAgent {
public static void main(String[] args) {
// Initialize client with builder pattern
AIMClient agent = AIMClient.builder("my-java-agent")
.agentType(AgentType.LANGCHAIN)
.capabilities(Arrays.asList("data:read", "api:call"))
.build();
System.out.println("Agent registered: " + agent.getAgentId());
System.out.println("Trust Score: " + agent.getAgentDetails().get("trustScore"));
}
}The SDK uses get-or-create pattern - safe to call registerAgent multiple times!
3
Secure Your Actions
Use the @SecureAction annotation to verify and log agent actions:
import org.opena2a.aim.annotations.SecureAction;
import org.opena2a.aim.client.RiskLevel;
public class WeatherService {
@SecureAction(capability = "weather:fetch")
public String getWeather(String city) {
// This action is now verified, logged, and monitored
return "Weather in " + city + ": Sunny, 72°F";
}
@SecureAction(
capability = "notification:send",
riskLevel = RiskLevel.HIGH
)
public void sendWeatherAlert(String userId, String message) {
// High-risk actions get additional monitoring
System.out.println("Sending alert to " + userId + ": " + message);
}
@SecureAction(
capability = "db:delete",
riskLevel = RiskLevel.CRITICAL,
jitAccess = true // Requires admin approval!
)
public void purgeOldData(int daysOld) {
// This will PAUSE until an admin approves in the dashboard
System.out.println("Purging data older than " + daysOld + " days");
}
}JIT
Just-In-Time Access: When
jitAccess = true, the action pauses execution and waits for admin approval in the AIM dashboard before proceeding.4
LangChain4j Integration
Secure LangChain4j tools with AIM:
import dev.langchain4j.agent.tool.Tool;
import org.opena2a.aim.annotations.SecureAction;
public class SecuredLangChain4jTools {
@Tool("Fetch current weather for a city")
@SecureAction(capability = "weather:fetch")
public String getWeather(String city) {
return "Weather in " + city + ": Sunny";
}
@Tool("Search the knowledge base")
@SecureAction(capability = "kb:search")
public String searchKnowledgeBase(String query) {
return "Results for: " + query;
}
}Enterprise Security Features
The Java SDK includes enterprise-grade security components:
SecurityLogger
Structured audit logging with automatic context capture
RiskDetector
ML-based risk assessment for capabilities and actions
AttestationCache
High-performance caching for MCP server attestations
import org.opena2a.aim.security.SecurityLogger;
import org.opena2a.aim.security.RiskDetector;
import org.opena2a.aim.security.RiskLevel;
import org.opena2a.aim.mcp.AttestationCache;
// Enterprise security logging
SecurityLogger logger = SecurityLogger.getInstance();
logger.logAuthentication(EventTypes.Authn.TOKEN_REFRESH, true, "Refreshed", Map.of());
// Risk detection (pattern-based)
RiskDetector detector = RiskDetector.getInstance();
RiskLevel level = detector.detectRisk("payment:charge"); // Returns: HIGH
// Attestation caching for MCP drift detection
AttestationCache cache = AttestationCache.getInstance();
cache.store("mcp-server-id", discovery, "attestation-123");Complete Working Example
import org.opena2a.aim.client.AIMClient;
import org.opena2a.aim.client.AgentType;
import org.opena2a.aim.client.RiskLevel;
import org.opena2a.aim.annotations.SecureAction;
import java.util.Arrays;
public class WeatherBot {
private final AIMClient agent;
public WeatherBot() {
this.agent = AIMClient.builder("weather-bot-java")
.agentType(AgentType.LANGCHAIN)
.capabilities(Arrays.asList("weather:fetch", "notification:send"))
.build();
}
@SecureAction(capability = "weather:fetch")
public String getWeather(String city) {
return "Weather in " + city + ": Sunny, 72°F";
}
@SecureAction(
capability = "notification:send",
riskLevel = RiskLevel.HIGH
)
public void sendAlert(String userId, String message) {
System.out.println("Alert to " + userId + ": " + message);
}
public static void main(String[] args) {
WeatherBot bot = new WeatherBot();
// All actions are verified, logged, and monitored
String weather = bot.getWeather("San Francisco");
System.out.println(weather);
bot.sendAlert("user-123", "Temperature is 72°F!");
System.out.println("All actions logged to AIM!");
}
}