AI Agent Development Guide: Core Concepts, Architecture, and Practical LangChain4j Examples

Core Concepts of AI Agent

AI Agent combines a large language model (LLM), tool invocation, memory, and planning to enable proactive task completion.

Four Core Abilities

Perception – parse user input (text, voice, image), fetch environmental data (APIs, databases, sensors), and identify task intent.

Planning – decompose a task into ordered steps, select appropriate tools, and optimise execution order.

Action – call tools (functions, APIs, scripts) and interact with external systems.

Reflection – verify results against expectations, detect errors, and improve from experience.

Agent Architecture

┌─────────────────────────────────────────┐
│              User Input                │
└─────────────────┬───────────────────────┘
                  ↓
┌─────────────────────────────────────────┐
│  Perception Layer: intent & key info    │
└─────────────────┬───────────────────────┘
                  ↓
┌─────────────────────────────────────────┐
│  Planning Layer: task split & strategy │
└─────────────────┬───────────────────────┘
                  ↓
┌─────────────────────────────────────────┐
│  Execution Layer: tool calls & actions │
└─────────────────┬───────────────────────┘
                  ↓
┌─────────────────────────────────────────┐
│  Reflection Layer: result check & fix │
└─────────────────┬───────────────────────┘
                  ↓
┌─────────────────────────────────────────┐
│               Return Result            │
└─────────────────────────────────────────┘

Typical Application Scenarios

Intelligent Customer Service – automatic answering and business processing (difficulty ★★★).

Code Assistant – code generation and debugging (difficulty ★★★★).

Data Analysis – data query and report generation (difficulty ★★★★).

Workflow Automation – coordination across multiple systems (difficulty ★★★★★).

Personal Assistant – schedule management and information aggregation (difficulty ★★★★★).

Developing Agents with LangChain4j

1. Add Maven Dependencies

<dependencies>
    <!-- LangChain4j core -->
    <dependency>
        <groupId>dev.langchain4j</groupId>
        <artifactId>langchain4j</artifactId>
        <version>0.35.0</version>
    </dependency>
    <!-- OpenAI support -->
    <dependency>
        <groupId>dev.langchain4j</groupId>
        <artifactId>langchain4j-open-ai</artifactId>
        <version>0.35.0</version>
    </dependency>
    <!-- Tool annotation support -->
    <dependency>
        <groupId>dev.langchain4j</groupId>
        <artifactId>langchain4j</artifactId>
        <version>0.35.0</version>
    </dependency>
</dependencies>

2. Define Tools

import dev.langchain4j.agent.tool.Tool;
import dev.langchain4j.agent.tool.P;
import org.springframework.stereotype.Component;

@Component
public class BusinessTools {

    @Tool("查询指定订单的详细信息")
    public String queryOrder(@P("订单 ID") String orderId) {
        return String.format("订单 %s：状态=已发货，金额=299 元，商品=无线耳机", orderId);
    }

    @Tool("查询用户的基本信息")
    public String queryUser(@P("用户 ID") String userId) {
        return String.format("用户 %s：姓名=张三，等级=VIP，积分=1500", userId);
    }

    @Tool("向用户发送通知消息")
    public boolean sendNotification(@P("用户 ID") String userId, @P("消息内容") String message) {
        System.out.println("发送通知给 " + userId + ": " + message);
        return true;
    }

    @Tool("根据用户等级计算折扣后的价格")
    public double calculateDiscount(@P("原价") double originalPrice, @P("用户等级") String userLevel) {
        double discount = switch (userLevel.toUpperCase()) {
            case "VIP" -> 0.8;
            case "PLUS" -> 0.9;
            default -> 1.0;
        };
        return originalPrice * discount;
    }
}

3. Build a Basic Agent

import dev.langchain4j.memory.ChatMemory;
import dev.langchain4j.memory.chat.MessageWindowChatMemory;
import dev.langchain4j.model.chat.ChatLanguageModel;
import dev.langchain4j.model.openai.OpenAiChatModel;
import dev.langchain4j.service.AiServices;

public class CustomerServiceAgent {
    interface Assistant {
        String chat(String userMessage);
    }

    public static void main(String[] args) {
        ChatLanguageModel model = OpenAiChatModel.builder()
                .apiKey(System.getenv("OPENAI_API_KEY"))
                .modelName("gpt-4o")
                .build();
        BusinessTools tools = new BusinessTools();
        ChatMemory memory = MessageWindowChatMemory.withMaxMessages(20);
        Assistant agent = AiServices.builder(Assistant.class)
                .chatLanguageModel(model)
                .tools(tools)
                .chatMemory(memory)
                .build();
        String response = agent.chat("帮我查一下订单 ORD123456 的状态");
        System.out.println(response);
    }
}

4. Multi‑Tool Collaboration

public class MultiToolAgent {
    public static void main(String[] args) {
        ChatLanguageModel model = OpenAiChatModel.builder()
                .apiKey(System.getenv("OPENAI_API_KEY"))
                .modelName("gpt-4o") // requires function calling support
                .build();
        BusinessTools tools = new BusinessTools();
        Assistant agent = AiServices.builder(Assistant.class)
                .chatLanguageModel(model)
                .tools(tools)
                .build();
        // Scenario 1: query order
        String response1 = agent.chat("我的订单 ORD123456 发货了吗？");
        // Scenario 2: query user then calculate discount
        String response2 = agent.chat("我是 VIP 用户，买 299 元的东西能便宜多少？");
        // Scenario 3: full flow – query user then order
        String response3 = agent.chat("帮我查一下用户 U001 的信息，然后告诉他订单 ORD123 的状态");
    }
}

Advanced Agent Patterns

Planning Agent (task decomposition)

public class PlanningAgent {
    private final ChatLanguageModel model;
    private final BusinessTools tools;
    public PlanningAgent() {
        this.model = OpenAiChatModel.builder()
                .apiKey(System.getenv("OPENAI_API_KEY"))
                .modelName("gpt-4o")
                .build();
        this.tools = new BusinessTools();
    }
    /** Execute a complex task */
    public String executeTask(String taskDescription) {
        String planningPrompt = """
            请分析以下任务，并分解为具体的执行步骤：
            任务：%s
            可用工具：
            1. queryOrder(orderId) - 查询订单
            2. queryUser(userId) - 查询用户
            3. sendNotification(userId, message) - 发送通知
            4. calculateDiscount(price, level) - 计算折扣
            请按顺序列出需要调用的工具和参数。
            """.formatted(taskDescription);
        String plan = model.generate(planningPrompt);
        System.out.println("任务规划：" + plan);
        Assistant agent = AiServices.builder(Assistant.class)
                .chatLanguageModel(model)
                .tools(tools)
                .build();
        return agent.chat(taskDescription);
    }
}

Reflective Agent (verification & retry)

public class ReflectiveAgent {
    private final ChatLanguageModel model;
    private final BusinessTools tools;
    public ReflectiveAgent() {
        this.model = OpenAiChatModel.builder()
                .apiKey(System.getenv("OPENAI_API_KEY"))
                .modelName("gpt-4o")
                .build();
        this.tools = new BusinessTools();
    }
    /** Execute with reflection and up to three retries */
    public String executeWithReflection(String task) {
        int maxRetries = 3;
        String lastResult = null;
        for (int i = 0; i < maxRetries; i++) {
            Assistant agent = AiServices.builder(Assistant.class)
                    .chatLanguageModel(model)
                    .tools(tools)
                    .build();
            String result = agent.chat(task);
            String reflectionPrompt = """
                请检查以下执行结果是否合理：
                任务：%s
                结果：%s
                如果结果有问题，请指出并说明如何改进。
                如果结果合理，请回复\"OK\"。
                """.formatted(task, result);
            String reflection = model.generate(reflectionPrompt);
            if (reflection.contains("OK")) {
                return result;
            }
            lastResult = result;
            System.out.println("第 " + (i + 1) + " 次尝试，需要改进：" + reflection);
        }
        return "执行失败，最后结果：" + lastResult;
    }
}

Multi‑Agent Cooperation

public class MultiAgentSystem {
    private final Assistant customerServiceAgent;
    private final Assistant technicalAgent;
    private final Assistant routerAgent;
    public MultiAgentSystem() {
        ChatLanguageModel model = OpenAiChatModel.builder()
                .apiKey(System.getenv("OPENAI_API_KEY"))
                .modelName("gpt-4o")
                .build();
        BusinessTools tools = new BusinessTools();
        this.customerServiceAgent = AiServices.builder(Assistant.class)
                .chatLanguageModel(model)
                .tools(tools)
                .build();
        this.technicalAgent = AiServices.builder(Assistant.class)
                .chatLanguageModel(model)
                .build();
        this.routerAgent = AiServices.builder(Assistant.class)
                .chatLanguageModel(model)
                .build();
    }
    /** Route request to the appropriate agent */
    public String handleRequest(String userMessage) {
        String routePrompt = """
            请判断以下问题属于哪一类：
            问题：%s
            回复\"customer\"表示业务问题，回复\"technical\"表示技术问题。只回复一个单词。
            """.formatted(userMessage);
        String route = routerAgent.chat(routePrompt).trim().toLowerCase();
        if (route.contains("customer")) {
            return customerServiceAgent.chat(userMessage);
        } else {
            return technicalAgent.chat(userMessage);
        }
    }
}

Real‑World Projects

Intelligent Customer Service Agent (Spring REST)

@RestController
@RequestMapping("/api/agent")
public class AgentController {
    @Autowired private ChatLanguageModel chatModel;
    @Autowired private BusinessTools businessTools;

    @PostMapping("/chat")
    public ResponseEntity<AgentResponse> chat(@RequestBody AgentRequest request) {
        ChatMemory memory = getSessionMemory(request.getSessionId());
        Assistant agent = AiServices.builder(Assistant.class)
                .chatLanguageModel(chatModel)
                .tools(businessTools)
                .chatMemory(memory)
                .build();
        String systemPrompt = """
            你是一位专业的客服助手，负责帮助用户查询订单、解答问题。
            1. 态度友好、专业
            2. 使用简洁清晰的语言
            3. 必要时主动询问补充信息
            4. 不知道的事情不要编造
            """;
        String response = agent.chat(systemPrompt + "

用户：" + request.getMessage());
        return ResponseEntity.ok(new AgentResponse(response));
    }

    private ChatMemory getSessionMemory(String sessionId) {
        // In a real project this should be persisted
        return MessageWindowChatMemory.withMaxMessages(20);
    }
}

public class AgentRequest { private String message; private String sessionId; /* getters/setters */ }
public class AgentResponse { private String reply; public AgentResponse(String reply) { this.reply = reply; } /* getter/setter */ }

Data Analysis Agent

@Service
public class DataAnalysisAgent {
    @Autowired private ChatLanguageModel chatModel;
    @Component
    public static class DataTools {
        @Tool("查询销售数据")
        public String querySales(@P("日期范围，如：2024-01") String dateRange) {
            return "2024 年 1 月销售额：150 万元，环比增长 15%";
        }
        @Tool("查询用户数据")
        public String queryUsers(@P("用户类型，如：VIP、普通") String userType) {
            return "VIP 用户数：5000，占比 10%";
        }
        @Tool("生成数据报表")
        public String generateReport(@P("报表类型") String reportType, @P("数据内容") String data) {
            return "=== " + reportType + " ===
" + data;
        }
    }
    public String analyzeAndReport(String request) {
        DataTools tools = new DataTools();
        Assistant agent = AiServices.builder(Assistant.class)
                .chatLanguageModel(chatModel)
                .tools(tools)
                .build();
        String prompt = """
            请根据用户需求查询数据并生成分析报告。
            用户需求：%s
            要求：
            1. 先查询相关数据
            2. 分析数据趋势
            3. 生成简洁的总结报告
            """.formatted(request);
        return agent.chat(prompt);
    }
}

Workflow Automation Agent

@Service
public class WorkflowAgent {
    @Autowired private ChatLanguageModel chatModel;
    @Component
    public static class WorkflowTools {
        @Tool("创建任务")
        public String createTask(@P("任务描述") String description, @P("负责人") String assignee) {
            return "任务已创建：ID=TASK001, 描述=" + description;
        }
        @Tool("发送邮件")
        public boolean sendEmail(@P("收件人") String to, @P("主题") String subject, @P("内容") String body) {
            System.out.println("发送邮件给：" + to);
            return true;
        }
        @Tool("更新数据库")
        public boolean updateDatabase(@P("表名") String table, @P("数据") String data) {
            System.out.println("更新表 " + table + ": " + data);
            return true;
        }
    }
    public String executeWorkflow(String workflowDescription) {
        WorkflowTools tools = new WorkflowTools();
        Assistant agent = AiServices.builder(Assistant.class)
                .chatLanguageModel(chatModel)
                .tools(tools)
                .build();
        String prompt = """
            请执行以下工作流程：
            %s
            要求：
            1. 按顺序执行每个步骤
            2. 每步执行后确认结果
            3. 如有错误及时报告
            """.formatted(workflowDescription);
        return agent.chat(prompt);
    }
}

Optimization Techniques

Prompt Optimization

String optimizedPrompt = """
    你是一位专业的客服助手，名叫小智。

    【能力范围】
    - 查询订单状态
    - 查询用户信息
    - 发送通知
    - 计算折扣

    【行为规范】
    1. 态度友好、专业
    2. 使用简洁清晰的语言
    3. 不知道的事情不要编造，如实告知
    4. 必要时主动询问补充信息

    【回复格式】
    - 查询结果：直接呈现关键信息
    - 操作步骤：分步骤说明
    - 复杂内容：使用列表或表格

    【限制】
    - 不处理与业务无关的问题
    - 不透露内部技术细节
    - 不承诺无法确定的事情
    """;

Tool Design Principles

Single Responsibility – each tool performs one distinct function.

Clear Naming – tool names express their purpose.

Comprehensive Documentation – describe purpose and parameters fully.

Error Handling – return explicit error messages.

@Tool("根据订单 ID 查询订单状态，返回订单详细信息")
public String getOrderStatus(@P("订单 ID，格式：ORD 开头 + 数字") String orderId) {
    if (!orderId.startsWith("ORD")) {
        return "错误：订单 ID 格式不正确，应以 ORD 开头";
    }
    // ... actual lookup logic
    return "...";
}

Memory Management

// Choose memory size per scenario
ChatMemory shortMemory = MessageWindowChatMemory.withMaxMessages(5);   // simple Q&A
ChatMemory mediumMemory = MessageWindowChatMemory.withMaxMessages(20); // general dialogue
ChatMemory longMemory = MessageWindowChatMemory.withMaxMessages(50);   // complex tasks
// Persistent memory example
ChatMemory persistentMemory = new PersistentChatMemory(
        sessionId -> loadFromFile(sessionId),
        (sessionId, messages) -> saveToFile(sessionId, messages)
);

Frequently Asked Questions

Agent Calls Wrong Tool

Refine tool descriptions for clarity.

Specify tool usage scenarios in the system prompt.

Provide usage examples.

Context Lost in Multi‑turn Dialogue

Increase memory size.

Use persistent storage.

Pass key information explicitly in each turn.

Complex Task Execution Fails

Add explicit planning steps.

Implement reflection and retry mechanisms.

Break the task into smaller sub‑tasks.