From cd06961910bac4bff27081dca2d46667c005a054 Mon Sep 17 00:00:00 2001 From: "fangyaozheng@bytedance.com" Date: Mon, 15 Jun 2026 13:49:16 +0800 Subject: [PATCH 1/3] docs(examples): spell out the codex-on-AgentKit deploy choices Users following the README hit the interactive `agentkit config` wizard and could pick wrong (esp. the TOS bucket). Replace the bare command list in the "Deploy" step with: - a copy-paste non-interactive `agentkit config` command (3 placeholders), and - the choices that matter if configuring interactively: launch type = cloud, TOS bucket = Auto (avoids the ListBuckets ownership failure), auth = API Key, runtime role, and the required MODEL_AGENT_* env vars. zh + en. --- examples/codex_runtime_on_agentkit/README.md | 45 +++++++++++++++---- .../codex_runtime_on_agentkit/README.zh.md | 41 +++++++++++++---- 2 files changed, 68 insertions(+), 18 deletions(-) diff --git a/examples/codex_runtime_on_agentkit/README.md b/examples/codex_runtime_on_agentkit/README.md index 527763c1..3f7f5f28 100644 --- a/examples/codex_runtime_on_agentkit/README.md +++ b/examples/codex_runtime_on_agentkit/README.md @@ -56,18 +56,45 @@ the bundled Codex binary spawns. ## 3. Deploy to AgentKit -```bash -# fill in account-specific fields in agentkit.yaml (interactive) -veadk agentkit config - -# build the image and deploy in one step -veadk agentkit launch +`agentkit config` writes `agentkit.yaml`; `agentkit launch` then builds and +deploys from it. The fastest, mistake-proof path is to configure +**non-interactively** (fill in the three `<...>` placeholders): -# check status / send a test request once it's live -veadk agentkit status -veadk agentkit invoke "你好，你叫什么" +```bash +veadk agentkit config \ + --agent_name codex-runtime-demo --entry_point app.py \ + --language Python --language_version 3.12 \ + --launch_type cloud --region cn-beijing \ + --tos_bucket Auto \ + --runtime_name codex-runtime-demo --runtime_apikey_name Auto \ + --runtime_role_name \ + --runtime_envs MODEL_AGENT_PROVIDER=openai \ + --runtime_envs MODEL_AGENT_NAME= \ + --runtime_envs MODEL_AGENT_API_BASE=https://ark.cn-beijing.volces.com/api/v3/\ + --runtime_envs MODEL_AGENT_API_KEY= \ + --runtime_envs OTEL_SDK_DISABLED=true + +veadk agentkit launch # build + deploy in one step +veadk agentkit status # wait until Ready +veadk agentkit invoke "你好，你叫什么" # test it ``` +If you run `veadk agentkit config` **interactively** instead, the choices +that matter: + +- **Launch type** → `cloud` (deploy to an AgentKit cloud runtime). +- **Entry point** → `app.py` (this example's deploy entry). +- **TOS bucket** → `Auto`. Otherwise the upload fails the bucket-ownership + (`ListBuckets`) check, unless your AK/SK has `tos:ListBuckets`. +- **Auth type** → API Key (the default). `custom_jwt` additionally needs a + JWT discovery URL and client IDs. +- **API key name** → `Auto` (auto-generated). +- **Runtime role** → your account's AgentKit runtime service role (required + to create the runtime). +- **Runtime env vars** → the `MODEL_AGENT_*` set shown above. Required: the + codex runtime needs `MODEL_AGENT_API_BASE` + `MODEL_AGENT_API_KEY`, or it + fails to start a turn. + `veadk agentkit launch` = `build` + `deploy`. Use `veadk agentkit destroy` to tear the runtime down. diff --git a/examples/codex_runtime_on_agentkit/README.zh.md b/examples/codex_runtime_on_agentkit/README.zh.md index bf85071e..8f1da63c 100644 --- a/examples/codex_runtime_on_agentkit/README.zh.md +++ b/examples/codex_runtime_on_agentkit/README.zh.md @@ -52,18 +52,41 @@ python app.py # 或：python -m app ## 3. 部署到 AgentKit -```bash -# 交互式填写 agentkit.yaml 中与账号相关的字段 -veadk agentkit config - -# 一步完成镜像构建与部署 -veadk agentkit launch +`agentkit config` 写出 `agentkit.yaml`，`agentkit launch` 再据此构建并部署。最快、 +最不容易选错的方式是**非交互式**配置（填好三个 `<...>` 占位符）： -# 上线后查看状态 / 发测试请求 -veadk agentkit status -veadk agentkit invoke "你好，你叫什么" +```bash +veadk agentkit config \ + --agent_name codex-runtime-demo --entry_point app.py \ + --language Python --language_version 3.12 \ + --launch_type cloud --region cn-beijing \ + --tos_bucket Auto \ + --runtime_name codex-runtime-demo --runtime_apikey_name Auto \ + --runtime_role_name <你账号的-AgentKit-runtime-服务角色> \ + --runtime_envs MODEL_AGENT_PROVIDER=openai \ + --runtime_envs MODEL_AGENT_NAME=<你的模型> \ + --runtime_envs MODEL_AGENT_API_BASE=https://ark.cn-beijing.volces.com/api/v3/\ + --runtime_envs MODEL_AGENT_API_KEY=<你的-ark-key> \ + --runtime_envs OTEL_SDK_DISABLED=true + +veadk agentkit launch # 一步完成构建 + 部署 +veadk agentkit status # 等到 Ready +veadk agentkit invoke "你好，你叫什么" # 测试 ``` +如果你改用 `veadk agentkit config` **交互式**向导，关键几项这样选： + +- **部署方式 / launch type** → `cloud`（部署到 AgentKit 云端 runtime）。 +- **入口 / entry point** → `app.py`（本示例的部署入口）。 +- **TOS bucket** → `Auto`。否则上传会卡在 bucket 所有权（`ListBuckets`）校验， + 除非你的 AK/SK 有 `tos:ListBuckets` 权限。 +- **鉴权 / auth type** → API Key（默认）。`custom_jwt` 还要额外配 JWT discovery + URL 和 client ID。 +- **API key 名** → `Auto`（自动生成）。 +- **runtime 角色** → 你账号里的 AgentKit runtime 服务角色（创建 runtime 必需）。 +- **环境变量** → 上面那组 `MODEL_AGENT_*`。必填：codex 运行时需要 + `MODEL_AGENT_API_BASE` + `MODEL_AGENT_API_KEY`，否则无法开始一轮。 + `veadk agentkit launch` = `build` + `deploy`。用 `veadk agentkit destroy` 拆除。 ## 注意 From 2ca71019add7f2a65baf6f2f407adb506abc32b2 Mon Sep 17 00:00:00 2001 From: "fangyaozheng@bytedance.com" Date: Mon, 15 Jun 2026 14:01:48 +0800 Subject: [PATCH 2/3] docs(examples): mark codex-on-AgentKit deploy fields required vs optional Split the deploy config into explicit **Required** / **Optional** groups so users know what they must fill: agent_name/entry_point/launch_type/region, tos_bucket=Auto, runtime_role_name, and the MODEL_AGENT_ name/base/key env vars are required; language/version, runtime_name, apikey name, auth type, MODEL_AGENT_PROVIDER and OTEL_SDK_DISABLED are optional/defaulted. zh + en. --- examples/codex_runtime_on_agentkit/README.md | 36 +++++++++++-------- .../codex_runtime_on_agentkit/README.zh.md | 31 +++++++++------- 2 files changed, 40 insertions(+), 27 deletions(-) diff --git a/examples/codex_runtime_on_agentkit/README.md b/examples/codex_runtime_on_agentkit/README.md index 3f7f5f28..f8093393 100644 --- a/examples/codex_runtime_on_agentkit/README.md +++ b/examples/codex_runtime_on_agentkit/README.md @@ -79,21 +79,27 @@ veadk agentkit status # wait until Ready veadk agentkit invoke "你好，你叫什么" # test it ``` -If you run `veadk agentkit config` **interactively** instead, the choices -that matter: - -- **Launch type** → `cloud` (deploy to an AgentKit cloud runtime). -- **Entry point** → `app.py` (this example's deploy entry). -- **TOS bucket** → `Auto`. Otherwise the upload fails the bucket-ownership - (`ListBuckets`) check, unless your AK/SK has `tos:ListBuckets`. -- **Auth type** → API Key (the default). `custom_jwt` additionally needs a - JWT discovery URL and client IDs. -- **API key name** → `Auto` (auto-generated). -- **Runtime role** → your account's AgentKit runtime service role (required - to create the runtime). -- **Runtime env vars** → the `MODEL_AGENT_*` set shown above. Required: the - codex runtime needs `MODEL_AGENT_API_BASE` + `MODEL_AGENT_API_KEY`, or it - fails to start a turn. +The fields split into **required** and **optional** (these are the same +things the interactive `agentkit config` wizard asks for): + +**Required** — you must set these: + +- `--agent_name`, `--entry_point app.py`, `--launch_type cloud`, `--region`. +- `--tos_bucket Auto` — without `Auto`, the upload fails the bucket-ownership + (`ListBuckets`) check unless your AK/SK has `tos:ListBuckets`. +- `--runtime_role_name` — your account's AgentKit runtime service role. +- `--runtime_envs` for `MODEL_AGENT_NAME`, `MODEL_AGENT_API_BASE`, + `MODEL_AGENT_API_KEY` — the codex runtime can't start a turn without the + model's base URL + key. + +**Optional** — sensible defaults if omitted: + +- `--language` / `--language_version` — default to Python 3.12. +- `--runtime_name` / `--runtime_apikey_name Auto` — auto-generated if omitted. +- Auth type — defaults to **API Key**; `custom_jwt` also needs a JWT discovery + URL and client IDs. +- `--runtime_envs MODEL_AGENT_PROVIDER=openai` (defaults to `openai`) and + `OTEL_SDK_DISABLED=true` (recommended — silences OTel connection errors). `veadk agentkit launch` = `build` + `deploy`. Use `veadk agentkit destroy` to tear the runtime down. diff --git a/examples/codex_runtime_on_agentkit/README.zh.md b/examples/codex_runtime_on_agentkit/README.zh.md index 8f1da63c..7fde5e14 100644 --- a/examples/codex_runtime_on_agentkit/README.zh.md +++ b/examples/codex_runtime_on_agentkit/README.zh.md @@ -74,18 +74,25 @@ veadk agentkit status # 等到 Ready veadk agentkit invoke "你好，你叫什么" # 测试 ``` -如果你改用 `veadk agentkit config` **交互式**向导，关键几项这样选： - -- **部署方式 / launch type** → `cloud`（部署到 AgentKit 云端 runtime）。 -- **入口 / entry point** → `app.py`（本示例的部署入口）。 -- **TOS bucket** → `Auto`。否则上传会卡在 bucket 所有权（`ListBuckets`）校验， - 除非你的 AK/SK 有 `tos:ListBuckets` 权限。 -- **鉴权 / auth type** → API Key（默认）。`custom_jwt` 还要额外配 JWT discovery - URL 和 client ID。 -- **API key 名** → `Auto`（自动生成）。 -- **runtime 角色** → 你账号里的 AgentKit runtime 服务角色（创建 runtime 必需）。 -- **环境变量** → 上面那组 `MODEL_AGENT_*`。必填：codex 运行时需要 - `MODEL_AGENT_API_BASE` + `MODEL_AGENT_API_KEY`，否则无法开始一轮。 +各字段分为**必填**和**可选**（交互式 `agentkit config` 向导问的也是这些）： + +**必填**（必须设置）： + +- `--agent_name`、`--entry_point app.py`、`--launch_type cloud`、`--region`。 +- `--tos_bucket Auto` —— 不设 `Auto` 的话，上传会卡在 bucket 所有权 + （`ListBuckets`）校验，除非你的 AK/SK 有 `tos:ListBuckets` 权限。 +- `--runtime_role_name` —— 你账号里的 AgentKit runtime 服务角色。 +- `--runtime_envs` 里的 `MODEL_AGENT_NAME`、`MODEL_AGENT_API_BASE`、 + `MODEL_AGENT_API_KEY` —— 缺了模型的 base URL + key，codex 运行时无法开始一轮。 + +**可选**（不填走默认）： + +- `--language` / `--language_version` —— 默认 Python 3.12。 +- `--runtime_name` / `--runtime_apikey_name Auto` —— 不填会自动生成。 +- 鉴权方式 —— 默认 **API Key**；`custom_jwt` 还要额外配 JWT discovery URL 和 + client ID。 +- `--runtime_envs MODEL_AGENT_PROVIDER=openai`（默认 `openai`）和 + `OTEL_SDK_DISABLED=true`（建议加，避免 OTel 连接报错）。 `veadk agentkit launch` = `build` + `deploy`。用 `veadk agentkit destroy` 拆除。 From 02b83ae33f7e2ad70a175528069d4d29900c4651 Mon Sep 17 00:00:00 2001 From: "fangyaozheng@bytedance.com" Date: Mon, 15 Jun 2026 14:07:36 +0800 Subject: [PATCH 3/3] docs(examples): trim deploy config to the minimal required flags Per maintainer: MODEL_AGENT_* don't need to go in --runtime_envs (they are read from the .env bundled into the image), and --runtime_role_name is auto-selected. Show the minimal config command and move both to Optional; the required set is agent_name/entry_point/language(+version)/launch_type/region/tos_bucket=Auto/ runtime_name/runtime_apikey_name + OTEL_SDK_DISABLED. zh + en. --- examples/codex_runtime_on_agentkit/README.md | 30 +++++++------------ .../codex_runtime_on_agentkit/README.zh.md | 28 +++++++---------- 2 files changed, 20 insertions(+), 38 deletions(-) diff --git a/examples/codex_runtime_on_agentkit/README.md b/examples/codex_runtime_on_agentkit/README.md index f8093393..5d76a641 100644 --- a/examples/codex_runtime_on_agentkit/README.md +++ b/examples/codex_runtime_on_agentkit/README.md @@ -57,8 +57,9 @@ the bundled Codex binary spawns. ## 3. Deploy to AgentKit `agentkit config` writes `agentkit.yaml`; `agentkit launch` then builds and -deploys from it. The fastest, mistake-proof path is to configure -**non-interactively** (fill in the three `<...>` placeholders): +deploys from it. The model config (`MODEL_AGENT_*`) is read from the `.env` +from step 1, which is bundled into the image, so it need not go in +`--runtime_envs`. A minimal config: ```bash veadk agentkit config \ @@ -67,11 +68,6 @@ veadk agentkit config \ --launch_type cloud --region cn-beijing \ --tos_bucket Auto \ --runtime_name codex-runtime-demo --runtime_apikey_name Auto \ - --runtime_role_name \ - --runtime_envs MODEL_AGENT_PROVIDER=openai \ - --runtime_envs MODEL_AGENT_NAME= \ - --runtime_envs MODEL_AGENT_API_BASE=https://ark.cn-beijing.volces.com/api/v3/\ - --runtime_envs MODEL_AGENT_API_KEY= \ --runtime_envs OTEL_SDK_DISABLED=true veadk agentkit launch # build + deploy in one step @@ -79,27 +75,21 @@ veadk agentkit status # wait until Ready veadk agentkit invoke "你好，你叫什么" # test it ``` -The fields split into **required** and **optional** (these are the same -things the interactive `agentkit config` wizard asks for): - -**Required** — you must set these: +**Required** — set these: - `--agent_name`, `--entry_point app.py`, `--launch_type cloud`, `--region`. +- `--language` / `--language_version`. - `--tos_bucket Auto` — without `Auto`, the upload fails the bucket-ownership (`ListBuckets`) check unless your AK/SK has `tos:ListBuckets`. -- `--runtime_role_name` — your account's AgentKit runtime service role. -- `--runtime_envs` for `MODEL_AGENT_NAME`, `MODEL_AGENT_API_BASE`, - `MODEL_AGENT_API_KEY` — the codex runtime can't start a turn without the - model's base URL + key. +- `--runtime_name` / `--runtime_apikey_name Auto`. -**Optional** — sensible defaults if omitted: +**Optional** — omit and AgentKit handles it: -- `--language` / `--language_version` — default to Python 3.12. -- `--runtime_name` / `--runtime_apikey_name Auto` — auto-generated if omitted. +- `--runtime_role_name` — auto-selected/created if omitted. +- `MODEL_AGENT_*` — read from the bundled `.env`, so not needed in + `--runtime_envs` (`OTEL_SDK_DISABLED=true` is worth passing to silence OTel). - Auth type — defaults to **API Key**; `custom_jwt` also needs a JWT discovery URL and client IDs. -- `--runtime_envs MODEL_AGENT_PROVIDER=openai` (defaults to `openai`) and - `OTEL_SDK_DISABLED=true` (recommended — silences OTel connection errors). `veadk agentkit launch` = `build` + `deploy`. Use `veadk agentkit destroy` to tear the runtime down. diff --git a/examples/codex_runtime_on_agentkit/README.zh.md b/examples/codex_runtime_on_agentkit/README.zh.md index 7fde5e14..c8dc6564 100644 --- a/examples/codex_runtime_on_agentkit/README.zh.md +++ b/examples/codex_runtime_on_agentkit/README.zh.md @@ -52,8 +52,9 @@ python app.py # 或：python -m app ## 3. 部署到 AgentKit -`agentkit config` 写出 `agentkit.yaml`，`agentkit launch` 再据此构建并部署。最快、 -最不容易选错的方式是**非交互式**配置（填好三个 `<...>` 占位符）： +`agentkit config` 写出 `agentkit.yaml`，`agentkit launch` 再据此构建并部署。模型 +配置（`MODEL_AGENT_*`）从第 1 步的 `.env` 读取（它会被打包进镜像），所以**不必** +再写进 `--runtime_envs`。最小配置： ```bash veadk agentkit config \ @@ -62,11 +63,6 @@ veadk agentkit config \ --launch_type cloud --region cn-beijing \ --tos_bucket Auto \ --runtime_name codex-runtime-demo --runtime_apikey_name Auto \ - --runtime_role_name <你账号的-AgentKit-runtime-服务角色> \ - --runtime_envs MODEL_AGENT_PROVIDER=openai \ - --runtime_envs MODEL_AGENT_NAME=<你的模型> \ - --runtime_envs MODEL_AGENT_API_BASE=https://ark.cn-beijing.volces.com/api/v3/\ - --runtime_envs MODEL_AGENT_API_KEY=<你的-ark-key> \ --runtime_envs OTEL_SDK_DISABLED=true veadk agentkit launch # 一步完成构建 + 部署 @@ -74,25 +70,21 @@ veadk agentkit status # 等到 Ready veadk agentkit invoke "你好，你叫什么" # 测试 ``` -各字段分为**必填**和**可选**（交互式 `agentkit config` 向导问的也是这些）： - -**必填**（必须设置）： +**必填**（要设置）： - `--agent_name`、`--entry_point app.py`、`--launch_type cloud`、`--region`。 +- `--language` / `--language_version`。 - `--tos_bucket Auto` —— 不设 `Auto` 的话，上传会卡在 bucket 所有权 （`ListBuckets`）校验，除非你的 AK/SK 有 `tos:ListBuckets` 权限。 -- `--runtime_role_name` —— 你账号里的 AgentKit runtime 服务角色。 -- `--runtime_envs` 里的 `MODEL_AGENT_NAME`、`MODEL_AGENT_API_BASE`、 - `MODEL_AGENT_API_KEY` —— 缺了模型的 base URL + key，codex 运行时无法开始一轮。 +- `--runtime_name` / `--runtime_apikey_name Auto`。 -**可选**（不填走默认）： +**可选**（不填由 AgentKit 自动处理）： -- `--language` / `--language_version` —— 默认 Python 3.12。 -- `--runtime_name` / `--runtime_apikey_name Auto` —— 不填会自动生成。 +- `--runtime_role_name` —— 不填会自动选/建。 +- `MODEL_AGENT_*` —— 从打包进镜像的 `.env` 读取，不必写进 `--runtime_envs` + （`OTEL_SDK_DISABLED=true` 建议带上，避免 OTel 连接报错）。 - 鉴权方式 —— 默认 **API Key**；`custom_jwt` 还要额外配 JWT discovery URL 和 client ID。 -- `--runtime_envs MODEL_AGENT_PROVIDER=openai`（默认 `openai`）和 - `OTEL_SDK_DISABLED=true`（建议加，避免 OTel 连接报错）。 `veadk agentkit launch` = `build` + `deploy`。用 `veadk agentkit destroy` 拆除。