项目配置

KsADK 项目建议显式提供 agentengine.yaml。显式配置比启发式检测更容易审查，也更适合公开示例。

最小配置

name: my-agent
version: "0.1.0"
framework: langgraph
entry_point: my_agent/agent.py
agent_variable: root_agent

字段	含义
`name`	项目名
`version`	项目版本
`framework`	代码框架为 `adk`、`langgraph`、`langchain` 或 `deepagents`；声明式 Runtime 使用 `codex`
`entry_point`	代码框架导入 Agent 的 Python 文件；Codex 不需要它
`agent_variable`	代码框架文件中导出的 Agent 对象变量名；Codex 不需要它
`artifact_type`	可选 specialized packaging mode；Codex ManagedRuntime 必填 `ManagedRuntime`
`runtime`	ManagedRuntime 的名称与锁定版本，例如 `name: codex`、`version: "0.144.4"`
`model` / `prompt`	声明式 Runtime 的模型与开发者指令
`ui_profile`	optional，UI profile 选择器，如 `custom`；默认 `auto`（0.6.7 新增）
`ui_bundle_path`	optional，custom UI 静态 bundle 相对项目路径，如 `research-ui/dist`（0.6.7 新增）
`ui_path`	optional，custom UI 挂载路径，如 `/` 或 `/research`；custom profile 下 `/chat` 会被自动修正为 `/`（0.6.7 新增）
`ui_url`	optional，外部 custom UI URL（0.6.7 新增）

框架示例

ADK：

framework: adk
entry_point: agent.py
agent_variable: root_agent

LangGraph：

framework: langgraph
entry_point: my_agent/agent.py
agent_variable: root_agent

Codex ManagedRuntime（0.8 新增）：

agentengine.yaml

name: my-codex-agent
version: "1.0.0"
framework: codex
artifact_type: ManagedRuntime
runtime:
  name: codex
  version: "0.144.4"
model: gpt-5.1-codex
prompt: |
  你是一个编码助手。

Codex manifest 没有 entry_point、agent_variable 或 agent.py。它由 model 与 prompt 定义 agent 行为；完整的本机和部署流程见 YAML 即 Agent：Codex。

环境变量

模型配置通常放在 .env：

OPENAI_API_KEY=sk-test
OPENAI_BASE_URL=https://api.example.com/v1
OPENAI_MODEL_NAME=my-model

不要把真实 key、私有 endpoint、kubeconfig 或客户数据提交到 Git。

云端部署配置

agentengine.yaml 可以保留不含密钥的网络默认值；命令行传参会覆盖文件中的值：

agentengine.yaml

network:
  enable_public_access: false
  enable_vpc_access: true
  vpc_id: vpc-xxxx
  subnet_id: subnet-xxxx
  security_group_id: sg-xxxx
  availability_zone: cn-beijing-6a

开启 VPC 时必须同时提供 vpc_id、subnet_id 和 security_group_id。模型 key、云账号 AK/SK、镜像仓库密码不要写入 YAML；它们应保存在未提交的 .env 或本机全局配置中。完整的前置条件、命令和验证步骤见部署到金山云。

检测规则

运行时优先读取显式 YAML；没有配置时才尝试 langgraph.json、agent.py、 main.py、app.py 等代码项目约定路径。Codex 必须使用显式 manifest；公开项目建议始终使用 YAML。