跪拜 Guibai
← Back to the summary

Agent Development Blueprint: From Prompts to Autonomous Digital Employees

Title: AI Agent Technology Panorama Analysis – From Prompt Engineering to Advanced Agent Construction

Author: vivo Internet Technology

Author: vivo Internet R&D Efficiency Team - Wu Qinghua
This article systematically reviews the full panorama of AI Agent technology evolution, with the core goal of building "digital employees" that can autonomously plan, call tools, and deliver results. From prompt engineering (how to precisely convey intent), to RAG (how to access external knowledge), to Harness engineering (how to keep models running reliably), to ReAct loops (how to impart autonomous decision-making and execution), and finally to multi-agent collaboration.

1 minute to see the core points👇

Introduction: From "Q&A Tools" to "Digital Employees"

The AI interaction we are familiar with

Everyone has used ChatGPT or similar large language models. The interaction is simple: you ask a question, it gives an answer. This "conversational" interaction is already powerful, but on reflection, it has three obvious limitations:

As an analogy: this is like a learned advisor without hands, feet, or memory. You have to re-explain the background every time; he gives you advice, but you have to execute it yourself.

Core problem

What do we really want? An "intelligent agent" that can understand a goal, plan autonomously, and execute complex tasks — like a new employee: you give a task, it decomposes steps, calls tools, adjusts when encountering problems, and finally delivers results.

That is the core problem AI Agent aims to solve.

A brief history of evolution

Before we formally start, let's quickly review how this technology path has evolved — understanding history helps us see the future:

A single main thread runs through: from "humans write prompts for LLMs to execute" to "LLMs plan and execute themselves" — autonomy increases step by step, and each step brings new engineering challenges.

Today's roadmap

In this talk, I will take you through this path:

Each step did not appear out of nowhere; it emerged because the previous step could no longer keep up. Understand this causal chain, and you understand the full picture of Agents.

一、Foundation: The Art of Efficient Collaboration with LLMs

Before building Agents, we must first master efficient communication with LLMs. This part covers three levels of "collaboration art."

1.1 Prompt Engineering

Problem it solves: How to precisely convey intent to an LLM and get high-quality answers?

This is the starting point of human-machine collaboration. The quality of LLM output is highly dependent on input — the same question, phr differently, can yield drastically different results. This is not a bug but an inevitable consequence of LLM's probabilistic reasoning: the prompt determines which direction the model moves in probability space.

Underlying principle: Why prompt is so important

To understand why prompt engineering works, we need to go back to how LLMs work. An LLM is essentially an autoregressive language model — it does "given the previous tokens, predict the probability distribution of the next token":

P(token_n | token_1, token_2, ..., token_{n-1})

This means:

Understanding this, you'll see why prompt is not "flowery language" but an engineering tool to control the LLM's output distribution.

Basic techniques

The framework automatically picks the path based on model capability: models that natively support structured output use the response_format parameter; those that don't fall back to "synthetic tool + instruction" — but this is transparent to the caller.

Advanced techniques

Chain-of-Thought (CoT): Let the LLM "think before answering" by writing out its reasoning. Essentially, it breaks down a single-step intuitive judgment into multi-step explicit reasoning, each step narrowing the probability space and lowering the per-step error rate. This idea later directly evolved into the ReAct loop for Agents.

The information-theoretic reason CoT works: when directly generating the final answer, the model must complete the entire "input to output" mapping in one step; that mapping has high entropy (high uncertainty) and high error probability. CoT splits this mapping into multiple steps, each with lower entropy (from one reasoning state to the next is more certain), so each step's error rate is lower, and overall accuracy rises.

Self-Consistency: Let the LLM reason multiple times on the same question (set temperature > 0) and take a majority vote. Use "consensus of multiple independent reasonings" instead of "the intuition of a single reasoning" to reduce randomness. The cost is N times more compute.

Horizontal comparison: trade-offs among prompt strategies

A trend: Newer models are increasingly internalizing CoT in their training — models learn to "think internally," so users no longer need to manually add "think step by step." But understanding the principle of CoT remains important because it is the conceptual source of the ReAct loop.

Analogy: Prompt engineering is like writing a "communication guide" for a smart new employee who doesn't yet know your business. The clearer the guide, the more the deliverable meets expectations.

1.2 Context Engineering (RAG)

Problem it solves: LLM context windows are limited; how to handle tasks that need external knowledge or very long content?

Prompt engineering handles "how to say it clearly in one inference," but soon we hit a problem: some knowledge is not in the prompt; the LLM simply doesn't know it. For example, your company's reimbursement policy, the latest product docs, a customer's historical orders — none of this is in the LLM's training data.

Why not directly fine-tune?

A natural question: if the LLM doesn't know private knowledge, why not fine-tune it on private data? What advantage does RAG have over fine-tuning?

Core difference: Fine-tuning changes the model's "capability" (how to answer), RAG changes the model's "input" (what it answers based on). Factual knowledge suits RAG (updatable, traceable), behavioral patterns / domain reasoning suit fine-tuning. They are not mutually exclusive; real systems often combine them.

RAG workflow

RAG (Retrieval-Augmented Generation) core process:

The elegance of RAG: instead of stuffing all knowledge into the LLM, retrieve on demand when needed. Just as a person doesn't need to memorize an encyclopedia but can look things up when encountering a problem.

Underlying principle: how vector retrieval works

How exactly do we "look up"? Typically with vector retrieval:

Why can embeddings capture semantic similarity? During training, the embedding model learns to map "semantically similar" texts to "spatially close" vectors. For instance, "how to reimburse travel expenses" and "travel expense reimbursement process" — though different wording, their embedding vectors' cosine similarity will be high. This is far stronger than keyword matching — keyword matching finds "literal matches," vector retrieval finds "similar meaning."

    // Example of connecting a knowledge base in AgentScope
    KnowledgeBase kb = new BailianKnowledge(baseConfig);
    
    ReActAgent agent = ReActAgent.builder()
            .name("assistant")
            .model("dashscope:qwen-max")
            .knowledgeBase(kb)        // Register knowledge base
            .build();
    
    // Agent automatically retrieves from the KB when it needs domain knowledge
    Msg result = agent.call(
            List.of(new UserMessage("What is our company's travel expense reimbursement standard?")),
            RuntimeContext.empty()
    ).block();
    // Internally: retrieve "travel reimbursement" doc chunks → splice into prompt → LLM answers based on docs

RAG advanced: not just "retrieve + splice"

Naive RAG (retrieve Top-K into prompt) has many variants to improve results:

RAG solves two key problems: knowledge staleness (knowledge base can be updated anytime) and hallucination (LLM answers based on retrieved real documents, not fabricated). It is also the foundation for Agents to connect to external knowledge bases.

Analogy: If prompt engineering is writing a "communication guide" for a new employee, RAG is giving him a "company internal document retrieval system" — he doesn't need to memorize all docs, just search when needed.

1.3 Harness Engineering (Agent's Runtime Infrastructure)

Problem it solves: A single prompt cannot complete complex tasks; how to chain multiple LLM calls into a workflow?

Evolution from "Chains" to "Harness"

So far we've talked about "one LLM call." But real tasks often require multiple steps:

In 2022, LangChain proposed the concept of "Chains" — chaining multiple LLM calls (and non-LLM processing steps) into a pipeline. That was the earliest process orchestration attempt:

    # LangChain's early "chain" paradigm (pseudocode)
    chain = LLMChain(
        llm=OpenAI(),
        prompt=PromptTemplate("Translate the following text to English: {text}")
    )
    result = chain.run(text="Hello world")

But "chains" have a fundamental limitation: they are a fixed, developer-hardcoded process. The path, branches, and loops are all written in advance. Once a task needs to "decide what to do next dynamically," chains fall short.

This gave rise to the shift from "chains" to "Agents" — and Agents require long-running, state management, security controls and other engineering infrastructure. That is Harness Engineering.

Harness Engineering concerns the runtime infrastructure: what supporting layers are needed to let an autonomous Agent run for a long time, reliably. It doesn't solve "which path to take" but "how not to crash while on the road."

In AgentScope 2.0, this orchestration capability is systematized as Harness Engineering. It does not just string calls together; it also handles:

Underlying principle: Middleware onion model

Harness's core extension mechanism is Middleware — it borrows the "onion model" from web frameworks (like Express, Koa), inserting custom logic at key points of the ReAct loop:

Each middleware can intervene at "before" and "after" points. For example, you can write an audit middleware that records "which tool is about to be called" at the "before" of onActing, and "what the tool returned" at the "after" — without affecting other logic.

    // Custom Middleware example: log all tool calls to audit log
    public class AuditMiddleware extends MiddlewareBase {
    
        @Override
        public Mono<Void> onActing(ActingContext ctx, MiddlewareNext next){
            String toolName = ctx.getToolCall().getName();
            String userInput = ctx.getToolCall().getInput().toString();
            auditLog.info("Tool call start: tool={}, input={}", toolName, userInput);
    
            return next.proceed(ctx)
                    .doOnSuccess(v -> {
                        String result = ctx.getToolResult().getTextContent();
                        auditLog.info("Tool call end: tool={}, resultLen={}",
                                toolName, result.length());
                    });
        }
    }
    
    ReActAgent agent = ReActAgent.builder()
            .name("audited_agent")
            .model("dashscope:qwen-max")
            .middlewares(List.of(new AuditMiddleware()))
            .build();

Key design: Harness's built-in capabilities (compression, memory, sub-agents, Plan Mode) are all implemented as middleware, hooked into key points of the ReAct loop. The core reasoning algorithm itself stays unchanged; Harness only adds to it. This means you can enable on demand — turn off everything you don't need, and the Agent still runs.

Horizontal comparison: mainstream orchestration frameworks

Selection advice: For simple LLM apps, use LangChain for quick prototypes; for RAG-centric apps, use LlamaIndex; for building production-grade autonomous Agents, use AgentScope. They are not mutually exclusive — AgentScope can also integrate LlamaIndex's retrieval capabilities.

Harness Engineering turns the LLM from a "single-point tool" into a "link in a pipeline" — a key step toward Agent automation.

Analogy: If prompt engineering is the "communication guide" and RAG is the "document retrieval system," then Harness Engineering is the "standard operating procedure (SOP)" — orchestrating multiple steps into a repeatable, monitorable pipeline.

二、Core: Building Autonomous AI Agents

The three foundations above are still essentially "human-driven, LLM-executed" patterns. Now we enter the real Agent territory — endowing AI with autonomy.

2.1 Agent's "Brain" — Planning & Decision-Making

Problem it solves: Facing complex goals, how does an Agent autonomously decide "what to do first, what next"?

Evolution of planning paradigms

Agent planning capability has evolved through several generations, each addressing the limitations of the previous:

Generation 1: Plan-then-Execute

Idea: First use an LLM to generate a complete plan, then execute step by step.

Limitation: The plan is static. If execution finds a step unworkable, the whole plan collapses — but in the real world, "encountering surprises during execution" is the norm.

Generation 2: ReAct (Reason + Act interleaved) — current mainstream

ReAct (Reason + Act) core idea is interleaving reasoning and action:

The elegance of ReAct: it is not "think through all steps first then execute" (pure planning), nor "blindly execute without thinking" (pure action), but "think one step, do one step, see the result, then think the next step." This resembles how humans solve unfamiliar problems.

The actual prompt fed to the LLM inside a ReAct loop, simplified, looks like this:

    You are a tool-using assistant. Answer in the following format:
    
    Thought: I need to first understand what the user wants...
    Action: search_web
    Action Input: {"query": "Spring Boot 3.2 new features"}
    
    (framework executes tool, returns result)
    
    Observation: Spring Boot 3.2 main updates include...
    
    Thought: Now I know the main features, I can summarize
    Action: [no tool needed, answer directly]
    Final Answer: Main new features of Spring Boot 3.2 include...

In each iteration, the LLM can see: all previous Thoughts, Actions, Observations. This means it can dynamically adjust subsequent plans based on execution results — something Plan-then-Execute cannot do.

Generation 3: Tree of Thoughts / MCTS — frontier exploration

ReAct is "single-chain reasoning" — one path to the end. But some complex problems require "exploring multiple paths and backtracking from unreliable branches." Tree of Thoughts organizes reasoning as a tree, supports branch exploration and backtracking, similar to Monte Carlo Tree Search (MCTS) in game-playing AI.

The cost is much higher (each node is an LLM call); currently mainly research-stage, rarely in production.

Horizontal comparison: three planning paradigms

For very complex tasks, Plan Mode can be added on top of ReAct: the Agent first analyzes the task in a read-only mode, generates a plan file, the user reviews it, then the Agent executes according to the plan. This achieves decoupling of intent and action — think clearly about what to do before doing it.

2.2 Agent's Core Loop and Architecture

What is the essential difference between an Agent and a normal LLM application? It is "autonomy."

A normal LLM app is "you give an input, it gives an output." An Agent is "you give a goal, it decides how to do it, and tells you the result when done."

Traditional programs vs Agents: transfer of control

Understanding Agents is best done by contrasting with traditional programs:

Traditional programs: Control flow is hardcoded. If-else branches, for-loop counts, which function to call — all predetermined. The program is a "developer-controlled executor."

Agents: Control flow is dynamically decided by the LLM at runtime. What to do next, which tool to call, when to stop — all judged by the LLM based on current context. The program becomes an "LLM-driven executor."

This is a fundamental shift: control transfers from developer to LLM. The developer no longer writes "execution logic" but "execution framework" — the framework defines where and what decisions the LLM can make, but the specific decision content is judged by the LLM based on context.

What implements this autonomy is the Agent's core control loop:

Each stage of this loop:

Actual control flow in AgentScope

In AgentScope, this loop is concretely implemented in the ReActAgent main loop:

Several noteworthy runtime mechanisms:

This loop is the framework for understanding all subsequent components — tools are the "hands and feet" of the execution stage, memory is the state running through the loop, knowledge base is a reference for planning and execution. Every later component maps to a place in this loop.

2.3 Agent's "Hands and Feet" — Tools and Skills

Problem it solves: LLMs cannot interact with the outside world (calling APIs, reading/writing files, executing code). How to give them action capability?

Tools

Tools are external functions an Agent can call. To the LLM, a tool needs to expose three things: name, description, and parameter format. The LLM uses this information to decide "when to use which tool."

Underlying principle: How Function Calling works

The complete tool call flow involves collaboration between the LLM and the framework:

    1. Framework injects the tool's JSON Schema into the LLM request
       POST /v1/chat/completions
       {
         "messages": [...],
         "tools": [{
           "type": "function",
           "function": {
             "name": "get_current_time",
             "description": "Returns the current time in the specified timezone",
             "parameters": {"type": "object", "properties": {"timezone": {"type": "string"}}}
           }
         }]
       }
    
    2. LLM decides whether to call a tool. If yes, it returns not plain text but a structured tool_call:
       {
         "tool_calls": [{
           "id": "call_abc123",
           "function": {"name": "get_current_time", "arguments": "{\"timezone\": \"Asia/Shanghai\"}"}
         }]
       }
    
    3. Framework parses tool_call, executes the corresponding Java method, gets the result
    
    4. Framework adds the tool result as a new message to the context, calls the LLM again
       → LLM continues reasoning based on the tool result

Key point: The LLM itself does not "execute" the tool; it just outputs a structured instruction "I want to call this tool." The framework actually executes the tool. The LLM does the "decision," the framework does the "execution."

    // Define tool with annotation in AgentScope; framework auto-derives JSON Schema
    @Tool(name = "get_current_time",
          description = "Returns the current time in the specified timezone",  // This description determines whether the LLM uses it
          readOnly = true)
    public String getCurrentTime(
            @ToolParam(name = "timezone", description = "IANA timezone, e.g., Asia/Shanghai")
            String timezone) {
        return LocalDateTime.now(ZoneId.of(timezone))
                .format(DateTimeFormatter.ISO_LOCAL_DATE_TIME);
    }

Here's a key point: tool descriptions must be detailed and specific. "Data query tool" is far less effective than "Query order data within a specified date range, filterable by customer ID" — because the LLM decides based on descriptions.

When the number of tools grows, two problems arise: context bloat (each tool's schema consumes tokens) and decision interference (too many tools, higher mis-selection rate). The solution is Tool Groups: group tools and activate only the groups relevant to the current task at runtime — this is "disclose on demand."

    // Tool groups: activate on demand
    ToolGroup database = new ToolGroup(
            "database", "Database operation tools",
            ToolGroupScope.SESSION, /* active = */false);
    database.addTool("db_query");
    database.addTool("db_migrate");
    
    ReActAgent agent = ReActAgent.builder()
            .name("router")
            .toolkit(toolkit)
            .enableMetaTool(true)   // Enable reset_tools meta-tool, let Agent switch tool groups itself
            .build();
    // When Agent encounters a database task, it calls reset_tools to activate the database group

MCP (Model Context Protocol)

Problem it solves: Decoupling tool providers from Agent frameworks.

Without MCP, tools written for AgentScope would need rewriting if you switch to LangChain. Every time you change framework, the tool ecosystem must be rebuilt.

MCP is a standardized protocol: tool providers implement a server according to the MCP protocol, and any MCP-supporting Agent framework can connect. It turns tools into reusable, independently deployable "microservices."

MCP protocol design

MCP defines three connection types for different deployment scenarios:

After an MCP server starts, it exposes a tool list; the client (Agent framework) auto-discovers available tools upon connection. This is the same idea as "service registration and discovery" in microservices.

    // Connecting a remote MCP server takes only a few lines
    McpClientWrapper weather = McpClientBuilder.streamableHttp()
            .name("weather").url("https://api.weather.com/mcp")
            .header("Authorization", "Bearer xxx")
            .build();
    
    Toolkit toolkit = new Toolkit();
    toolkit.registerMcpClient(weather).block();
    // Framework auto-handles protocol negotiation, tool discovery, result conversion
    // MCP tools are named mcp__weather__get_forecast in toolkit to avoid conflicts

Analogy: MCP to Agent tools is like HTTP to web services — a standard protocol decoupling producers and consumers. Just as you don't care whether a REST API is written in Java or Python, MCP means you don't care which Agent framework a tool runs in.

Skills

Tools are "what can be done" (capability), but each time the Agent processes the same type of task, it starts from scratch — it doesn't remember "what was the most effective way last time."

Skills solve this: they are the Agent's SOP, a reusable workflow document. Essentially Markdown instructions telling the Agent "how to handle this type of task."

code-reviewer/           ← A skill is a directory
├── SKILL.md             ← Instruction doc: "first search code, then read files, review per checklist"
├── references/          ← Reference materials (e.g., code style guidelines)
└── scripts/             ← Executable scripts (e.g., automated check scripts)

Essential difference between Skills and Tools: A tool is "a callable function"; a skill is "a set of workflow instructions." A skill cannot be directly called — the Agent first reads the skill instructions, then uses existing tools to execute per instructions. Skills are "knowledge," not "actions."

More advanced: an Agent can draft its own skills — successful experiences are automatically sedimented as skill drafts, which become formal skills after review. This is Agent "self-evolution": know-how accumulates across runs.

2.4 Agent's "Memory" — Short-term and Long-term

Problem it solves: How to make an Agent remember conversation history, task progress, and past experience, avoiding repeated mistakes?

LLMs are stateless — between two calls, the model remembers nothing. To give an Agent "memory" requires engineering means.

The nature of the memory problem

"Memory" sounds like one concept, but it actually includes three distinct levels:

These three levels have completely different solutions; they must not be conflated.

Memory is divided into two layers:

Short-term memory — Session Memory

Manages context within a single task/conversation. The core carrier is AgentState, which stores not just conversation history but also permission rules, task lists, tool activation states — all runtime state that affects reasoning:

AgentState
├── context              ← Conversation history (user input, assistant replies, tool calls, tool results)
├── summary              ← Compressed summary (generated when context exceeds threshold)
├── permissionContext    ← Tool permission rules (allow/ask/deny)
├── planModeContext      ← Plan Mode state (whether currently in planning phase)
├── tasksContext         ← Task list (subtask list maintained by todo_write)
└── toolContext          ← Tool group activation states (which tool groups are active)

Why are permission rules and task lists also in AgentState? Because they all influence the LLM's reasoning decisions. Permission rules determine what operations the LLM knows it can do; task lists determine what progress it knows it has made — these are as much context to see during reasoning as conversation history.

In AgentScope, the Agent instance itself is stateless — all state is externalized by (userId, sessionId):

    // Configure Redis state store — recommended for production
    ReActAgent agent = ReActAgent.builder()
            .name("assistant")
            .model("dashscope:qwen-plus")
            .stateStore(new RedisAgentStateStore(jedis))  // Distributed state store
            .build();
    
    // First call — create session, Agent looked up flights
    agent.call(List.of(new UserMessage("Help me find flights from Beijing to Shanghai")),
            RuntimeContext.builder().userId("alice").sessionId("s1").build()).block();
    
    // Second call — auto-restores previous AgentState, Agent knows what "the cheapest" refers to
    agent.call(List.of(new UserMessage("Which is the cheapest")),
            RuntimeContext.builder().userId("alice").sessionId("s1").build()).block();

One Agent instance can serve thousands of users simultaneously without interference. With a distributed backend like Redis, it also supports cross-machine failover and zero-downtime rolling releases — Agent instances on different physical machines all get exactly consistent state.

Long-term Memory

Session memory is "short-term" — archived when the session ends. But some information is cross-session: user preferences, project conventions, historical experience. These should not require the user to repeat every time.

AgentScope's long-term memory is divided into two layers, solving the contradiction of "remember long-term facts while preventing context from growing without bound":

There are three separate LLM calls here, each with its own prompt and trigger timing:

    // Memory system configuration — can use small model for memory ops to save cost
    HarnessAgent agent = HarnessAgent.builder()
        .model("openai:o3")                      // Main reasoning model (strong)
        .memory(MemoryConfig.builder()
            .model("openai:gpt-4.1-mini")        // Memory ops use small model (cheap)
            .flushTrigger(MemoryConfig.FlushTrigger.throttled(
                    Duration.ofMinutes(10)))      // Flush at most every 10 minutes
            .build())
        .compaction(CompactionConfig.builder()
            .triggerMessages(30)                  // Trigger compaction at 30 messages
            .keepMessages(10)                     // Keep latest 10
            .model("openai:gpt-4.1-mini")        // Compaction also uses small model
            .build())
        .build();

The Agent also gets a memory_search tool to actively retrieve historical memories. This is like a person having a "diary" and "experience summaries" — the diary records raw facts, the summary is distilled wisdom.

Horizontal comparison: memory solution choices

Analogy: Session is "working memory" (what you are currently thinking about), Memory is "long-term memory" (accumulated experience).

2.5 Agent's "Knowledge Base"

Problem it solves: How does an Agent acquire professional domain knowledge needed to execute tasks?

Here we return to RAG from Part 1. The knowledge base is an Agent's main source of static domain knowledge — company policy documents, product technical docs, industry standards, etc.

Difference between knowledge base and memory (commonly confused):

Difference between knowledge base and skills:

2.6 Agent's "Organization" — Multi-Agent Systems

Problem it solves: A single Agent's capabilities are limited — context pollution, too many tools, inability to parallelize. How to solve grander problems by organizing multiple Agents to collaborate?

Bottlenecks of single Agent

As task complexity grows, a single Agent hits bottlenecks. Just like one person trying to do design, development, testing, and operations simultaneously — not impossible, but inefficient and error-prone. Specifically three bottlenecks:

Core idea of Sub-Agents

Sub-Agent core idea is division of labor: each sub-agent has its own independent context, tool set, persona, and reasoning loop, can execute in parallel, without contamination.

Two delegation modes:

Multi-Agent collaboration patterns

Using a "software development team" as example:

Different collaboration patterns suit different scenarios:

Hierarchy of Tool vs Skill vs Subagent:

The three are not mutually exclusive: a sub-agent internally uses tools, and may load Skills. They are different levels of abstraction — Tool is "hands and feet," Skill is "method manual," Subagent is "another brain."

This is the evolution from "one all-round Agent" to "an Agent team" — like from "individual hero" to "high-efficiency team."

三、Practical Guide: From Concept to Implementation

The first two parts cover "what Agents are, how they work." But when implementing, you find a wide gap between "knowing the concepts" and "building a good system." In this part, we look at three practical dimensions: where to use, common pitfalls, and best practices.

3.1 Typical Scenarios: What Problems Suit Agents?

Not all problems suit Agents. The core criterion: does the task require "multi-step reasoning + dynamic decision + external tools"? If a single LLM call suffices, using an Agent is overkill.

Scenario 1: Knowledge Q&A Assistant (RAG + lightweight Agent)

Business background: Company has large volumes of documents (policies, product docs, technical wiki); employees search inefficiently.

Why Agent: Pure RAG can only "retrieve + answer," but real employee needs often require multiple steps — first check policy, then associated process, then give advice based on personal situation.

Architecture: Knowledge base (RAG) + lightweight Agent (ReAct loop + 2-3 tools: retrieval, read file, answer)

    // Knowledge Q&A assistant — simplest Agent application
    ReActAgent agent = ReActAgent.builder()
            .name("kb_assistant")
            .sysPrompt("You are the company's internal knowledge assistant. Cite document sources in answers. "
                    + "If retrieval results are insufficient, clearly say so rather than fabricate.")
            .model("dashscope:qwen-plus")
            .knowledgeBase(kb)            // Knowledge base
            .maxIters(5)                  // Knowledge QA doesn't need many iterations
            .build();

Implementation advice: This is the "entry-level" Agent app; ROI is easily quantifiable (time saved). Start here, verify results, then expand.

Scenario 2: Code Engineering Assistant (tool-intensive Agent)

Business background: Dev team needs an AI assistant that can read code, run tests, submit PRs.

Why Agent: Code tasks naturally require multiple steps — understand requirements → search relevant code → read files → modify code → run tests → fix based on test results → submit. Each step's result affects the next, a typical ReAct scenario.

Architecture: HarnessAgent + workspace (code repo) + tool set (read_file, write_file, execute_shell, search_code) + Plan Mode

    HarnessAgent agent = HarnessAgent.builder()
            .name("code_engineer")
            .sysPrompt("You are a code engineer. Understand context before modifying code, "
                    + "run tests to verify after modification.")
            .model("dashscope:qwen-max")
            .workspace(workspace)               // Code repo as workspace
            .enablePlanMode()                   // Complex changes first produce a plan
            .compaction(CompactionConfig.builder()
                    .triggerMessages(20)         // Code tasks grow context fast, compact early
                    .keepMessages(8)
                    .build())
            .build();

Implementation advice: Code scenario Agents are highly effective but high security risk — must have permission system and sandbox. Recommend first validating in read-only mode (analyze only, no modifications), then gradually grant write permissions.

Scenario 3: Data Processing and Analysis Agent (multi-tool collaboration)

Business background: Business teams need to fetch data from multiple sources, clean, analyze, generate reports.

Why Agent: Data analysis is highly dynamic — first look at data schema, decide analysis direction, write SQL to fetch, dig deeper on anomalies, finally chart. This "explore-and-decide" process cannot be done with hardcoded ETL pipelines.

Architecture: Agent + multiple tool groups (DB query, Python execution, chart generation) + knowledge base (business metric definitions)

    // Data analysis scenario — tool groups activated on demand
    ToolGroup queryGroup = new ToolGroup("db", "Database query tools", ...);
    queryGroup.addTool("sql_query");
    queryGroup.addTool("schema_inspect");
    
    ToolGroup analysisGroup = new ToolGroup("analysis", "Analysis tools", ...);
    analysisGroup.addTool("python_execute");
    analysisGroup.addTool("plot_chart");
    
    ReActAgent agent = ReActAgent.builder()
            .name("data_analyst")
            .toolkit(toolkit)
            .enableMetaTool(true)       // Let Agent switch tool groups itself
            .knowledgeBase(metricsKb)   // Business metric definitions
            .maxIters(15)               // Data exploration needs more rounds
            .build();

Implementation advice: SQL execution tool must be given a read-only database account; Python execution must run in sandbox. Data analysis Agent's value is "replacing repetitive labor of data analysts," not replacing the analyst.

Scenario 4: Multi-Agent Collaboration — Automated R&D Pipeline

Business background: Chain requirement analysis, code development, code review, test validation into an automated pipeline.

Why Multi-Agent: Each stage requires different expertise and tool sets; putting it all in one Agent causes context pollution and tool overload.

Architecture: Supervisor Agent + 4 specialized sub-agents (PM / Developer / Reviewer / Tester)

Implementation advice: Multi-Agent systems are complex; validate with a single Agent first. Early on, use "human-in-the-loop" (HITL) to replace some sub-agents, and automate gradually.

Scenarios not suited for Agents

3.2 Common Pitfalls and Avoidance Guide

During Agent deployment, these pain points hit almost everyone. These "stepping-on-rake" lessons are pre-listed.

Pain point 1: Agent "does not act as expected" — tool call decision inaccuracy

Symptom: Agent doesn't use a tool when it should, uses it wrongly, or picks the wrong tool.

Root cause: LLM decides based on tool descriptions. Vague or overlapping descriptions cause mis-selection.

Avoidance:

❌ Bad description: description = "Query data"
✅ Good description: description = "Query order records in MySQL orders table within a specified date range, "
                   "filterable by customer ID and order status. Return fields: order number, amount, status, creation time."

Pain point 2: Context explosion — token cost out of control

Symptom: In long conversations, token consumption grows linearly, costs rise, and results degrade ("lost in the middle").

Root cause: Each ReAct loop adds messages to context (reasoning + tool calls + tool results). Without management, dozens of rounds blow up the context.

Avoidance:

    // Standard production configuration
    HarnessAgent agent = HarnessAgent.builder()
            .compaction(CompactionConfig.builder()
                    .triggerMessages(20)          // Trigger at 20 messages, don't wait longer
                    .keepMessages(8)              // Keep only latest 8 + summary
                    .truncateArgs(CompactionConfig.TruncateArgsConfig.builder()
                            .maxArgLength(2000)   // Truncate tool args over 2000 chars
                            .build())
                    .build())
            .toolResultEviction(ToolResultEvictionConfig.defaults())  // Offload large results to disk
            .memory(MemoryConfig.builder()
                    .flushTrigger(MemoryConfig.FlushTrigger.throttled(
                            Duration.ofMinutes(10)))  // Throttle flush, not run every time
                    .model("dashscope:qwen-turbo")     // Memory ops use cheap model
                    .build())
            .build();

Pain point 3: Agent stuck in infinite loop — repeatedly calling the same tool

Symptom: Agent repeatedly calls the same tool or jumps between steps, unable to converge.

Root cause: Usually unclear prompt, or tool results make the LLM misjudge task state.

Avoidance:

Pain point 4: Security issues — Agent executes dangerous operations

Symptom: Agent deletes files by mistake, executes dangerous commands, sends sensitive data to external APIs.

Root cause: Agent gains action, hence destructive power. An Agent without permission control is like a car without brakes.

Avoidance:

    // Production security configuration — three lines of defense
    ReActAgent agent = ReActAgent.builder()
            .permissionContext(PermissionContextState.STRICT)  // Strict permission mode
            .toolkit(toolkit)                                   // Tool whitelist
            .build();
    
    // First line of defense: tool-level permissions
    // Write tools must be marked readOnly = false; framework will run permission checks
    @Tool(name = "delete_file", description = "Delete specified file",
          readOnly = false, dangerousDirectories = {"/etc", "/system"})
    public String deleteFile(@ToolParam(name = "path") String path){ ... }
    
    // Second line: HITL human confirmation
    // Sensitive operations trigger RequireUserConfirmEvent, pause and wait for human confirmation
    // After confirmation, rules can be persisted — similar operations auto-approved later
    
    // Third line: sandbox isolation
    // Untrusted code executes in Docker sandbox, host unaffected
    HarnessAgent agent = HarnessAgent.builder()
            .filesystem(new DockerFilesystemSpec()...)  // Sandbox filesystem
            .build();

Pain point 5: Evaluation difficulty — can't tell if Agent is working well

Symptom: Traditional software testing is "input → assert output," but Agent's multi-step reasoning + tool calls make output non-deterministic — same input may take different paths.

Avoidance:

Layered evaluation:

Golden set regression: maintain a set of "standard questions + standard answers," run after every model upgrade or prompt change.

Observability is a prerequisite: must be able to trace every step of Agent reasoning and tool calls. AgentScope's Studio visualization tool serves this.

    // Enable observability — essential for production
    ReActAgent agent = ReActAgent.builder()
            .name("observable_agent")
            .model("dashscope:qwen-max")
            .toolkit(toolkit)
            // Each step of reasoning, tool call, tool result flows out as events
            .build();
    
    // Use streamEvents instead of call to trace execution in real time
    agent.streamEvents(userMsg)
            .doOnNext(event -> {
                switch (event.getType()) {
                    case TEXT_BLOCK_DELTA -> System.out.print(((TextBlockDeltaEvent) event).getDelta());
                    case TOOL_CALL_START -> log.info("Tool call: {}", ((ToolCallStartEvent) event).getToolCallName());
                    case TOOL_CALL_END -> log.info("Tool complete: {}", ((ToolCallEndEvent) event).getToolCallName());
                }
            })
            .blockLast();

3.3 Industry Best Practices

Practice one: Progressive introduction — from HITL to full automation

Don't aim for a fully automated Agent from the start. Recommended staged path:

Practice two: Model routing — different tasks use different models

Not every step needs the strongest model. A common cost optimization strategy:

    // Main model strong, auxiliary operations small model
    HarnessAgent agent = HarnessAgent.builder()
            .model("dashscope:qwen-max")              // Main reasoning
            .memory(MemoryConfig.builder()
                    .model("dashscope:qwen-turbo")    // Memory operations
                    .build())
            .compaction(CompactionConfig.builder()
                    .model("dashscope:qwen-turbo")    // Compaction summary
                    .build())
            .build();
    // Overall cost down 40-60%, nearly no performance loss

Practice three: Skill sedimentation — make Agent stronger with use

Teams accumulate many effective work patterns while using Agents. Sediment these patterns into Skills so the Agent gets stronger:

Key principles:

Practice four: Production deployment checklist

Check item by item before launch:

四、Summary and Outlook

Panorama architecture diagram

Let's integrate all the concepts discussed today into one diagram:

One-sentence summary:

The four layers stacked on the foundation = a complete autonomous intelligent agent.

Current challenges

Agent technology is advancing fast, but real challenges remain:

These challenges also spawn many engineering practices: permission systems with three-state decisions (allow/ask/deny), HITL to pause sensitive operations for human confirmation, sandbox isolation for safe untrusted code execution.

Future directions

Looking ahead, several directions worth watching:

An inspiration

Finally, I'd like to leave you with a thought:

The essence of Agent technology is not making AI "smarter," but building "engineering infrastructure" for AI — turning it from "a flash of brilliance in Q&A" into a "reliably operating system." This mirrors the history of software engineering: from single scripts, to engineering, to platforms.

Agents are Software Engineering 3.0 — a new development paradigm.

What we are experiencing is the engineering turning point of AI from "models" to "systems." And every engineering problem in this turning point — reliability, observability, security, maintainability — is the domain we engineers are best at.

The future of Agents is not only the future of AI researchers; it is the future of every engineer.