DEV Community: Leo Han

From Overload Protection to Health Checks: Production-Grade Scheduling in Firefly

Leo Han — Thu, 30 Jul 2026 10:26:16 +0000

Summary: A reliable scheduler must do more than complete work successfully. It also needs explicit outcomes for overload, timeout, upgrade, and dependency failure. This article examines how Firefly implements bounded capacity, dispatch convergence, schema migration, secure startup, and dependency-aware health reporting.

Intended Reader

This article is for backend engineers who already understand the basic shape of a scheduler and now need to reason about its production behavior: overload, retry exhaustion, schema upgrades, security defaults, and readiness signals. It is especially relevant if you are building or operating Java services where scheduled work is executed remotely by application-side workers.

The article assumes familiarity with Java executors, Spring Boot Actuator, relational schema migration, and common reliability language such as timeout, ACK, idempotency, and SLO. It focuses on Firefly's production design boundaries rather than on a step-by-step quick start.

Why This Matters

A scheduler looks reliable under light load: the Scheduler creates work, a Gateway locates an Executor, a handler runs, and the result reaches the database. The difficult failures appear at the edges. A traffic spike can grow thread count without bound. An execution can remain DISPATCHING after every Executor disconnects. A schema upgrade can depend on an operator remembering an ad hoc statement. A Spring Boot process can report UP even though it cannot register with any Gateway.

Those failures are not primarily missing features. They are missing resource, time, and state boundaries. Firefly's production design follows four rules:

Perform capacity admission before accepting work.
Persist deadlines for dispatch and execution attempts.
Evolve database state through versioned SQL files.
Report dependency failures through health, not merely JVM liveness.

Figure 1: Firefly combines transactional execution records, a durable Outbox, Gateway routing, bounded Executor admission, and operational guardrails into an observable dispatch path with deterministic outcomes.

As a compact mental model, the implementation defines four kinds of production boundary: capacity answers whether the system can accept more work, time answers how long it may wait, state defines where an attempt must converge, and operations determines whether the service is actually usable.

Figure 2: The four boundaries are not independent toggles. Capacity rejection, deadlines, durable terminal states, and health reporting work together to turn failure into an observable and recoverable result. The editable source is assets/excalidraw/03-firefly-production-boundaries.excalidraw.

Mental Model

The core mental model is simple: a production scheduler should fail in states the system can record, monitor, and recover from. It should not convert every boundary into invisible waiting, unbounded resource growth, or ambiguous intermediate status.

In Firefly, capacity and time are first-class control surfaces. Executor admission decides whether a worker can accept more work before the business handler runs. The Outbox gives delivery a bounded recovery window. The execution deadline prevents DISPATCHING and RUNNING attempts from remaining alive forever. Schema migrations become an ordered version sequence instead of a one-off manual patch. Health reflects whether the application is connected and synchronized, not just whether its process exists.

This distinction matters because retry alone does not create reliability. Retrying without admission control can amplify overload. Retrying without deadlines can create immortal intermediate records. Running startup with insecure defaults can turn a configuration warning into an operational exposure. Reporting healthy while disconnected can make an orchestrator keep sending traffic to a service that is not ready.

Implementation Walkthrough

The previous executor client used newCachedThreadPool(). That avoids short-term queueing by converting pressure into threads. When handlers slow down or block on downstream services, thread growth transfers the cost to heap usage, context switching, and garbage collection.

Firefly exposes execution resources through NettyExecutorResourceOptions:

public record NettyExecutorResourceOptions(
        int workerThreads,
        int queueCapacity,
        int maxConcurrentExecutions
) {
    public static NettyExecutorResourceOptions defaults() {
        int workers = Math.max(2, Runtime.getRuntime().availableProcessors());
        return new NettyExecutorResourceOptions(workers, 1024, workers);
    }
}

A Firefly-owned pool has a fixed worker count, a bounded ArrayBlockingQueue, and a fail-fast AbortPolicy. NettyExecutorWorkScheduler adds two semaphore boundaries:

acceptedSlots = maxConcurrentExecutions + queueCapacity limits all work accepted by the client.
runningSlots = maxConcurrentExecutions limits concurrent business-handler calls.

The same admission layer wraps an externally supplied ExecutorService. Even if that pool has an unbounded queue, Firefly does not accept unbounded work.

When capacity is exhausted, the Executor neither drops work silently nor leaves the Gateway waiting for a network timeout. The protocol emits an explicit response:

ACK_JOB accepted=false reason=executor_overloaded
RESULT   status=FAILED errorMessage=executor_overloaded

Overload is therefore a scheduler-visible, durable, and observable result. The relevant Prometheus series are:

firefly_executor_overload_acks_total
firefly_executor_client_active_executions
firefly_executor_client_queued_executions
firefly_executor_client_max_concurrent_executions
firefly_executor_client_queue_capacity

Pool ownership is explicit as well. Firefly shuts down pools it creates. It never shuts down a pool supplied by the application, which remains responsible for that pool's lifecycle.

The second boundary is dispatch convergence. Immediately failing a task when no Executor is online is not always correct: the connection may be temporarily absent during a rolling deployment, and a durable Outbox exists precisely to allow recovery within a bounded window. Firefly keeps DISPATCHING as a transitional state but gives it deterministic exit conditions.

When a remote attempt is created, its execution enters DISPATCHING and persists timeout_at from the job timeout. The default job timeout is five minutes and can be changed per job. Outbox delivery operates on a shorter cycle:

firefly.dispatch.outbox.remote-ack-timeout=PT10S
firefly.dispatch.outbox.max-attempts=5
firefly.dispatch.outbox.max-retry-backoff=PT30S
firefly.execution.maintenance.interval=PT5S

These are two distinct time boundaries:

The ACK deadline determines whether one remote send was accepted by an Executor.
The execution deadline determines whether the entire attempt exceeded its allowed runtime.

Figure 3: the short ACK deadline bounds each delivery attempt, while the persisted execution deadline bounds the complete task attempt. Overload, retry exhaustion, and timeout all converge to explicit terminal states.

The state diagram is useful for checking every branch. The two-clock view below isolates the operational distinction that is easiest to miss: a failed delivery advances the retry budget, while only the job-level execution deadline bounds the lifetime of the complete attempt.

Figure 4: The ACK deadline bounds each send -> wait ACK cycle; the execution timeout bounds the complete task attempt. They require separate configuration, monitoring, and interpretation. The editable source is assets/excalidraw/04-firefly-two-clocks.excalidraw.

A Gateway send rejection or an ACK timeout consumes a real delivery attempt. After max-attempts, the Outbox record becomes DEAD and is no longer sent automatically. Upgrade compatibility also reconstructs missing historical deadlines from dispatch_time + timeout_value, preventing old executions from remaining active forever.

The third boundary is schema evolution. Schema 12 adds password_change_required, but the more important change is the migration mechanism. Each dialect now owns an incremental file:

stores/jdbc/src/main/resources/com/firefly/store/jdbc/schema/migrations/
├── h2/v12.sql
├── mysql/v12.sql
└── postgresql/v12.sql

Startup reads firefly_schema_version and loads every missing version in order:

for (int version = Math.max(installed + 1, FIRST_VERSIONED_SQL_MIGRATION);
     version <= CURRENT_VERSION;
     version++) {
    for (String sql : JdbcSchemaScript.loadMigration(dialect, version)) {
        statement.execute(sql);
    }
}

The same design naturally extends from 11 -> 12 to 12 -> 13 -> 14, and tests can require every incremental resource to exist. Fresh PostgreSQL installations use scripts/postgresql/init.sql, which creates only Firefly-owned objects. Database creation, roles, and grants remain operator-owned.

The v12 migration requires a password change only when the administrator still has the known bootstrap password digest. It does not overwrite an already changed password. This is an essential migration property: strengthen unsafe defaults without destroying state the operator already owns.

The fourth boundary is security and health. Documentation that says "change this before production" is not a control. In Firefly, cluster mode or an Admin HTTP endpoint bound outside the local host checks for bundled development credentials and refuses to start when they remain. The bootstrap admin/admin account must also complete its first-login password change before management APIs become available.

The Spring Boot Starter adds an Actuator HealthIndicator that checks more than bean construction:

The number of registered Gateway connections.
Executor registration failures caused by authentication or server policy.
Declarative job synchronization status and synchronized or failed job counts.

With autoStart=true, zero registered Gateway connections produces DOWN. A failed job-registration state does the same. This can change restart and traffic-routing behavior in an orchestrator, so liveness and readiness should be configured separately instead of using aggregate /actuator/health as an unconditional process-liveness probe.

Figure 5: Startup blocks development credentials from non-local deployments. During operation, Gateway connectivity and job synchronization determine readiness, while liveness remains a narrower JVM-process signal. The editable source is assets/excalidraw/05-firefly-startup-readiness.excalidraw.

Pitfalls and Tradeoffs

A bounded system exposes insufficient capacity earlier. executor_overloaded is not framework instability; it is deterministic process protection. A larger queue does not create throughput. It increases waiting time and memory use. Capacity should be based on handler service time, latency budgets, and instance count, with alerts on active, queued, and overload metrics.

Reliable dispatch does not mean unlimited retries. Business handlers still need an idempotency boundary. Job timeout, ACK timeout, and delivery attempts should reflect the side effects of the workload. If a handler performs external writes, retry and timeout settings need to be designed together with deduplication or idempotency keys.

Health checks are also operational interfaces. If aggregate health is used as a liveness probe, a real dependency failure may cause unnecessary restarts. For Kubernetes or a similar orchestrator, liveness should answer "is the process alive enough to restart only when stuck?", while readiness should answer "should this instance receive traffic or scheduled work now?"

The release also closes several gaps that workstation builds tend to hide:

Gradle resolves from Maven Central by default; local repositories and mirrors require explicit opt-in.
Isolated Maven consumers test Spring Boot 3.3, 3.4, 3.5, and 4.0.
PostgreSQL and MySQL containers cover initialization, concurrency, and fault injection.
Playwright exercises the primary Admin UI workflows.
Public artifacts no longer leak slf4j-nop, and netty-all is replaced with the modules actually used.

The process-fault benchmark foundation makes targets such as scheduler-delay p99 below 500 ms and failover below 15 seconds executable. Precision matters here: these are SLO definitions and test infrastructure, not claimed production benchmark results. Database restarts, network partitions, and large same-second workloads still require ongoing scenario implementation and measurement.

Verification Checklist

Evaluate concurrency per handler class instead of assuming CPU count is always optimal.
Alert on queued executions, overload ACKs, oldest Outbox age, and DEAD records.
Distinguish the 10-second ACK deadline from the job-level execution timeout.
Back up existing databases and verify firefly_schema_version contains 12 after upgrade.
Generate a unique JWT secret for non-local deployment and change the bootstrap administrator password immediately.
Configure separate liveness and readiness probes in Kubernetes or an equivalent orchestrator.
Treat SLO targets as testable objectives unless you have measured results from the target deployment environment.

Scheduler reliability is not making every operation "try harder." It is knowing how much work the system can still accept, how long it may wait, who owns state, and what evidence remains after failure. Firefly turns those boundaries into explicit engineering capabilities: overload can be rejected, dispatch can expire, schemas can advance one version at a time, and connectivity or synchronization failures can affect health.

The changes do not eliminate failure. They turn unbounded resource use and ambiguous intermediate states into deterministic behavior that operators can monitor, test, and recover.

Firefly: A Lightweight Distributed Scheduler for Java Business Systems

Leo Han — Thu, 30 Jul 2026 10:25:50 +0000

Summary: The article explains why business systems need scheduling as a governed runtime capability instead of scattered cron jobs.

Intended Reader

Java engineers designing internal scheduling infrastructure.

Why This Matters

Scheduling systems turn time-based business intent into reliable execution. Real systems need visibility, retry behavior, ownership, and cross-time-zone correctness.

A scheduler should make task ownership, executor registration, dispatch, retry behavior, timeout rules, and execution history explicit.

Mental Model

A scheduler should make task definitions, executor registration, dispatch, persistence, failure handling, and observability explicit.

The practical way to read this article is to look for the boundary it clarifies: what state exists, who owns it, which operation changes it, and what evidence proves the system behaved as expected.

Implementation Walkthrough

Start from the business problem: scattered cron jobs are hard to observe, retry, and govern.
Define task metadata separately from runtime execution so schedules can be managed centrally.
Use Spring Boot annotations to reduce integration cost while still registering tasks explicitly.
Track executor heartbeat and execution history so operators can debug missed or failed runs.

Pitfalls and Tradeoffs

A lightweight scheduler should avoid overbuilding features before execution semantics are clear.
Distributed dispatch requires idempotency and executor state awareness.
Annotation convenience should not hide operational behavior.

Verification Checklist

Test missed runs, retries, timeouts, duplicate dispatch, and executor restarts.
Verify task history and failure reasons in the management view.
Document timezone and schedule interpretation rules.

Practical Takeaways

Cron syntax is only the beginning; execution ownership and failure semantics are the hard parts.
Distributed schedulers need fencing, idempotency, and clear executor state.
Time zone handling should be a task-level decision, not an accidental machine default.
Operational visibility is part of the product, not an afterthought.

Visual Evidence

The migrated local images are preserved as supporting figures. They keep the English edition aligned with the same diagrams, screenshots, or console evidence used by the source article.

Selected Technical Snippets

The following snippets are preserved only when they are safe to publish in English without broken encoding or translated identifiers.

<dependency>
<groupId>com.firefly</groupId>
<artifactId>firefly-spring-boot-starter</artifactId>
<version>1.0.0</version>
</dependency>

repositories {
mavenLocal()
mavenCentral()
}

dependencies {
implementation "com.firefly:firefly-spring-boot-starter:1.0.0"
}

spring:
application:
name: firefly-example
firefly:
executor:
name: billing-executor
gateway-addresses:
- 127.0.0.1:9700
integration-key: ${FIREFLY_INTEGRATION_KEY}
server:
port: 80

Source Notes

Topic: Scheduling
Original source
Original publication date: 2026-07-24
This English edition is localized from the migrated article metadata, source structure, technical terms, local assets, and clean implementation evidence.

Closing Thoughts

The goal of this English edition is not to imitate the original wording sentence by sentence. It preserves the engineering argument, removes migration noise, and presents the article as a publishable technical note that future readers can use for design, debugging, or implementation review.

LangChain Agents, Tools, and Memory

Leo Han — Thu, 30 Jul 2026 10:25:41 +0000

Summary: The article frames an Agent as model plus harness: the model decides, but tools, memory, and execution boundaries determine whether the system is reliable.

Intended Reader

Engineers building tool-using LLM systems for internal or enterprise workflows.

Why This Matters

Agent-oriented AI systems are not only about calling a model. They also involve context management, tool boundaries, retrieval quality, memory, execution control, and failure recovery.

Agents become production-ready only when tools are narrow, memory is intentional, and every action can be inspected.

Mental Model

Treat the model as one component in an execution system. The valuable engineering work is deciding what the model may do, what evidence it can use, how state is carried forward, and how the workflow can be inspected or rolled back.

The practical way to read this article is to look for the boundary it clarifies: what state exists, who owns it, which operation changes it, and what evidence proves the system behaved as expected.

Implementation Walkthrough

Position the Agent as a coordination layer around the model rather than the whole system.
Design tools with small responsibilities, clear parameters, and predictable error behavior.
Use memory for durable task context, not for dumping every conversation token.
Separate business actions from model reasoning so dangerous operations can be reviewed.

Pitfalls and Tradeoffs

A broader tool surface increases capability and risk at the same time.
Memory improves continuity but raises privacy, correctness, and stale-state concerns.
Enterprise agents need auditability more than clever prompt tricks.

Verification Checklist

Review tool schemas and sample tool calls.
Record agent traces with inputs, decisions, tool arguments, and outputs.
Test permission failures, invalid arguments, and partial business success.

Practical Takeaways

Separate model reasoning, tool execution, retrieval, memory, and orchestration instead of mixing everything into a single prompt.
Use RAG or memory only when it improves the task boundary; more context is not automatically better context.
Prefer explicit workflows for production agents, especially when tools mutate state or depend on external systems.
Evaluate the system by observing failures: hallucinated tool calls, stale context, ambiguous state, and missing fallback paths.

Selected Technical Snippets

The following snippets are preserved only when they are safe to publish in English without broken encoding or translated identifiers.

get_order_status(order_id)
get_customer_profile(customer_id)
create_refund_request(order_id, reason)
search_policy_document(query)

handle_customer_issue(anything)

{
"status": "success",
"order_id": "O123",
"payment_status": "paid",
"shipment_status": "in_transit"
}

Source Notes

Topic: AI & Agent
Original source
Original publication date: 2026-06-15
This English edition is localized from the migrated article metadata, source structure, technical terms, local assets, and clean implementation evidence.

Closing Thoughts

LangGraph: Moving Agents from Answering to Controlled Execution

Leo Han — Thu, 30 Jul 2026 10:24:22 +0000

Summary: The article explains why enterprise agents need explicit state, nodes, edges, and checkpoints rather than a single opaque model call.

Intended Reader

Engineers designing multi-step AI workflows that must be controlled and debugged.

Why This Matters

Agent-oriented AI systems are not only about calling a model. They also involve context management, tool boundaries, retrieval quality, memory, execution control, and failure recovery.

LangGraph is valuable because it turns agent execution into a graph with explicit state and transitions. That makes retries, branching, checkpoints, and human review easier to reason about.

Mental Model

The practical way to read this article is to look for the boundary it clarifies: what state exists, who owns it, which operation changes it, and what evidence proves the system behaved as expected.

Implementation Walkthrough

Start with the problem: a single model call cannot safely represent a long-running workflow.
Model State as the shared business context that moves through the graph.
Model Nodes as executable steps and Edges as the control rules between them.
Use checkpoints and interrupts when the workflow must be resumed or reviewed.

Pitfalls and Tradeoffs

Graphs add structure and control, but they require more upfront modeling.
Explicit state improves debugging while forcing the team to define what state really matters.
A graph should simplify operational behavior, not become a decorative diagram.

Verification Checklist

Trace state changes across nodes.
Test retry, resume, and human-in-the-loop paths.
Inspect branch conditions with real failure cases.

Practical Takeaways

Separate model reasoning, tool execution, retrieval, memory, and orchestration instead of mixing everything into a single prompt.
Use RAG or memory only when it improves the task boundary; more context is not automatically better context.
Prefer explicit workflows for production agents, especially when tools mutate state or depend on external systems.
Evaluate the system by observing failures: hallucinated tool calls, stale context, ambiguous state, and missing fallback paths.

Selected Technical Snippets

The following snippets are preserved only when they are safe to publish in English without broken encoding or translated identifiers.

Start -> Step 1 -> Step 2 -> Step 3 -> End

Start
-> Agent Node
-> Tool Node
-> Agent Node
-> Human Review Node
-> End

Agent Node
-> if need_tool: Tool Node
-> if need_human: Human Review Node
-> if ready: Final Answer Node

Source Notes

Topic: AI & Agent
Original source
Original publication date: 2026-06-15
This English edition is localized from the migrated article metadata, source structure, technical terms, local assets, and clean implementation evidence.

Closing Thoughts

A Complete Guide to LangChain Core Components

Leo Han — Thu, 30 Jul 2026 10:23:58 +0000

Summary: This article turns LangChain from a list of APIs into a system map: components are useful only when their boundaries and data flow are understood.

Intended Reader

Developers building LLM applications and trying to understand the LangChain ecosystem.

Why This Matters

Agent-oriented AI systems are not only about calling a model. They also involve context management, tool boundaries, retrieval quality, memory, execution control, and failure recovery.

LangChain should be learned as a set of composable boundaries: model IO, prompt construction, parsing, memory, retrieval, tools, and agent orchestration.

Mental Model

The practical way to read this article is to look for the boundary it clarifies: what state exists, who owns it, which operation changes it, and what evidence proves the system behaved as expected.

Implementation Walkthrough

Start with the model call and prompt template because every higher-level abstraction eventually depends on them.
Introduce output parsing so model responses can become structured data instead of free text.
Use chains to express repeatable workflows, not to hide logic that should be visible.
Add memory, tools, and retrieval only when the task requires external context or action.

Pitfalls and Tradeoffs

High-level abstractions speed up demos but can obscure execution order.
Memory improves continuity but can introduce stale or irrelevant context.
Agent flexibility is valuable only when tool boundaries and traces remain inspectable.

Verification Checklist

Log prompt inputs, model outputs, parser results, and tool calls.
Test each component independently before composing them.
Use real task examples instead of only hello-world prompts.

Practical Takeaways

Separate model reasoning, tool execution, retrieval, memory, and orchestration instead of mixing everything into a single prompt.
Use RAG or memory only when it improves the task boundary; more context is not automatically better context.
Prefer explicit workflows for production agents, especially when tools mutate state or depend on external systems.
Evaluate the system by observing failures: hallucinated tool calls, stale context, ambiguous state, and missing fallback paths.

Visual Evidence

The migrated local images are preserved as supporting figures. They keep the English edition aligned with the same diagrams, screenshots, or console evidence used by the source article.

Selected Technical Snippets

The following snippets are preserved only when they are safe to publish in English without broken encoding or translated identifiers.

User Input → [Prompt Template] → [LLM Call] → [Output Parser] → Result
↑                ↑
[Memory]        [Tools / APIs]

pip install langchain langchain-openai langchain-community python-dotenv

DEEPSEEK_API_KEY=sk-your-key-here
OPENAI_API_KEY=sk-your-backup-key-here

Source Notes

Topic: AI & Agent
Original source
Original publication date: 2026-06-12
This English edition is localized from the migrated article metadata, source structure, technical terms, local assets, and clean implementation evidence.

Closing Thoughts

LangChain Core Components: From Basics to Application Structure

Leo Han — Thu, 30 Jul 2026 10:23:43 +0000

Summary: The article explains how LangChain components fit together and where engineers should draw boundaries when an LLM demo becomes an application.

Intended Reader

Engineers who want a practical overview before committing to a LangChain architecture.

Why This Matters

Agent-oriented AI systems are not only about calling a model. They also involve context management, tool boundaries, retrieval quality, memory, execution control, and failure recovery.

The value of LangChain is composition. The risk is losing sight of what data enters and leaves each component.

Mental Model

The practical way to read this article is to look for the boundary it clarifies: what state exists, who owns it, which operation changes it, and what evidence proves the system behaved as expected.

Implementation Walkthrough

Build from model access and prompt templates toward chains and parsing.
Introduce memory only after the workflow has a clear state requirement.
Use tools to cross the boundary from language generation into external action.
Keep retrieval and agent logic observable because they are the most common failure points.

Pitfalls and Tradeoffs

The framework can reduce repetitive glue code while increasing debugging distance.
Generic abstractions are helpful for learning but may need to be narrowed in production.
A component diagram is often more useful than a long chain of helper calls.

Verification Checklist

Document each component boundary.
Capture traces for full requests.
Replace weak abstractions with explicit code when ownership becomes unclear.

Practical Takeaways

Separate model reasoning, tool execution, retrieval, memory, and orchestration instead of mixing everything into a single prompt.
Use RAG or memory only when it improves the task boundary; more context is not automatically better context.
Prefer explicit workflows for production agents, especially when tools mutate state or depend on external systems.
Evaluate the system by observing failures: hallucinated tool calls, stale context, ambiguous state, and missing fallback paths.

Visual Evidence

The migrated local images are preserved as supporting figures. They keep the English edition aligned with the same diagrams, screenshots, or console evidence used by the source article.

Selected Technical Snippets

The following snippets are preserved only when they are safe to publish in English without broken encoding or translated identifiers.

User Input → [Prompt Template] → [LLM Call] → [Output Parser] → Result
↑                ↑
[Memory]        [Tools / APIs]

pip install langchain langchain-openai langchain-community python-dotenv

DEEPSEEK_API_KEY=sk-your-key-here
OPENAI_API_KEY=sk-your-backup-key-here

Source Notes

Topic: AI & Agent
Original source
Original publication date: 2026-06-12
This English edition is localized from the migrated article metadata, source structure, technical terms, local assets, and clean implementation evidence.

Closing Thoughts

Agent Concepts, Principles, and Construction Patterns

Leo Han — Thu, 30 Jul 2026 10:23:01 +0000

Summary: The article presents agents as execution systems: they reason, act through tools, observe results, and continue until the task reaches a usable state.

Intended Reader

Developers moving from basic LLM calls to agent-style applications.

Why This Matters

Agent-oriented AI systems are not only about calling a model. They also involve context management, tool boundaries, retrieval quality, memory, execution control, and failure recovery.

An Agent is useful when the task needs iterative reasoning and external action. The engineering challenge is to keep the loop bounded, observable, and recoverable.

Mental Model

The practical way to read this article is to look for the boundary it clarifies: what state exists, who owns it, which operation changes it, and what evidence proves the system behaved as expected.

Implementation Walkthrough

Define the agent loop: reason, choose an action, call a tool, observe the result, and update state.
Use examples such as question answering or planning to show why a single model call is not always enough.
Treat tools as controlled interfaces with explicit inputs, outputs, and error behavior.
Keep memory and state small enough to inspect and stable enough to continue a task.

Pitfalls and Tradeoffs

More autonomy increases flexibility but also increases failure surface.
A powerful tool set can make agents useful, but each tool adds security and correctness risk.
Natural language plans are easy to produce but hard to verify without structured state.

Verification Checklist

Log the model decision, selected tool, tool arguments, and result.
Replay failed tasks from stored state.
Add stop conditions and human handoff for uncertain or destructive actions.

Practical Takeaways

Separate model reasoning, tool execution, retrieval, memory, and orchestration instead of mixing everything into a single prompt.
Use RAG or memory only when it improves the task boundary; more context is not automatically better context.
Prefer explicit workflows for production agents, especially when tools mutate state or depend on external systems.
Evaluate the system by observing failures: hallucinated tool calls, stale context, ambiguous state, and missing fallback paths.

Selected Technical Snippets

The following snippets are preserved only when they are safe to publish in English without broken encoding or translated identifiers.

<action>write_to_file("test.txt", "a\nb\nc")</action>

Source Notes

Topic: AI & Agent
Original source
Original publication date: 2026-06-09
This English edition is localized from the migrated article metadata, source structure, technical terms, local assets, and clean implementation evidence.

Closing Thoughts

A Practical Guide to Building an AI Agent

Leo Han — Thu, 30 Jul 2026 10:22:54 +0000

Summary: The article argues for disciplined agent design: choose agents only when the problem needs them, then make planning, execution, memory, and sub-agents explicit.

Intended Reader

Engineers designing AI-assisted workflows or internal agent tools.

Why This Matters

Agent-oriented AI systems are not only about calling a model. They also involve context management, tool boundaries, retrieval quality, memory, execution control, and failure recovery.

An agent should be introduced because the task requires iterative execution, not because the word is fashionable. The design must clarify planning, execution, memory, and delegation boundaries.

Mental Model

The practical way to read this article is to look for the boundary it clarifies: what state exists, who owns it, which operation changes it, and what evidence proves the system behaved as expected.

Implementation Walkthrough

Start from the task boundary and decide whether a workflow, a chain, or an agent is actually needed.
Separate planning from execution so intermediate steps can be inspected.
Use memory only for information that improves future decisions.
Introduce sub-agents when responsibilities are truly separate, not as decoration.

Pitfalls and Tradeoffs

Agent frameworks can help prototypes, but unclear boundaries become production bugs.
Memory can improve continuity, but stale memory can poison future decisions.
Sub-agents can reduce complexity per role while increasing orchestration complexity.

Verification Checklist

Define success criteria before building the agent loop.
Test tool failures, malformed outputs, timeouts, and retries.
Review traces to confirm the agent is solving the task, not just producing fluent steps.

Practical Takeaways

Separate model reasoning, tool execution, retrieval, memory, and orchestration instead of mixing everything into a single prompt.
Use RAG or memory only when it improves the task boundary; more context is not automatically better context.
Prefer explicit workflows for production agents, especially when tools mutate state or depend on external systems.
Evaluate the system by observing failures: hallucinated tool calls, stale context, ambiguous state, and missing fallback paths.

Source Notes

Topic: AI & Agent
Original source
Original publication date: 2026-06-09
This English edition is localized from the migrated article metadata, source structure, technical terms, local assets, and clean implementation evidence.

Closing Thoughts

How RAG Works: A Detailed Walkthrough

Leo Han — Thu, 30 Jul 2026 10:18:49 +0000

Summary: RAG is explained as a retrieval pipeline rather than a magic prompt trick. Each stage can improve or damage answer quality.

Intended Reader

Engineers implementing knowledge-base question answering or enterprise AI search.

Why This Matters

Agent-oriented AI systems are not only about calling a model. They also involve context management, tool boundaries, retrieval quality, memory, execution control, and failure recovery.

The quality of a RAG system depends on the full pipeline: source documents, chunking, embeddings, index design, retrieval, ranking, prompt assembly, and evaluation.

Mental Model

The practical way to read this article is to look for the boundary it clarifies: what state exists, who owns it, which operation changes it, and what evidence proves the system behaved as expected.

Implementation Walkthrough

Start offline with document parsing, cleanup, chunking, embedding, and index storage.
At query time, convert the user question into a retrieval task and select candidate chunks.
Use ranking or reranking to reduce irrelevant context before the model sees it.
Assemble context with citations or source anchors so the answer can be inspected.

Pitfalls and Tradeoffs

Small chunks improve precision but can lose context; large chunks preserve context but add noise.
Embedding search is not the same as factual verification.
Adding more retrieved text can make answers worse if ranking is weak.

Verification Checklist

Create a test set of real questions and expected evidence.
Measure retrieval hit rate separately from answer quality.
Inspect failed answers to decide whether the problem is parsing, chunking, ranking, or generation.

Practical Takeaways

Separate model reasoning, tool execution, retrieval, memory, and orchestration instead of mixing everything into a single prompt.
Use RAG or memory only when it improves the task boundary; more context is not automatically better context.
Prefer explicit workflows for production agents, especially when tools mutate state or depend on external systems.
Evaluate the system by observing failures: hallucinated tool calls, stale context, ambiguous state, and missing fallback paths.

Source Notes

Topic: AI & Agent
Original source
Original publication date: 2026-06-09
This English edition is localized from the migrated article metadata, source structure, technical terms, local assets, and clean implementation evidence.

Closing Thoughts

Why Consider Moving Away from LangChain

Leo Han — Thu, 30 Jul 2026 10:18:44 +0000

Summary: The article explains why a framework that accelerates early experiments can become a liability when production systems need clarity, traceability, and control.

Intended Reader

Engineers evaluating whether LangChain is still the right abstraction for a production AI system.

Why This Matters

Agent-oriented AI systems are not only about calling a model. They also involve context management, tool boundaries, retrieval quality, memory, execution control, and failure recovery.

LangChain is useful when it matches the problem boundary. It becomes costly when abstractions hide control flow, make simple tasks complex, or obscure failure diagnosis.

Mental Model

The practical way to read this article is to look for the boundary it clarifies: what state exists, who owns it, which operation changes it, and what evidence proves the system behaved as expected.

Implementation Walkthrough

Identify which part of the system LangChain is actually simplifying.
Compare framework convenience with the cost of debugging hidden state and implicit chains.
Keep tool calls, memory, prompts, and model IO visible even when using framework helpers.
Be willing to replace a framework abstraction with a small explicit workflow when production control matters.

Pitfalls and Tradeoffs

Frameworks reduce boilerplate but can add conceptual overhead.
A simple HTTP or model call may be easier to own than a generic chain abstraction.
Leaving a framework too early can waste useful ecosystem integrations; leaving too late can trap the architecture.

Verification Checklist

Trace a full request from input to model call to tool result to final output.
Estimate how hard it is to debug a failed run.
Keep migration paths open by isolating framework-specific code.

Practical Takeaways

Separate model reasoning, tool execution, retrieval, memory, and orchestration instead of mixing everything into a single prompt.
Use RAG or memory only when it improves the task boundary; more context is not automatically better context.
Prefer explicit workflows for production agents, especially when tools mutate state or depend on external systems.
Evaluate the system by observing failures: hallucinated tool calls, stale context, ambiguous state, and missing fallback paths.

Selected Technical Snippets

The following snippets are preserved only when they are safe to publish in English without broken encoding or translated identifiers.

import os
from openai import OpenAI

os.environ["OPENAI_API_KEY"] = "<your_api_key>"

client = OpenAI()
text = "hello!"
language = "Italian"

messages = [
{"role": "system", "content": "You are an expert translator"},
{"role": "user", "content": f"Translate the following from English into {language}"},
{"role": "user", "content": f"{text}"},
]

response = client.chat.completions.create(model="gpt-4o", messages=messages)

from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser

model = ChatOpenAI(model="gpt-4o-turbo", temperature=0)
prompt = ChatPromptTemplate.from_messages([
("system", "You are an expert translator"),
("user", "Translate the following from English into {language}"),
("user", "{text}")
])

parser = StrOutputParser()
chain = prompt | model | parser
result = chain.invoke({"language": language, "text": text})

import http.client, json

conn = http.client.HTTPSConnection("api.example.com")
conn.request("GET", "/data")
response = conn.getresponse()
data = json.loads(response.read().decode())
conn.close()

Source Notes

Topic: AI & Agent
Original source
Original publication date: 2026-06-09
This English edition is localized from the migrated article metadata, source structure, technical terms, local assets, and clean implementation evidence.

Closing Thoughts

How AI Models Work

Leo Han — Thu, 30 Jul 2026 10:15:46 +0000

Summary: This article explains AI models from an engineering perspective: data, training, pattern learning, inference, and the limitations that appear when real input is messy.

Intended Reader

Developers who want a technical but approachable mental model for AI systems.

Why This Matters

Agent-oriented AI systems are not only about calling a model. They also involve context management, tool boundaries, retrieval quality, memory, execution control, and failure recovery.

An AI model is not a magic knowledge store. It is a learned statistical system shaped by data quality, training objectives, architecture choices, and the inference context provided at runtime.

Mental Model

The practical way to read this article is to look for the boundary it clarifies: what state exists, who owns it, which operation changes it, and what evidence proves the system behaved as expected.

Implementation Walkthrough

Start with machine learning as pattern learning from data rather than hand-coded rules.
Connect datasets to model behavior: messy data leads to messy boundaries.
Explain LLMs as systems that predict and compose language based on learned representations.
Distinguish model capability from product reliability; reliable systems still need retrieval, tools, evaluation, and guardrails.

Pitfalls and Tradeoffs

A larger model may improve general reasoning but still fail on fresh or domain-specific facts.
Fine-tuning changes behavior but does not remove the need for evaluation.
RAG can provide external evidence, but retrieval quality becomes a new failure point.

Verification Checklist

Test with examples from the actual domain, not only clean demos.
Check failure cases and ambiguous prompts.
Measure whether added context improves accuracy or merely increases confidence.

Practical Takeaways

Separate model reasoning, tool execution, retrieval, memory, and orchestration instead of mixing everything into a single prompt.
Use RAG or memory only when it improves the task boundary; more context is not automatically better context.
Prefer explicit workflows for production agents, especially when tools mutate state or depend on external systems.
Evaluate the system by observing failures: hallucinated tool calls, stale context, ambiguous state, and missing fallback paths.

Visual Evidence

The migrated local images are preserved as supporting figures. They keep the English edition aligned with the same diagrams, screenshots, or console evidence used by the source article.

Source Notes

Topic: AI & Agent
Original source
Original publication date: 2026-05-26
This English edition is localized from the migrated article metadata, source structure, technical terms, local assets, and clean implementation evidence.

Closing Thoughts

When AI Damages an Engineering Team

Leo Han — Thu, 30 Jul 2026 10:15:40 +0000

Summary: The article is not anti-AI. It argues that AI becomes dangerous when teams use it to skip understanding, architecture judgment, and code ownership.

Intended Reader

Engineers and team leads adopting AI tools in daily development.

Why This Matters

Agent-oriented AI systems are not only about calling a model. They also involve context management, tool boundaries, retrieval quality, memory, execution control, and failure recovery.

AI should increase engineering leverage, not remove engineering responsibility. The failure mode is a team that ships plausible output without understanding the design or owning the consequences.

Mental Model

The practical way to read this article is to look for the boundary it clarifies: what state exists, who owns it, which operation changes it, and what evidence proves the system behaved as expected.

Implementation Walkthrough

Separate useful AI assistance from outsourcing judgment.
Watch for review decay: code appears faster, but fewer people understand why it works.
Make AI-generated changes pass the same design, testing, and observability standards as human-written code.
Treat prompts, assumptions, and generated diffs as artifacts that need review.

Pitfalls and Tradeoffs

AI can accelerate exploration, but it can also normalize shallow implementation.
Junior engineers may learn faster with AI, or slower if they never debug the underlying model.
Team productivity metrics can look better while long-term maintainability gets worse.

Verification Checklist

Ask whether the author can explain the design without the model.
Require tests and operational reasoning for AI-assisted changes.
Track rework and incident patterns, not only code throughput.

Practical Takeaways

Separate model reasoning, tool execution, retrieval, memory, and orchestration instead of mixing everything into a single prompt.
Use RAG or memory only when it improves the task boundary; more context is not automatically better context.
Prefer explicit workflows for production agents, especially when tools mutate state or depend on external systems.
Evaluate the system by observing failures: hallucinated tool calls, stale context, ambiguous state, and missing fallback paths.

Source Notes

Topic: AI & Agent
Original source
Original publication date: 2026-01-18
This English edition is localized from the migrated article metadata, source structure, technical terms, local assets, and clean implementation evidence.