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>0.1.0</version>
</dependency>Gradle
implementation 'org.opena2a:aim-sdk:0.1.0'Local Installation: If using local JAR, install with: mvn install:install-file -Dfile=aim-sdk-0.1.0.jar -DgroupId=org.opena2a -DartifactId=aim-sdk -Dversion=0.1.0 -Dpackaging=jar
2
Initialize the SDK
Create an AIMClient and register your agent:
import org.opena2a.aim.AIMClient;
import org.opena2a.aim.Agent;
public class MyAgent {
public static void main(String[] args) {
// Initialize client with your AIM server URL and SDK token
AIMClient client = new AIMClient(
"http://localhost:8080",
"your-sdk-token" // Get from Settings → SDK Tokens
);
// Register your agent (auto-creates if doesn't exist)
Agent agent = client.registerAgent(
"my-java-agent",
"langchain4j", // Agent type
new String[]{"data:read", "api:call"} // Capabilities
);
System.out.println("Agent registered: " + agent.getAgentId());
System.out.println("Trust Score: " + agent.getTrustScore());
}
}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.annotation.SecureAction;
import org.opena2a.aim.annotation.EnableAIMSecurity;
@EnableAIMSecurity(
baseUrl = "http://localhost:8080",
sdkToken = "your-sdk-token"
)
public class WeatherService {
@SecureAction(
agentId = "weather-agent",
capability = "weather:fetch",
riskLevel = "low"
)
public String getWeather(String city) {
// This action is now verified, logged, and monitored
return "Weather in " + city + ": Sunny, 72°F";
}
@SecureAction(
agentId = "weather-agent",
capability = "notification:send",
riskLevel = "high"
)
public void sendWeatherAlert(String userId, String message) {
// High-risk actions get additional monitoring
System.out.println("Sending alert to " + userId + ": " + message);
}
@SecureAction(
agentId = "weather-agent",
capability = "db:delete",
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.annotation.SecureAction;
public class SecuredLangChain4jTools {
@Tool("Fetch current weather for a city")
@SecureAction(
agentId = "langchain-weather-agent",
capability = "weather:fetch"
)
public String getWeather(String city) {
return "Weather in " + city + ": Sunny";
}
@Tool("Search the knowledge base")
@SecureAction(
agentId = "langchain-weather-agent",
capability = "kb:search",
riskLevel = "low"
)
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.AttestationCache;
// Enterprise security logging
SecurityLogger logger = new SecurityLogger(client);
logger.logAction("agent-123", "data:read", "low", metadata);
// Risk detection
RiskDetector detector = new RiskDetector();
String riskLevel = detector.assessCapability("payment:charge"); // Returns "critical"
// Attestation caching for performance
AttestationCache cache = new AttestationCache(client, Duration.ofMinutes(5));
Attestation att = cache.getAttestation("mcp-server-id");Complete Working Example
import org.opena2a.aim.AIMClient;
import org.opena2a.aim.Agent;
import org.opena2a.aim.annotation.SecureAction;
import org.opena2a.aim.annotation.EnableAIMSecurity;
@EnableAIMSecurity(
baseUrl = "http://localhost:8080",
sdkToken = "${AIM_SDK_TOKEN}" // Use environment variable
)
public class WeatherBot {
private final AIMClient client;
private final Agent agent;
public WeatherBot() {
this.client = new AIMClient(
System.getenv("AIM_BASE_URL"),
System.getenv("AIM_SDK_TOKEN")
);
this.agent = client.registerAgent(
"weather-bot-java",
"langchain4j",
new String[]{"weather:fetch", "notification:send"}
);
}
@SecureAction(agentId = "weather-bot-java", capability = "weather:fetch")
public String getWeather(String city) {
return "Weather in " + city + ": Sunny, 72°F";
}
@SecureAction(
agentId = "weather-bot-java",
capability = "notification:send",
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!");
}
}