Building Reliable Java AI Agents with JetBrains’ Koog Framework

JetBrains, known for IntelliJ IDEA, recently launched Koog for Java, an AI Agent framework that offers a native Java Builder‑style API rather than a Kotlin‑only add‑on.

Origin of Koog

During development of JetBrains’ AI Assistant and the Junie coding assistant, the company initially used Python services for AI tasks. As the Agent system grew more complex—handling multi‑step workflows, tool chains, and state management—the Python approach became a bottleneck, prompting JetBrains to implement the functionality directly on the JVM.

Early versions exposed only a Kotlin API; version 0.7.2 (March 2024) added a full Java API with Builder patterns, annotation‑driven tool definitions, and thread‑pool management familiar to Java developers.

Core Capabilities

Defining a Simple Agent

Annotate Java methods with @Tool and @LLMDescription to expose them as callable tools for the Agent.

public class BankingTools implements ToolSet {
    @Tool
    @LLMDescription("向指定收款人转账")
    public Boolean sendMoney(@LLMDescription("收款人的唯一标识") String recipientId,
                             @LLMDescription("转账金额，单位：元") Integer amount) {
        return true; // 你的转账逻辑
    }

    @Tool
    @LLMDescription("查询用户的账户余额，返回余额金额")
    public Integer getAccountBalance(@LLMDescription("用户ID") String userId) {
        return 1000000; // 你的余额查询逻辑
    }
}

Assemble the Agent with a Builder API:

MultiLLMPromptExecutor promptExecutor = new MultiLLMPromptExecutor(
    new OpenAILLMClient("OPENAI_API_KEY")
);

AIAgent bankingAgent = AIAgent.builder()
    .promptExecutor(promptExecutor)
    .llmModel(OpenAIModels.Chat.GPT5_4)
    .systemPrompt("你是一个银行转账助手，帮用户查询余额和转账")
    .toolRegistry(
        ToolRegistry.builder()
            .tools(new BankingTools())
            .build()
    )
    .build();

bankingAgent.run("帮我看看余额够不够，够的话给老王(wang_0056)转 500 块");

The Agent automatically decides to call getAccountBalance first, then sendMoney if the balance is sufficient, without any explicit if‑else logic.

Real‑World Example: E‑Commerce Customer Service Agent

Define tools for order lookup, inventory check, and order creation:

<dependency>
    <groupId>ai.koog</groupId>
    <artifactId>koog-agents-jvm</artifactId>
    <version>0.7.2</version>
</dependency>

public class ECommerceTools implements ToolSet {
    @Tool
    @LLMDescription("根据订单号查询订单状态，返回订单详情")
    public String queryOrder(@LLMDescription("用户的订单号，例如 ORD-20260325-001") String orderId) {
        return "订单 " + orderId + " 状态：已发货，预计明天送达";
    }

    @Tool
    @LLMDescription("根据商品名称查询库存数量")
    public String checkInventory(@LLMDescription("商品名称，例如：机械键盘") String productName) {
        return productName + " 当前库存：128 件";
    }

    @Tool
    @LLMDescription("为用户创建新订单")
    public String createOrder(@LLMDescription("用户ID") String userId,
                              @LLMDescription("商品名称") String productName,
                              @LLMDescription("购买数量") Integer quantity) {
        String orderId = "ORD-" + System.currentTimeMillis();
        return "下单成功，订单号：" + orderId + "，商品：" + productName + " x " + quantity;
    }
}

Build the customer‑service Agent:

MultiLLMPromptExecutor promptExecutor = new MultiLLMPromptExecutor(
    new OpenAILLMClient("OPENAI_API_KEY")
);

AIAgent customerServiceAgent = AIAgent.builder()
    .promptExecutor(promptExecutor)
    .llmModel("deepseek-chat")
    .systemPrompt(
        "你是一个电商平台的智能客服。用简洁友好的中文回答用户问题。" +
        "你可以帮用户查订单、查库存、下单。" +
        "如果用户的问题超出你的能力范围，礼貌地建议用户联系人工客服。"
    )
    .toolRegistry(
        ToolRegistry.builder()
            .tools(new ECommerceTools())
            .build()
    )
    .build();

customerServiceAgent.run("帮我看看订单 ORD-20260325-001 到哪了");

The Agent calls queryOrder and replies in Chinese. If the user wants to purchase, it checks inventory with checkInventory and creates an order via createOrder, all driven by the LLM without manual branching.

Strict Functional Strategy

For tighter control, a functional strategy can lock the workflow into distinct intent‑understanding and execution phases:

AIAgent strictAgent = AIAgent.builder()
    .promptExecutor(promptExecutor)
    .functionalStrategy("strict-order-flow", (ctx, userInput) -> {
        String intent = ctx.subtask(
            "判断用户意图，只返回：查订单、查库存、下单、其他。用户说：" + userInput
        ).withOutput(String.class).run();

        String result = ctx.subtask(
            "根据用户意图执行操作：" + intent + "，原始输入：" + userInput
        ).withOutput(String.class).withTools(new ECommerceTools()).run();

        return result;
    })
    .build();

Conclusion

In 2026 the Java AI Agent ecosystem is vibrant: Spring AI provides infrastructure, LangChain4j unifies APIs, and Koog fills the gap in Agent orchestration with a developer‑friendly, JVM‑native approach that aligns with JetBrains’ long‑standing focus on tooling ergonomics.