> ## Documentation Index
> Fetch the complete documentation index at: https://docs.veadk.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# 运行时

运行时决定智能体「内层循环」如何执行——即每一轮如何调用模型、解析意图、调用工具。默认运行时基于 Google ADK 的内置执行流程，开箱即用；你也可以切换执行后端，或在执行流程上插入统一的处理逻辑，而无需改动智能体本身。

## 默认运行时

默认即为 ADK 运行时，无需额外配置：

```python lines theme={null}
from veadk import Agent

agent = Agent(name="assistant")  # 默认使用 ADK 运行时
```

## 切换执行后端

通过 `runtime` 选择内层循环的执行后端：

使用 Codex 运行时前需安装其 Python SDK：

```bash lines theme={null}
pip install openai-codex
```

<Warning>
  VeADK 1.0.1 的 Codex 运行时默认允许执行命令、读写主机文件和访问网络，且不提供交互式操作确认。仅应在隔离环境中运行可信任务，并限制进程可访问的凭证和数据。
</Warning>

```python lines theme={null}
agent = Agent(name="assistant", runtime="codex")
```

| 取值 | 说明 |
| - | - |
| `adk`（默认） | 使用 Google ADK 内置的执行流程，适用于绝大多数场景。 |
| `codex` | 使用 Codex SDK 执行智能体内层循环；需要 `openai-codex`。 |

### Codex 运行时中的技能与工具

VeADK 1.0.1 会把智能体通过 ADK `SkillToolset` 或旧 `skills` 入口加载的技能提供给 Codex 运行时。智能体的函数工具和 MCP 工具也可在该运行时中调用：

```python lines theme={null}
from google.adk.tools.mcp_tool.mcp_toolset import MCPToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StdioServerParameters
from veadk import Agent

mcp_tools = MCPToolset(
    connection_params=StdioServerParameters(
        command="python",
        args=["mcp_server.py"],
    )
)

agent = Agent(runtime="codex", tools=[mcp_tools])
```

MCP Server 进程和其中的工具会获得当前运行环境允许的权限。仅连接可信 Server，并限制其文件、网络和凭证访问范围。

### Codex 后端请求

| 环境变量 | 默认值 | 说明 |
| - | - | - |
| `CODEX_SHIM_NUM_RETRIES` | `2` | 遇到限流、服务端错误、过载或超时时的重试次数；小于 `0` 的值按 `0` 处理。 |
| `CODEX_SHIM_TIMEOUT` | `0` | 单次后端请求超时秒数；`0` 表示不额外设置超时。 |

### 启用网页搜索

Codex 运行时通过火山方舟调用模型时，网页搜索默认关闭。将 `CODEX_SHIM_MAX_TOOL_ITERS` 设置为大于 `0` 的整数后，运行时可调用 VeADK 的 `web_search` 和 `web_fetch` 工具，并在限定的轮数内把搜索结果交给模型继续处理：

```bash lines theme={null}
export CODEX_SHIM_MAX_TOOL_ITERS=6
```

| 环境变量 | 默认值 | 说明 |
| - | - | - |
| `CODEX_SHIM_MAX_TOOL_ITERS` | `0` | 单次请求允许的网页工具调用轮数；`0` 表示关闭。建议从 `6` 开始，并按任务复杂度和响应时延调整。 |

网页搜索需要运行环境可以访问外部网络，并具备相应工具所需的凭证。配置方法见[网页搜索](/productions/veadk/archives/1.0.1/zh/components/tools/web-search)。网页内容来自外部来源，生产环境中应对结果进行校验，不应直接把搜索结果作为可信指令执行。

## 请求处理

在不侵入业务逻辑的前提下，可为每次执行插入统一的横切处理。将处理器传入 `run_processor` 即可，例如接入身份认证做登录态校验：

```python lines theme={null}
from veadk import Agent
from veadk.integrations.ve_identity import AuthRequestProcessor

agent = Agent(name="assistant", run_processor=AuthRequestProcessor())
```

不设置时使用默认处理器，不改变任何行为。VeADK 内置 `AuthRequestProcessor` 作为身份认证的开箱即用实现。

### 自定义处理器

所有处理器都继承抽象基类 `BaseRunProcessor`，实现其 `process_run(runner, message)` 方法。该方法返回一个包裹本轮「事件流」的装饰器，从而让你：

* 在整轮执行的**前后**插入逻辑（如鉴权、日志、性能监控）；
* **拦截、改写或注入**执行过程中产生的事件；
* 在此基础上实现重试等控制逻辑。

```python lines theme={null}
from veadk.processors.base_run_processor import BaseRunProcessor

class LoggingProcessor(BaseRunProcessor):
    def process_run(self, runner, message, **kwargs):
        def decorator(event_generator):
            async def wrapper():
                # 执行前：记录起始、校验等
                async for event in event_generator():
                    yield event  # 可在此拦截或改写事件
                # 执行后：汇总、上报等
            return wrapper
        return decorator
```