Run agent tools concurrently and fix tool message pairing (#99)

* feat(agent): implement concurrent tool call execution, fix: tool call context

* docs: update API usage note, clarify PROCESS_MESSAGE tool, add new metadata types, and fix parameter names in agent strategy examples

* resolve: issues

Author: JohnRichard4096

docs/docs/guide/api-reference/index.md

@@ -59,7 +59,7 @@ set_config(config)
 
 **Usage Notes**:
 
-- Must be called after `init()` but before `load_amrita()`
+- Should be called before `load_amrita()`
 - Configuration affects all subsequent operations
 
 ### 7.1.4 get_config() - Getting Configuration

docs/docs/guide/builtins.md

@@ -38,22 +38,25 @@ Built-in tools are automatically enabled based on the agent configuration:
 
 - **Agent Mode**: When `config.builtin.tool_calling_mode == "agent"`, both `STOP_TOOL` and `REASONING_TOOL` are available.
 - **Thought Mode**: The `REASONING_TOOL` is only available when `config.builtin.agent_thought_mode` starts with "reasoning".
-- **Process Messages**: The `PROCESS_MESSAGE` tool is enabled when `config.function_config.agent_middle_message` is True.
+- **Process Messages**: The `PROCESS_MESSAGE` tool is used internally by the `HybridReActAgentStrategy` to communicate intermediate tool results to the user. It is **not** registered by `ReActAgentStrategy`; the `config.function_config.agent_middle_message` flag controls whether the agent may send intermediate notifications, but does not independently enable the `PROCESS_MESSAGE` tool.
 
 ## 9.2 Built-in Metadata Types
 
 > **Since v0.9.1**: A new `amrita_core.builtins.types` module provides typed metadata classes (based on `MessageMetadataPayload`) for structured metadata in agent and hook workflows.
 
 These typed metadata classes replace plain dictionaries, providing type safety and IDE autocompletion:
 
-| Class                         | Purpose                                                                |
-| ----------------------------- | ---------------------------------------------------------------------- |
-| `AgentReasoningMetadata`      | Pre-resolve reasoning summaries (`last_step`, `summary`)               |
-| `AgentReasoningChunkMetadata` | Streaming reasoning chunks (`content`)                                 |
-| `AgentToolCallMetadata`       | Tool call notifications (`function_name`, `is_done`, `tool_id`, `err`) |
-| `AgentLoopErrorMetadata`      | Loop detection errors (`chat_object_id`, `error`)                      |
-| `AgentMiddleMessageMetadata`  | LLM middle messages (`content`)                                        |
-| `HookErrorMetadata`           | Hook-level error responses (`content`)                                 |
+| Class                                   | Purpose                                                                           |
+| --------------------------------------- | --------------------------------------------------------------------------------- |
+| `AgentReasoningMetadata`                | Pre-resolve reasoning summaries (`last_step`, `summary`)                          |
+| `AgentReasoningChunkMetadata`           | Streaming reasoning chunks (`content`)                                            |
+| `AgentToolCallMetadata`                 | Tool call notifications (`function_name`, `is_done`, `tool_id`, `err`)            |
+| `AgentLoopErrorMetadata`                | Loop detection errors (`chat_object_id`, `error`)                                 |
+| `AgentMiddleMessageMetadata`            | LLM middle messages (`content`)                                                   |
+| `HookErrorMetadata`                     | Hook-level error responses (`content`)                                            |
+| `AgentStructuredReasoningChunkMetadata` | Per-step structured CoT reasoning metadata (`step_index`, `total_steps`, `phase`) |
+| `AgentReflectionMetadata`               | Post-reasoning self-reflection results (`reflection_type`, `result`, `detail`)    |
+| `AgentToolPredictionMetadata`           | Tool prediction during structured reasoning (`predicted_tools`)                   |
 
 Base classes in `amrita_core.contents`:
 

docs/docs/guide/concepts/agent-strategy.md

@@ -197,22 +197,22 @@ async def use_builtin_strategies():
 
     # Standard ReAct strategy (recommended for most cases)
     standard_agent = create_agent(
-        url="https://api.openai.com",
-        key="your-api-key",
+        base_url="https://api.openai.com",
+        api_key="your-api-key",
         strategy=ReActAgentStrategy
     )
 
     # Hybrid strategy for MoE models
     hybrid_agent = create_agent(
-        url="https://api.moemodel.com",
-        key="your-api-key",
+        base_url="https://api.moemodel.com",
+        api_key="your-api-key",
         strategy=HybridReActAgentStrategy
     )
 
     # No-action strategy to skip tool execution
     no_action_agent = create_agent(
-        url="https://api.example.com",
-        key="your-api-key",
+        base_url="https://api.example.com",
+        api_key="your-api-key",
         strategy=NoActionAgentStrategy
     )
 

docs/docs/guide/concepts/event.md

@@ -54,9 +54,9 @@ async def handle_fallback(event: FallbackContext):
 
     # Switch to a different preset for retry
     # The system will automatically use event.preset for the next attempt
-    if event.term == 1:  # First retry
+    if event.term == 0:  # First attempt
         event.preset = get_alternative_preset()  # Your custom function to get alternative preset
-    elif event.term == 2:  # Second retry
+    elif event.term == 1:  # First retry
         event.preset = get_safe_preset()  # Your custom function to get a safe/cheaper preset
     else:
         # Mark as failed if no more fallbacks available
@@ -70,7 +70,7 @@ The `FallbackContext` provides the following properties:
 - `exc_info`: The exception that caused the failure
 - `config`: The current [AmritaConfig](../api-reference/classes/AmritaConfig.md)
 - `context`: The [SendMessageWrap](../api-reference/classes/SendMessageWrap.md) containing the message context
-- `term`: The current retry attempt number (starting from 1)
+- `term`: The current retry attempt number, counting from **0** (first call) up to `max_retries - 1`.
 
 You can modify the `event.preset` to switch to a different model preset for the next retry attempt. If no suitable fallback is available, call `event.fail(reason)` to terminate the retry process.
 

docs/docs/guide/extensions-integration/index.md

@@ -612,16 +612,16 @@ Combine AmritaCore with other frameworks:
 ```python
 # Example: Integration with FastAPI for a web service
 from fastapi import FastAPI
-from amrita_core import ChatObject, init
-from amrita_core.config import AmritaConfig
+from amrita_core import ChatObject, minimal_init
+from amrita_core.config import AmritaConfig, set_config
 from amrita_core.types import MemoryModel, Message
 
 app = FastAPI()
 
 # Initialize AmritaCore when the app starts
-init()
-from amrita_core.config import set_config
-set_config(AmritaConfig())
+@app.on_event("startup")
+async def startup():
+    await minimal_init(AmritaConfig())
 
 @app.post("/chat/")
 async def chat_endpoint(user_input: str, session_id: str):

docs/docs/guide/security-mechanisms.md

@@ -12,18 +12,18 @@ The cookie system works by inserting a unique identifier into the conversation c
 
 ### 6.1.2 CookieConfig Configuration
 
-The [CookieConfig](../api-reference/classes/CookieConfig.md) class manages cookie-related security settings:
+The [CookieConfig](../api-reference/classes/CookieConfig.md) class manages cookie-related security settings. Cookie security is **enabled by default** (`enable_cookie=True`) — no explicit configuration is needed unless you want to customise the cookie string:
 
 ```python
 from amrita_core.config import CookieConfig
 
-# Enable cookie security detection
+# Cookie security is ON by default.  These examples show how to change the cookie.
 security_config = CookieConfig(
-    enable_cookie=True,              # Enable the cookie leak detection mechanism
+    enable_cookie=True,              # Already the default, shown for clarity
     cookie="custom_cookie_string"    # Custom cookie string (defaults to random string)
 )
 
-# Or let the system generate a random cookie automatically
+# Or let the system generate a random cookie automatically (this is the default behaviour)
 default_security_config = CookieConfig(enable_cookie=True)
 ```
 

docs/docs/zh/guide/api-reference/index.md

@@ -2,24 +2,18 @@
 
 ## 7.1 核心 API 函数
 
-### 7.1.1 init() - 初始化
+### 7.1.1 init() - 初始化（已废弃）
 
-`init()` 函数初始化 AmritaCore 的核心组件，必须在任何其他操作之前调用。
+> **已废弃**：`init()` 函数从 v0.9.0rc1 起已废弃。现在是空操作存根，不再执行任何初始化。请改用 `load_amrita()` 进行异步初始化。
 
 ```python
 from amrita_core import init
 
-# 初始化 AmritaCore
+# 不再必要 — 现在是一个空操作
 init()
 ```
 
-**用途**: 准备 AmritaCore 的内部组件，初始化 Jieba 用于文本处理，加载内置模块并设置核心框架。
-
-**使用注意事项**:
-
-- 必须在任何其他 AmritaCore 函数之前调用
-- 线程安全，可以多次调用（后续调用是无操作）
-- 设置日志记录和内部状态
+**迁移**: 删除代码中所有 `init()` 调用。需要异步初始化时（例如 MCP 客户端设置）使用 `load_amrita()`。
 
 ### 7.1.2 load_amrita() - 加载框架
 
@@ -39,7 +33,7 @@ asyncio.run(main())
 
 **使用注意事项**:
 
-- 必须在 `init()` 和 `set_config()` 之后调用
+- 必须在 `set_config()` 之后调用
 - 应该被等待，因为它是一个异步函数
 
 ### 7.1.3 set_config() - 设置配置
@@ -61,7 +55,7 @@ set_config(config)
 
 **使用注意事项**:
 
-- 必须在 `init()` 之后但在 `load_amrita()` 之前调用
+- 应该在 `load_amrita()` 之前调用
 - 配置会影响所有后续操作
 
 ### 7.1.4 get_config() - 获取配置
@@ -79,8 +73,8 @@ print(config.function_config.use_minimal_context)
 
 **使用注意事项**:
 
-- 如果 AmritaCore 未初始化则抛出 RuntimeError
-- 在初始化后调用是安全的
+- 如果尚未调用 `set_config()` 则抛出 RuntimeError
+- 初始化后调用是安全的
 
 ### 7.1.5 create_agent() - Agent 创建
 

docs/docs/zh/guide/concepts/agent-strategy.md

@@ -197,22 +197,22 @@ async def use_builtin_strategies():
 
     # 标准ReAct策略（推荐用于大多数情况）
     standard_agent = create_agent(
-        url="https://api.openai.com",
-        key="your-api-key",
+        base_url="https://api.openai.com",
+        api_key="your-api-key",
         strategy=ReActAgentStrategy
     )
 
     # MoE模型的混合策略
     hybrid_agent = create_agent(
-        url="https://api.moemodel.com",
-        key="your-api-key",
+        base_url="https://api.moemodel.com",
+        api_key="your-api-key",
         strategy=HybridReActAgentStrategy
     )
 
     # 跳过工具执行的无操作策略
     no_action_agent = create_agent(
-        url="https://api.example.com",
-        key="your-api-key",
+        base_url="https://api.example.com",
+        api_key="your-api-key",
         strategy=NoActionAgentStrategy
     )
 
@@ -254,22 +254,22 @@ async def use_builtin_strategies():
 ```python
 from amrita_core.agent.strategy import StrategyLikedObject
 
-class 限流策略(StrategyLikedObject):
-    def __init__(self, 最大调用次数: int, api_key: str):
-        self.最大调用次数 = 最大调用次数
-        self.调用计数 = 0
+class RateLimitedStrategy(StrategyLikedObject):
+    def __init__(self, max_calls: int, api_key: str):
+        self.max_calls = max_calls
+        self.call_count = 0
         self.api_key = api_key
-        self.客户端 = MyAPIClient(api_key)  # 预加载资源
+        self.client = MyAPIClient(api_key)  # 预加载资源
 
     @classmethod
     def get_category(cls) -> str:
         return "agent"
 
     async def single_execute(self) -> bool:
-        self.调用计数 += 1
-        if self.调用计数 > self.最大调用次数:
+        self.call_count += 1
+        if self.call_count > self.max_calls:
             return False  # 停止
-        # 使用 self.客户端 进行 API 调用...
+        # 使用 self.client 进行 API 调用...
         return True
 
     async def on_limited(self) -> None:
@@ -278,13 +278,13 @@ class 限流策略(StrategyLikedObject):
         )
 
 # 传入实例 — 而非类
-策略 = 限流策略(最大调用次数=5, api_key="sk-...")
+strategy = RateLimitedStrategy(max_calls=5, api_key="sk-...")
 chat_obj = ChatObject(
     train={"system": "你是一个有用的助手"},
     user_input="你好",
     context=None,
     session_id="session_123",
-    agent_strategy=策略,  # 实例！
+    agent_strategy=strategy,  # 传入实例
 )
 ```
 

docs/docs/zh/guide/extensions-integration/index.md

@@ -611,16 +611,16 @@ async def get_weather_data(data: dict) -> str:
 ```python
 # 示例: 与 FastAPI 集成为 Web 服务
 from fastapi import FastAPI
-from amrita_core import ChatObject, init
-from amrita_core.config import AmritaConfig
+from amrita_core import ChatObject, minimal_init
+from amrita_core.config import AmritaConfig, set_config
 from amrita_core.types import MemoryModel, Message
 
 app = FastAPI()
 
 # 启动应用时初始化 AmritaCore
-init()
-from amrita_core.config import set_config
-set_config(AmritaConfig())
+@app.on_event("startup")
+async def startup():
+    await minimal_init(AmritaConfig())
 
 @app.post("/chat/")
 async def chat_endpoint(user_input: str, session_id: str):

docs/docs/zh/guide/function-implementation.md

@@ -2,23 +2,24 @@
 
 ## 4.1 初始化和加载
 
-### 4.1.1 init() 初始化函数
+### 4.1.1 init() 初始化函数（已废弃）
 
-`init()` 函数初始化AmritaCore的核心组件，在执行任何其他操作之前必须调用：
+> **从 v0.9.0rc1 起已废弃**：`init()` 函数现在是空操作存根，不再执行任何初始化。请改用 `minimal_init()` 或 `load_amrita()` 进行异步初始化。
 
 ```python
 from amrita_core import init
 
-# 初始化AmritaCore
+# 不再必要 — 现在是一个空操作
 init()
 ```
 
-此函数执行几项关键任务：
+此函数以前执行几项关键任务：
 
 - 设置内部日志记录
-- 初始化Jieba进行文本处理（如果可用）
+- 初始化Jieba进行文本处理
 - 加载内置模块
-- 准备核心框架以供使用
+
+这些任务现在由框架自动处理，或通过 `amrita-sense` 完成。
 
 ### 4.1.2 load_amrita() 异步加载
 
@@ -35,9 +36,21 @@ async def main():
 asyncio.run(main())
 ```
 
-### 4.1.3 配置设置和检索
+### 4.1.3 minimal_init() 最小化初始化
+
+`minimal_init()` 结合了配置设置和异步加载，是推荐的初始化方式：
+
+```python
+from amrita_core import minimal_init
+from amrita_core.config import AmritaConfig
+
+# 一行完成初始化和配置
+await minimal_init(AmritaConfig())
+```
+
+### 4.1.4 配置设置和检索
 
-#### 4.1.3.1 set_config() 设置配置
+#### 4.1.4.1 set_config() 设置配置
 
 `set_config()` 函数将配置应用到AmritaCore：