项目配置

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`
`entry_point`	导入 Agent 的 Python 文件
`agent_variable`	文件中导出的 Agent 对象变量名
`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

环境变量

模型配置通常放在 .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 等约定路径。公开项目建议始终使用 YAML。