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并发

Running AgentScope requires the use of asynchronous programming (async/await): conversation methods must be defined with async def, await is used where the model is called, and at startup an asynchronous entry point such as asyncio.run() must be used; it cannot be called directly in a synchronous manner.

In asyncio, the CancelledError injected by Task.cancel() still triggers finally, but if there is an await inside finally and the cancellation signal arrives again, the release logic may be interrupted.

To avoid concurrent graph-building races for the same repository, RepoBuddy maintains one `asyncio.Task` per repository protected with `asyncio.shield`, letting all callers share the same build result (request coalescing pattern).

In an asyncio environment, SQLAlchemy implicit lazy loading triggers the MissingGreenlet error, and it often blows up only when serializing the response.

Treating async as an infrastructure-layer concern and separating data fetching from business decisions (for example, decide_checkout receiving order and profile parameters rather than fetching them itself) decouples business logic from infrastructure, keeping it testable and reusable.

A function defined with async def returns a coroutine object that must be driven by an event loop to execute; the await keyword can only be used inside async functions, so once a layer is asynchronous, all synchronous functions that call it must be changed to async (the function coloring problem).

The streaming playback approach uses asyncio.create_subprocess_exec to start an ffmpeg process, with parameters specifying pipe:0 as input, s16le as the output format, a 48000Hz sample rate, and two channels, and loops reading 1024-byte chunks from the response stream and writing them to ffmpeg's stdin.

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)控制并发。

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.