asyncio

Python中处理并发有三种主要范式：多线程（threading）、多进程（multiprocessing）和异步IO（asyncio）

Agentica采用async-first（异步优先）架构，基于Python的asyncio生态构建

asyncio需要整个调用链都支持async/await，改造成本极高

对于等待子进程完成这类IO密集型任务，线程切换的开销远小于收益，多线程比asyncio更适合

Python's asyncio is a standard library introduced in Python 3.4.

Python的asyncio是基于单线程事件循环的协程并发模型，asyncio.gather并非真正的CPU并行，而是I/O并发

Batch ingestion uses asyncio.Semaphore(10) to limit concurrency, preventing the embedding service from being overwhelmed.

Python 3.11 introduced the tomllib module for TOML parsing and brought asyncio's TaskGroup and timeout() features as well as the datetime.UTC alias.

摄入管线通过计算文档内容的SHA256哈希（取前16位）作为chunk_hash来实现幂等性，批量摄入使用asyncio.Semaphore(10)控制并发。

Slow callback tracing (asyncio debug mode) gives the exact call stack of who is blocking, while the latency monitor gives production-grade metrics of how long the blocking lasts, and the two are complementary.

Calling the synchronous Anthropic() client inside async def causes the event loop to block, because the synchronous network call has no await yield point.

In a single-user scenario, the cost of blocking the event loop is zero, because a 2.3-second blocking call looks just like a 2.3-second LLM call.

Enabling asyncio debug mode and setting loop.slow_callback_duration = 0.1 can record every callback exceeding the threshold and its corresponding task, but debug mode has extra overhead and is not suitable for production environments.

The latency monitor detects event loop latency through a periodic asyncio.sleep task, has almost zero overhead, and can run in production environments for a long time.

async def only defines a coroutine factory; the synchronous code inside the function body still executes line by line, monopolizing the thread, and await itself cannot make blocking code asynchronous.

Task cancellation exceptions are particularly common in Python's asyncio ecosystem; if CancelledError is not handled correctly, it may lead to resource leaks or state inconsistencies.

This update changes asynchronous methods to internally use asyncio.get_running_loop().

Calling asyncio.get_running_loop() within a running coroutine is safer than get_event_loop() and is a best practice in Python asynchronous programming.

anyio is an asynchronous compatibility layer library that allows code to run seamlessly on both asyncio and Trio async runtimes.

In Jupyter Notebook or certain framework environments where the event loop is already running, directly calling asyncio.run() will raise a 'This event loop is already running' error; the common fix is to patch it using the nest_asyncio library (nest_asyncio.apply()).