Java SDK
The official Ants Platform Java SDK for monitoring AI agents and LLM applications in Java and JVM-based environments.
Installation
Maven
Add the following dependency to your pom.xml:
xml
<dependency>
<groupId>ai.agenticants</groupId>
<artifactId>ants-platform-java</artifactId>
<version>0.1.1</version>
</dependency>
Gradle
Add the following to your build.gradle:
gradle
dependencies {
implementation 'ai.agenticants:ants-platform-java:0.1.1'
}
Gradle (Kotlin DSL)
Add the following to your build.gradle.kts:
kotlin
dependencies {
implementation("ai.agenticants:ants-platform-java:0.1.1")
}
Quick Start
java
public class MyAgent {
public static void main(String[] args) {
// Initialize the client
AntsPlatformClient client = AntsPlatformClient.builder()
.url("https://api.agenticants.ai")
.credentials(
System.getenv("ANTS_PLATFORM_PUBLIC_KEY"),
System.getenv("ANTS_PLATFORM_SECRET_KEY")
)
.build();
try {
// Your agent logic here
processQuery(client, "Help me with my order");
} catch (AntsPlatformClientApiException e) {
System.err.println("Error: " + e.getBody());
System.err.println("Status Code: " + e.getStatusCode());
}
}
private static void processQuery(AntsPlatformClient client, String query) {
// Implementation here
}
}
Core Features
Client Initialization
java
// Basic initialization
AntsPlatformClient client = AntsPlatformClient.builder()
.url("https://api.agenticants.ai")
.credentials(
System.getenv("ANTS_PLATFORM_PUBLIC_KEY"),
System.getenv("ANTS_PLATFORM_SECRET_KEY")
)
.build();
// Custom environment
AntsPlatformClient client = AntsPlatformClient.builder()
.url(System.getenv("ANTS_PLATFORM_HOST"))
.credentials(
System.getenv("ANTS_PLATFORM_PUBLIC_KEY"),
System.getenv("ANTS_PLATFORM_SECRET_KEY")
)
.build();
Tracing
Track your AI agent executions with detailed tracing:
java
public class AgentTracing {
private final AntsPlatformClient client;
public AgentTracing() {
this.client = AntsPlatformClient.builder()
.url("https://api.agenticants.ai")
.credentials(
System.getenv("ANTS_PLATFORM_PUBLIC_KEY"),
System.getenv("ANTS_PLATFORM_SECRET_KEY")
)
.build();
}
public String executeAgent(String userQuery) {
String traceId = UUID.randomUUID().toString();
String eventId = UUID.randomUUID().toString();
try {
// Create trace start event
Map<String, Object> traceBody = new HashMap<>();
traceBody.put("id", traceId);
traceBody.put("name", "agent-execution");
traceBody.put("userId", "user_123");
traceBody.put("sessionId", "session_abc");
traceBody.put("input", Map.of("user_query", userQuery));
traceBody.put("metadata", Map.of(
"agent", "my-agent",
"version", "1.0.0"
));
traceBody.put("tags", Arrays.asList(
"agent:my-agent",
"service:my-service"
));
// Create ingestion request
IngestionEvent event = IngestionEvent.builder()
.id(eventId)
.type("trace-create")
.timestamp(new Date())
.body(traceBody)
.build();
IngestionRequest request = IngestionRequest.builder()
.batch(Collections.singletonList(event))
.build();
// Send trace to Ants Platform
client.ingestion().batch(request);
// Your agent logic
String result = processAgentLogic(userQuery);
// Update trace with results
updateTrace(traceId, result);
return result;
} catch (Exception e) {
// Handle error and update trace
handleError(traceId, e);
throw e;
}
}
private String processAgentLogic(String query) {
// Your agent implementation
return "Agent response";
}
private void updateTrace(String traceId, String result) {
Map<String, Object> updateBody = new HashMap<>();
updateBody.put("id", traceId);
updateBody.put("output", Map.of("result", result));
updateBody.put("status", "success");
IngestionEvent event = IngestionEvent.builder()
.id(UUID.randomUUID().toString())
.type("trace-update")
.timestamp(new Date())
.body(updateBody)
.build();
IngestionRequest request = IngestionRequest.builder()
.batch(Collections.singletonList(event))
.build();
client.ingestion().batch(request);
}
private void handleError(String traceId, Exception e) {
Map<String, Object> errorBody = new HashMap<>();
errorBody.put("id", traceId);
errorBody.put("status", "error");
errorBody.put("output", Map.of("error", e.getMessage()));
IngestionEvent event = IngestionEvent.builder()
.id(UUID.randomUUID().toString())
.type("trace-update")
.timestamp(new Date())
.body(errorBody)
.build();
IngestionRequest request = IngestionRequest.builder()
.batch(Collections.singletonList(event))
.build();
client.ingestion().batch(request);
}
}
Spans for Detailed Tracking
Create spans to track individual operations within your agent:
java
public class DetailedTracking {
private final AntsPlatformClient client;
public void executeWithSpans(String traceId, String query) {
// Create validation span
createSpan(
traceId,
"request_validation",
Map.of("raw_input", query),
Map.of(
"validated_input", query,
"input_length", query.length()
),
Map.of("step", "validation")
);
// Process query
String context = retrieveContext(query);
// Create context retrieval span
createSpan(
traceId,
"context_retrieval",
Map.of("query", query),
Map.of("context", context),
Map.of("step", "context-retrieval")
);
// Generate response
String response = generateResponse(query, context);
// Create generation span
createGenerationSpan(
traceId,
"gpt-4_llm_call",
"gpt-4",
query,
response,
100, // input tokens
200, // output tokens
Map.of("step", "llm_call")
);
}
private void createSpan(
String traceId,
String name,
Map<String, Object> input,
Map<String, Object> output,
Map<String, Object> metadata
) {
String spanId = UUID.randomUUID().toString();
Map<String, Object> spanBody = new HashMap<>();
spanBody.put("id", spanId);
spanBody.put("traceId", traceId);
spanBody.put("name", name);
spanBody.put("input", input);
spanBody.put("output", output);
spanBody.put("metadata", metadata);
spanBody.put("startTime", new Date());
spanBody.put("endTime", new Date());
IngestionEvent event = IngestionEvent.builder()
.id(UUID.randomUUID().toString())
.type("span-create")
.timestamp(new Date())
.body(spanBody)
.build();
IngestionRequest request = IngestionRequest.builder()
.batch(Collections.singletonList(event))
.build();
client.ingestion().batch(request);
}
private void createGenerationSpan(
String traceId,
String name,
String model,
String prompt,
String completion,
int inputTokens,
int outputTokens,
Map<String, Object> metadata
) {
String generationId = UUID.randomUUID().toString();
Map<String, Object> generationBody = new HashMap<>();
generationBody.put("id", generationId);
generationBody.put("traceId", traceId);
generationBody.put("name", name);
generationBody.put("model", model);
generationBody.put("prompt", prompt);
generationBody.put("completion", completion);
generationBody.put("inputTokens", inputTokens);
generationBody.put("outputTokens", outputTokens);
generationBody.put("metadata", metadata);
generationBody.put("startTime", new Date());
generationBody.put("endTime", new Date());
IngestionEvent event = IngestionEvent.builder()
.id(UUID.randomUUID().toString())
.type("generation-create")
.timestamp(new Date())
.body(generationBody)
.build();
IngestionRequest request = IngestionRequest.builder()
.batch(Collections.singletonList(event))
.build();
client.ingestion().batch(request);
}
private String retrieveContext(String query) {
// Retrieve context implementation
return "Relevant context";
}
private String generateResponse(String query, String context) {
// Generate response implementation
return "Generated response";
}
}
Error Handling
java
public class ErrorHandlingExample {
private final AntsPlatformClient client;
public void processWithErrorHandling(String query) {
String traceId = UUID.randomUUID().toString();
try {
// Start trace
startTrace(traceId, query);
// Process query
String result = processQuery(query);
// Update trace with success
updateTraceSuccess(traceId, result);
} catch (AntsPlatformClientApiException e) {
System.err.println("API Error: " + e.getBody());
System.err.println("Status Code: " + e.getStatusCode());
// Update trace with error
updateTraceError(traceId, e.getMessage());
throw e;
} catch (Exception e) {
System.err.println("Error: " + e.getMessage());
// Update trace with error
updateTraceError(traceId, e.getMessage());
throw e;
}
}
private void startTrace(String traceId, String query) {
// Implementation
}
private String processQuery(String query) {
// Implementation
return "Result";
}
private void updateTraceSuccess(String traceId, String result) {
// Implementation
}
private void updateTraceError(String traceId, String error) {
// Implementation
}
}
Configuration
Environment Variables
Create a .env file or set system environment variables:
bash
ANTS_PLATFORM_PUBLIC_KEY=your_public_key
ANTS_PLATFORM_SECRET_KEY=your_secret_key
ANTS_PLATFORM_HOST=https://api.agenticants.ai
Configuration in Code
java
public class Configuration {
public static AntsPlatformClient createClient() {
return AntsPlatformClient.builder()
.url(getEnvOrDefault("ANTS_PLATFORM_HOST", "https://api.agenticants.ai"))
.credentials(
System.getenv("ANTS_PLATFORM_PUBLIC_KEY"),
System.getenv("ANTS_PLATFORM_SECRET_KEY")
)
.build();
}
private static String getEnvOrDefault(String key, String defaultValue) {
String value = System.getenv(key);
return value != null ? value : defaultValue;
}
}
Framework Integrations
Spring Boot
java
@Service
public class AntsPlatformService {
private final AntsPlatformClient client;
public AntsPlatformService(
@Value("${ants.platform.host}") String host,
@Value("${ants.platform.public-key}") String publicKey,
@Value("${ants.platform.secret-key}") String secretKey
) {
this.client = AntsPlatformClient.builder()
.url(host)
.credentials(publicKey, secretKey)
.build();
}
public void traceAgentExecution(String query) {
String traceId = UUID.randomUUID().toString();
try {
// Start trace
Map<String, Object> traceBody = new HashMap<>();
traceBody.put("id", traceId);
traceBody.put("name", "spring-boot-agent");
traceBody.put("input", Map.of("query", query));
traceBody.put("metadata", Map.of(
"framework", "spring-boot",
"service", "agent-service"
));
IngestionEvent event = IngestionEvent.builder()
.id(UUID.randomUUID().toString())
.type("trace-create")
.timestamp(new Date())
.body(traceBody)
.build();
IngestionRequest request = IngestionRequest.builder()
.batch(Collections.singletonList(event))
.build();
client.ingestion().batch(request);
// Your agent logic here
} catch (Exception e) {
// Handle error
}
}
public AntsPlatformClient getClient() {
return client;
}
}
application.properties
properties
ants.platform.host=https://api.agenticants.ai
ants.platform.public-key=${ANTS_PLATFORM_PUBLIC_KEY}
ants.platform.secret-key=${ANTS_PLATFORM_SECRET_KEY}
API Reference
AntsPlatformClient
java
public class AntsPlatformClient {
// Build a new client
public static AntsPlatformClientBuilder builder()
// Access ingestion API
public IngestionClient ingestion()
// Access trace API
public TraceClient trace()
// Access other resources
public PromptsClient prompts()
public SessionsClient sessions()
public ObservationsClient observations()
}
AntsPlatformClientBuilder
java
public class AntsPlatformClientBuilder {
// Set the API URL
public AntsPlatformClientBuilder url(String url)
// Set credentials
public AntsPlatformClientBuilder credentials(String publicKey, String secretKey)
// Build the client
public AntsPlatformClient build()
}
IngestionClient
java
public class IngestionClient {
// Send batch of events
public IngestionResponse batch(IngestionRequest request)
// Send batch with custom options
public IngestionResponse batch(IngestionRequest request, RequestOptions options)
}
Best Practices
1. Use Try-Catch Blocks
Always handle exceptions properly:
java
try {
// Your tracing code
client.ingestion().batch(request);
} catch (AntsPlatformClientApiException e) {
System.err.println("API Error: " + e.getBody());
System.err.println("Status Code: " + e.getStatusCode());
} catch (Exception e) {
System.err.println("Error: " + e.getMessage());
}
2. Add Rich Metadata
Include relevant context in your traces:
java
Map<String, Object> metadata = new HashMap<>();
metadata.put("user_id", "user_123");
metadata.put("session_id", "session_abc");
metadata.put("agent", "my-agent");
metadata.put("version", "1.0.0");
metadata.put("environment", System.getenv("ENVIRONMENT"));
traceBody.put("metadata", metadata);
traceBody.put("tags", Arrays.asList(
"agent:my-agent",
"service:my-service",
"version:1.0.0"
));
3. Use Unique IDs
Generate unique IDs for traces and events:
java
String traceId = UUID.randomUUID().toString();
String eventId = UUID.randomUUID().toString();
String spanId = UUID.randomUUID().toString();
4. Batch Events Efficiently
Group multiple events in a single batch for better performance:
java
List<IngestionEvent> events = new ArrayList<>();
// Add multiple events
events.add(createTraceEvent(traceId));
events.add(createSpanEvent(traceId, "step1"));
events.add(createSpanEvent(traceId, "step2"));
events.add(createGenerationEvent(traceId));
// Send all at once
IngestionRequest request = IngestionRequest.builder()
.batch(events)
.build();
client.ingestion().batch(request);
Note: Batch sizes are limited to 3.5 MB in total.
5. Create Helper Classes
Encapsulate tracing logic in reusable helper classes:
java
public class TracingHelper {
private final AntsPlatformClient client;
public TracingHelper(AntsPlatformClient client) {
this.client = client;
}
public String startTrace(String name, Map<String, Object> input, Map<String, Object> metadata) {
String traceId = UUID.randomUUID().toString();
Map<String, Object> traceBody = new HashMap<>();
traceBody.put("id", traceId);
traceBody.put("name", name);
traceBody.put("input", input);
traceBody.put("metadata", metadata);
IngestionEvent event = IngestionEvent.builder()
.id(UUID.randomUUID().toString())
.type("trace-create")
.timestamp(new Date())
.body(traceBody)
.build();
IngestionRequest request = IngestionRequest.builder()
.batch(Collections.singletonList(event))
.build();
client.ingestion().batch(request);
return traceId;
}
public void updateTrace(String traceId, String status, Map<String, Object> output) {
Map<String, Object> updateBody = new HashMap<>();
updateBody.put("id", traceId);
updateBody.put("status", status);
updateBody.put("output", output);
IngestionEvent event = IngestionEvent.builder()
.id(UUID.randomUUID().toString())
.type("trace-update")
.timestamp(new Date())
.body(updateBody)
.build();
IngestionRequest request = IngestionRequest.builder()
.batch(Collections.singletonList(event))
.build();
client.ingestion().batch(request);
}
}
// Usage
TracingHelper helper = new TracingHelper(client);
String traceId = helper.startTrace("my-operation", input, metadata);
// ... do work ...
helper.updateTrace(traceId, "success", output);
Complete Example
Here's a complete example of a customer support agent with full tracing:
java
public class CustomerSupportAgent {
private final AntsPlatformClient client;
private final TracingHelper tracingHelper;
public CustomerSupportAgent() {
this.client = AntsPlatformClient.builder()
.url("https://api.agenticants.ai")
.credentials(
System.getenv("ANTS_PLATFORM_PUBLIC_KEY"),
System.getenv("ANTS_PLATFORM_SECRET_KEY")
)
.build();
this.tracingHelper = new TracingHelper(client);
}
public String handleQuery(String query, String userId) {
String traceId = tracingHelper.startTrace(
"customer-support-agent",
Map.of("query", query, "userId", userId),
Map.of("agent", "customer-support", "userId", userId)
);
try {
// Validate input
tracingHelper.createSpan(
traceId,
"validate-input",
Map.of("query", query),
Map.of("valid", true),
Map.of("step", "validation")
);
// Get context
String context = getContext(query);
tracingHelper.createSpan(
traceId,
"retrieve-context",
Map.of("query", query),
Map.of("context", context),
Map.of("step", "context-retrieval")
);
// Generate response
String response = generateResponse(query, context);
tracingHelper.createGenerationSpan(
traceId,
"generate-response",
"gpt-4",
query,
response,
150, // input tokens
200, // output tokens
Map.of("step", "generation")
);
// Update trace with success
tracingHelper.updateTrace(
traceId,
"success",
Map.of("response", response)
);
return response;
} catch (Exception e) {
// Handle error
tracingHelper.createSpan(
traceId,
"error-handling",
Map.of("error", e.getMessage()),
Map.of("handled", true),
Map.of(
"error_type", e.getClass().getSimpleName(),
"step", "error-handling"
)
);
tracingHelper.updateTrace(
traceId,
"error",
Map.of("error", e.getMessage())
);
throw e;
}
}
private String getContext(String query) {
// Retrieve relevant context from database or vector store
return "Relevant context...";
}
private String generateResponse(String query, String context) {
// Call LLM to generate response
return "Generated response...";
}
public static void main(String[] args) {
CustomerSupportAgent agent = new CustomerSupportAgent();
String response = agent.handleQuery(
"What's the status of my order?",
"user_123"
);
System.out.println("Response: " + response);
}
}
Troubleshooting
Common Issues
"Authentication failed" error
- Verify your public and secret keys are correct
- Ensure environment variables are properly set
- Check that keys have not expired
"Network timeout" error
- Verify the host URL is correct
- Check your network connectivity
- Ensure firewall rules allow outbound HTTPS connections
Traces not appearing in dashboard
- Ensure you're sending events with correct format
- Check that the client is properly initialized
- Verify your API keys have the correct permissions
- Check batch size is under 3.5 MB limit
Debug Logging
Enable debug logging in your application to troubleshoot issues:
java
public class DebugExample {
static {
// Enable HTTP logging
System.setProperty("java.util.logging.config.file", "logging.properties");
}
public static void main(String[] args) {
Logger logger = Logger.getLogger("com.ants.platform");
logger.setLevel(Level.FINE);
ConsoleHandler handler = new ConsoleHandler();
handler.setLevel(Level.FINE);
logger.addHandler(handler);
// Your code here
}
}
Requirements
- Java 8 or higher
- Maven 3.x or Gradle 6.x+
- Dependencies:
- Jackson 2.18.2+ (for JSON processing)
- OkHttp 4.11.0+ (for HTTP client)