A modern Java SDK for building AI agents with OpenAI's API, inspired by the OpenAI Agents TypeScript SDK. Built on the OpenAI Java SDK.
📖 Full Documentation | 🚀 Quickstart Guide | 📚 API Reference
| Feature | Description | Docs | Examples |
|---|---|---|---|
| Agent Loop | Built-in agent loop that handles tool invocation, sends results back to the LLM, and continues until the task is complete | Guide | Code |
| Java-First | Orchestrate and chain agents using idiomatic Java language features, without needing to learn new abstractions | Guide | Code |
| Handoffs | Powerful mechanism for coordinating and delegating work across multiple agents | Guide | Code |
| Guardrails | Run input validation and safety checks in parallel with agent execution, and fail fast when checks do not pass | Guide | Code |
| Function Tools | Turn any Java function into a tool with automatic schema generation and validation | Guide | Code |
| Hosted Tools | Built-in support for OpenAI hosted tools like web search and image generation | Guide | Code |
| Sessions | Persistent memory layer for maintaining working context within an agent loop | Guide | Code |
| Human in the Loop | Built-in mechanisms for involving humans across agent runs | Guide | Code |
| Tracing | Built-in tracing for visualizing, debugging, and monitoring workflows | Guide | Code |
| MCP Server Tools | Built-in MCP server tool integration that works the same way as function tools | TBD | TBD |
| Realtime API | Build powerful voice agents with features such as automatic interruption detection, context management, and guardrails | TBD | TBD |
- Java 21 or higher
- Maven 3.6+ or Gradle 7+
- OpenAI API key (Get one here)
Add to your pom.xml:
<dependency>
<groupId>ai.acolite</groupId>
<artifactId>openai-agent-sdk</artifactId>
<version>0.4.0</version>
</dependency>Set your OpenAI API key as an environment variable:
export OPENAI_API_KEY='your-api-key-here'import ai.acolite.agentsdk.core.Agent;
import ai.acolite.agentsdk.core.RunResult;
import ai.acolite.agentsdk.core.Runner;
import ai.acolite.agentsdk.core.types.TextOutput;
import ai.acolite.agentsdk.core.types.UnknownContext;
public class HelloWorld {
public static void main(String[] args) {
// Create a simple agent
Agent<UnknownContext, TextOutput> agent =
Agent.<UnknownContext, TextOutput>builder()
.name("Assistant")
.instructions("You are a helpful assistant.")
.build();
// Run the agent
RunResult<UnknownContext, ?> result =
Runner.run(agent, "What is the capital of France?");
// Print the response
System.out.println(result.getFinalOutput());
}
}Try the SDK with our interactive command-line demos:
cd demo
mvn clean package
# Run async chat demo (responses appear all at once)
java -jar target/async-chat-demo.jar
# Or run streaming chat demo (real-time character-by-character)
java -jar target/streaming-chat-demo.jarThe demos include:
- 💬 Interactive chat interface with conversation memory
- 🏠 Address validation tool using the Smarty US Street API
- 🔄 Up to 20 turns for complex multi-step workflows
- 📝 Both async and streaming modes to compare execution patterns
View demo source code → | Demo README →
Agents are the core building blocks. They encapsulate instructions and optional tools:
Agent<UnknownContext, TextOutput> agent =
Agent.<UnknownContext, TextOutput>builder()
.name("MathAssistant")
.instructions("You are a math tutor. Use the calculator tool to perform calculations.")
.tools(List.of(new CalculatorTool()))
.build();Define custom tools that agents can invoke. Tools use type-safe input/output with automatic JSON schema generation:
public class CalculatorTool
implements FunctionTool<Object, CalculatorTool.Input, CalculatorTool.Output> {
@Data
@JsonClassDescription("Input parameters for arithmetic operations")
public static class Input {
@JsonPropertyDescription("The arithmetic operation: add, subtract, multiply, or divide")
private String operation;
@JsonPropertyDescription("The first number")
private double a;
@JsonPropertyDescription("The second number")
private double b;
}
@Data
@AllArgsConstructor
public static class Output {
private double result;
private String operation;
private String expression;
}
@Override
public String getName() {
return "calculator";
}
@Override
public String getDescription() {
return "Performs basic arithmetic operations.";
}
@Override
public Object getParameters() {
return Input.class;
}
@Override
public CompletableFuture<Output> invoke(RunContext<Object> context, Input input) {
return CompletableFuture.supplyAsync(() -> {
double result = switch (input.getOperation()) {
case "add" -> input.getA() + input.getB();
case "subtract" -> input.getA() - input.getB();
case "multiply" -> input.getA() * input.getB();
case "divide" -> input.getA() / input.getB();
default -> throw new IllegalArgumentException("Unknown operation");
};
return new Output(result, input.getOperation(),
String.format("%.2f %s %.2f = %.2f", input.getA(),
input.getOperation(), input.getB(), result));
});
}
}Use OpenAI's hosted tools for web search and image generation:
import ai.acolite.agentsdk.core.HostedTool;
// Web search
Agent<UnknownContext, TextOutput> searchAgent =
Agent.<UnknownContext, TextOutput>builder()
.name("SearchAssistant")
.instructions("You can search the web for current information.")
.tools(List.of(HostedTool.webSearch()))
.build();
// Image generation
Agent<UnknownContext, TextOutput> artistAgent =
Agent.<UnknownContext, TextOutput>builder()
.name("Artist")
.instructions("You can generate images using DALL-E.")
.tools(List.of(HostedTool.imageGeneration()))
.build();Transfer conversations between specialized agents:
// Create specialist agents
Agent<UnknownContext, TextOutput> supportAgent =
Agent.<UnknownContext, TextOutput>builder()
.name("Technical Support")
.instructions("You are a technical support specialist.")
.handoffDescription("Handles technical support questions")
.build();
Agent<UnknownContext, TextOutput> billingAgent =
Agent.<UnknownContext, TextOutput>builder()
.name("Billing Support")
.instructions("You handle billing and payment questions.")
.handoffDescription("Handles billing and payment questions")
.build();
// Create triage agent with handoffs
Agent<UnknownContext, TextOutput> triageAgent =
Agent.<UnknownContext, TextOutput>builder()
.name("Triage")
.instructions("You route customer requests to the right specialist.")
.handoffs(List.of(supportAgent, billingAgent))
.build();
// Run - automatically hands off to appropriate agent
RunResult<UnknownContext, ?> result =
Runner.run(triageAgent, "My app keeps crashing, can you help?");View complete handoff example →
Manage conversation history across turns:
import ai.acolite.agentsdk.core.Session;
import ai.acolite.agentsdk.core.memory.MemorySession;
import ai.acolite.agentsdk.core.RunConfig;
// Create an in-memory session
Session session = new MemorySession("conversation-123");
// Create agent
Agent<UnknownContext, TextOutput> agent =
Agent.<UnknownContext, TextOutput>builder()
.name("Assistant")
.instructions("You are a helpful assistant with a good memory.")
.build();
// Use session across multiple turns
RunConfig config = RunConfig.builder().session(session).build();
// Turn 1
Runner.run(agent, "My name is Alice and I love hiking.", config);
// Turn 2
Runner.run(agent, "What's the capital of France?", config);
// Turn 3 - agent remembers your name!
RunResult<UnknownContext, ?> result =
Runner.run(agent, "What's my name?", config);
// Response: "Your name is Alice!"For persistent storage, use SQLiteSession:
import ai.acolite.agentsdk.core.memory.SQLiteSession;
Session session = new SQLiteSession("conversations.db", "user-123");View memory example → | View SQLite example →
Monitor agent execution with distributed tracing:
import ai.acolite.agentsdk.core.tracing.TraceProvider;
import ai.acolite.agentsdk.core.tracing.ConsoleTraceProcessor;
// Enable console tracing (development)
TraceProvider.configure(new ConsoleTraceProcessor());
// All agent operations are automatically traced
Agent<UnknownContext, TextOutput> agent =
Agent.<UnknownContext, TextOutput>builder()
.name("TracedAgent")
.instructions("You are a helpful assistant.")
.build();
Runner.run(agent, "Hello!");
// Traces will be printed to console showing execution flowView complete tracing example →
git clone https://github.com/bnbarak/openai-agent-sdk.git
cd openai-agent-sdk
mvn clean install# Unit tests only (fast)
mvn test
# All tests including integration tests (requires a real API key and may incur costs)
mvn verify -Pe2eThis project uses Spotless with Google Java Format:
# Check formatting
mvn spotless:check
# Apply formatting
mvn spotless:apply📖 Full Documentation - Complete guides and tutorials
Guides:
- Agents - Creating and configuring agents
- Tools - Building custom function tools
- Handoffs - Multi-agent coordination
- Sessions - Memory and conversation history
- Tracing - Monitoring and debugging
- Running Agents - Execution patterns
Reference:
Contributions are welcome! Please read our Contributing Guide first.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Run tests (
mvn test) - Format code (
mvn spotless:apply) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
- We are appreciative of the great work Stainless is doing on the OpenAI Java SDK, which enabled this SDK.
- Built on top of the official OpenAI Java SDK
- Inspired by the OpenAI Agents TypeScript SDK
- 📧 Email: support@acolite.ai
- 💬 GitHub Issues: Report a bug
- 📖 Documentation: bnbarak.github.io/openai-agent-sdk
Made with ❤️ by Acolite AI