在腾讯云 EdgeOne Makers 上部署一个「摄影师智能体」

假如你是一名摄影师，长期在不同场景中完成拍摄，积累了大量关于构图、光线、镜头选择、参数设置和后期思路的经验。时间久了你会发现，很多摄影入门用户遇到的问题其实非常相似：不知道当前场景该怎么取景，不清楚不同光线下该如何调整参数，也很难判断一张照片为什么“不够好看”。这些问题如果由你亲自解答，当然可以给出专业建议。但每一次都依赖人工沟通，效率并不高，也很难把经验持续复用起来。更理想的方式，是把你多年积累下来的摄影方法、判断逻辑和创作经验，沉淀成一个可以随时响应用户问题的智能体服务。

Makers 正是这样一套面向 Agent 应用的托管底座。它把 Agent 从开发到上线过程中最容易分散精力的基础能力先托住：运行沙箱负责执行必要命令，上下文记忆和流式响应保证对话体验，工具调用链路让 Agent 能完成指定任务，AI 网关把模型选择从业务代码里解耦出来；上线后，追踪观测、版本管理、自定义域名等功能都集中在一个控制台中，让 Agent 可以稳定地被用户访问和持续迭代。开发者要做的不是从零搭一套 Agent 基础设施，仅需在这套托管链路上填入自己的业务能力，可以把主要精力放在经验的结构化、业务工具的接入以及最终用户体验的打磨上。

在这个案例里，我们会以“摄影师 Agent”为例，体验如何把个人经验转化为一个可访问、可部署、可持续迭代的 MVP 产品，并借助 EdgeOne 全球边缘网络上线。

具体来讲，它需要做到：

1. 用户用文字描述拍摄需求，Agent 能给出构图、参数、修图建议；

2. 用户提到地点和拍摄时间，Agent 能查实时天气和日出日落；

3. 用户使用内置支持的相机时，Agent 能查官方说明书，告诉用户菜单怎么按；

Step 1 · 从模板开始

做一个垂直 Agent，最开始通常不需要马上写很多业务相关的代码。更实际的第一步，是先让它拥有一个稳定的应用骨架：用户能发起对话，模型能持续返回内容，工具调用时前端能展示状态，用户不想等时可以中断，后续要加工具和页面也有清楚的代码结构。

如果从空项目开始，这些基础工作会比想象中更占时间。你要设计后端对话入口，要处理 SSE 或其他流式输出方式，要实现文本输入、工具调用、错误和完成状态。它们不是摄影业务本身，但没有这些，摄影师智能体就很难从一个本地代码变成用户能访问的 Agent 。

Makers 提供的模板把这部分先准备好了。模板里已经包含 /chat 主入口、SSE 流式响应、工具调用事件、中断接口、基础日志、前端请求封装和部署配置。开发者可以在这个骨架上替换业务层，而不是重新搭一套对话服务。对于摄影师智能体来说，这意味着不必再从“怎么让前端收到模型输出”开始写，而是可以直接进入更有业务价值的问题。Makers 让 Agent MVP 不必从底层工程脚手架开始。开发者可以从一个已经能跑的模板出发，把主要精力放到业务验证上。你可以根据自己的习惯选择不同模板，这里我们选择 OpenAI Agents 入门模板的 Python 版本。

体验模板

你可以先在 Makers 里体验一下默认对话模板实现的能力。

点击开始部署，Makers 会自动创建并填入运行所需的基础环境变量。部署成功后即可点击预览来体验模板。

这是一个把 OpenAI Agents SDK（Python）接到 EdgeOne Makers 上的最小但贴近生产形态的模板。完整跑通了流式响应、自定义工具注册、会话存储这条链路，方便你直接替换工具，而不是搭水管。

如果你决定从这个模板起步，那么可以点击下面链接获取模板。

GitHub - TencentEdgeOne/openai-agent-starter-python · GitHub

当然，如果你前面已经部署体验过模板，那么此时模板代码已经克隆在你自己的仓库里了。

如果你不熟悉代码，可以先把需求描述清楚，再把需求和 Agent 模板一起交给 WorkBuddy，它可以直接帮你完成代码改造和自动部署。

你只需要跳转到本文的部署上线部分，就能学会如何把 Agent 托管上线。但如果你想了解它背后的改造思路，也可以继续往下看。

Step 2 · 接入工具

摄影师智能体如果只靠模型常识，回答很容易变得泛泛。用户问“今天鼓浪屿日落值不值得拍”，它需要知道当前天气、云量和日落时间；用户问“机型 A 的 ISO 在哪里调”，它应该查说明书，而不是凭印象编一个菜单路径。

这些能力不能简单塞进 Prompt，Prompt 里放太多资料，会让上下文越来越长；模型也不一定能稳定判断什么时候该查天气、什么时候该查说明书。外部天气接口还可能失败、超时或限流。说明书检索如果不返回页码和原文片段，用户也很难确认答案是否可靠。更合理的方式，是把这些能力拆成工具，让 Agent 在需要时调用。摄影师智能体可以先拆成三类工具：

摄影经验工具：负责从结构化经验里返回当前场景相关的构图、参数和后期建议；

实时天气工具：负责查询指定地点的天气、云量、能见度、日出日落等信息；

说明书检索工具：负责从相机说明书里找菜单路径、页码和原文片段。

Makers 模板已经支持工具调用链路。开发者需要做的是把业务能力封装成工具，并告诉 Agent 什么时候应该使用它们。工具调用过程中，前端也可以通过流式事件把状态展示出来，例如“正在查实时天气”“正在检索说明书”“正在匹配构图经验”。这样用户等待时能看到 Agent 正在做什么，而不是面对一个没有反馈的加载状态。

Step 3 · 构建结构化知识库

摄影知识不建议直接写进系统提示里。系统提示更适合定义 Agent 的角色、回答规则和工具调用方式，不适合承载大量经验资料。如果把构图方法、参数建议、后期技巧都堆进 Prompt，后续不仅难维护，也会让上下文越来越长。更适合的做法，是把这些经验知识沉淀成一个结构化知识文件，放在 Agent 目录里。例如，我们可以新增一个 agents/_knowledge.py 文件，把摄影经验整理成结构化字典，再让工具按需读取。

这里有一个很实用的优势：在模板的目录约定里，带下划线的文件不会暴露为公开路由。也就是说，_knowledge.py 可以作为 Agent 内部使用的知识模块，专门存放核心经验、场景规则和参数建议，而不会被用户直接访问。

这样，摄影经验就不再是散落、难以整理的文本，而是变成了 Agent 可以稳定调用的内部知识模块。后续要新增场景、修改建议、接入更多资料，只需要继续扩展 _knowledge.py，不需要频繁改系统提示，也不会影响对外暴露的接口结构。对于 MVP 阶段来说，这种方式足够轻量：不用先搭复杂的向量库，也不用引入额外组件，只要在 Agent 目录中新增一个内部文件，就能把核心经验知识先沉淀下来，并让工具在需要时读取。

Step 4 · 对话存储能力

真实使用场景中，用户不一定会在第一轮就把所有信息说全。

用户可能先说：“我想拍日落。”

第二轮才补充：“地点在鼓浪屿。”

第三轮又说：“我用的是机型 A。”

后面再追问：“那 ISO 和测光应该怎么设置？”

如果 Agent 每一轮都像第一次见用户，用户就要反复说明地点、时间、设备和拍摄目标，体验会很割裂.

Makers Agent 默认提供对话存储能力，让 Agent 能够在同一次会话里持续承接上下文。它知道用户前面问过什么，也能基于前面的信息继续处理后续问题。这个能力是开箱即用的，零配置即可实现，帮助开发者省掉了复杂的拼装和调试流程。

Step 5 · 模型网关自由切换

Agent 项目上线后，模型选择通常不会一成不变。早期为了效果，可能选择能力更强的模型；用户量上来后，可能要考虑成本和速度，把部分任务切到更轻量的模型；新模型上线后，也可能希望做灰度测试或 A/B 对比。甚至在同一个摄影师智能体里，说明书问答和创作建议也可能适合不同的模型。如果在开发的时候就把模型厂商、模型 ID 和 API Key 都写死在业务代码里，每次切换都要改代码、测试、重新部署。模型选择就会从一个产品策略问题，变成一次工程处理问题。

Makers 底层接入 AI 网关，可以把模型调用从业务代码里解耦出来。开发者在代码里保留统一的模型接入方式，具体使用哪个模型、哪个厂商、哪个版本，通过网关侧配置和环境变量调整。只需要在项目的环节变量中增加下面的配置

AI_GATEWAY_BASE_URL=https://ai-gateway.edgeone.link/v1
AI_GATEWAY_API_KEY=sk-xxx......xxx
AI_GATEWAY_MODEL=@makers/modelname

后续要切模型，只需要修改模型名称即可。这样，业务代码可以始终保持稳定，模型能力也可以随着效果、成本和速度要求继续调整。这一点对 Agent 长期迭代非常重要。

Step 6 · 本地测试

现在，摄影师 Agent 已经能理解需求、调用工具、组织回答了。剩下的优化就看你想把它打磨到什么程度：知识库可以持续补充，说明书可以继续扩展，Prompt 可以反复优化，前端体验也可以慢慢做得更精致。但 MVP 最重要的事已经完成了：借助 Makers 平台，你跳过了复杂的基础工程开发，快速把沉淀的经验和文档资料封装成可复用的服务。接下来要做的，就是把它部署到平台上线，让更多用户来体验，并借此收集问题反馈。

Step 7 · 部署上线

1. 准备环境变量

如果你已经部署过默认模板，那么 Makers 已经帮你生成好了运行所需要的基础变量。你也可以参考下面的步骤来获取。

首先是调用平台自带模型网关的 API Key。回到 EdgeOne Makers 平台，选择「Models」，点击左侧的「API Key」选项卡，然后点击「创建 API Key」按钮。

自定一个名称，并设置过期时间，如果你的 Agent 准备长期在线，可以选择默认的永不过期。

创建完成后，你会获得一串"sk-xxx......xxx"的 Key，对应的就是 AI_GATEWAY_API_KEY 这个环境变量。请复制并妥善保管。出于安全原因，API Key 界面上不会再次显示，丢失后需重新创建。

然后点击左侧的「快速开始」选项卡。

下滑，在第四步 创建并运行脚本的第 5 行有一个 baseURL，引号里的值就是 AI 网关的地址，对应的就是 AI_GATEWAY_BASE_URL 这个环境变量，我们复制下来。

（可选）模板默认提供的模型是 deepseek-v4-flash。如果你想更换其他模型的话，可以在「模型与密钥」选项卡里，查看 AI_GATEWAY_MODEL 这个变量对应的模型 ID。例如，如果你想使用腾讯混元3.0模型，则变量名则为 @makers/hy3-preview。除了平台内置模型，你也可以接入第三方模型，只需要点击列表右侧的添加，并填入该模型的 API Key 即可获取对应的模型 ID 变量值。

现在，部署所需的基础环境变量就已经准备好了。

这里之所以把模型接入放到控制台配置里，是为了让后续模型切换更灵活。在 Agent 项目里，模型选择往往会持续变化。今天可能因为效果选择模型 A，之后可能因为成本或速度切换到模型 B，过一段时间又想试试新上线的模型 C。如果模型调用写进业务代码里，那么每次切换都要改代码、重新测试、重新发布，迭代节奏很容易被拖慢。

Makers 底层接入了 AI 网关，把模型调用从业务逻辑中抽离出来。代码里只需要保留统一的模型接入配置，具体使用哪个模型、哪家厂商、哪个版本，可以在网关侧统一调整。后续如果要切换模型、做 A/B 测试，或者按不同场景路由到不同模型，都不需要重新改造业务代码。

对开发者来说，这意味着 Agent 的“大脑”是可替换的：业务逻辑保持稳定，模型能力可以持续跟随平台和行业迭代。

2. 代码上传

下一步，将本地代码上传到 Makers 平台托管。如果上传的仓库是从 Makers 克隆到你账号下的，那么默认的网关环境变量已经预填好了。如果是新建项目，可以从以下方式中选择：

2.1 代码仓库上传

你已经有了代码仓库，比如 Github，最省事的方式就是先上传到仓库中，这里我们选择新建一个仓库：

git add .
git commit -m "feat: build photography agent"
git push

等上传完以后，回到 Makers 的控制台，选择「项目」标签，点击「导入 Git 仓库」。

如果是第一次使用，需要绑定对应的仓库平台。我们以 Github 为例，点击「Github」。

这里会弹出一个弹窗，登录 Github 账号，安装 EO Pages，默认会授权访问所有仓库，你也可以修改为只允许访问指定仓库。然后点击「Install」。

这样，就授权完成了。可以在仓库列表中选择刚才上传好的仓库。

默认选择的是仓库的 main 分支，如果打算托管特定的分支也可以手动搜索修改。

然后根据自身需求选择加速区域。需要注意的是，如果加速区域保包含中国大陆，则腾讯云账号必须完成实名认证，且仅支持完成 ICP 备案的自定义域名绑定。如果您没有提供中国大陆区域访问的需求，可以选择全球可用区（不含中国大陆）。

点击环境变量，在这里填入我们上面提到的几个变量名和变量值。

AI_GATEWAY_BASE_URL=https://ai-gateway.edgeone.link/v1
AI_GATEWAY_API_KEY=sk-xxx......xxx
AI_GATEWAY_MODEL=@makers/hy3-preview

如果你的 Agent 运行还需要额外的环境变量，可以在这里一并填入。

填写完成后点击「开始部署」，接下来等待部署完成即可。

部署成功后，就可以点击右上角「预览」按钮，获取临时预览链接。

2.2 Workbuddy上传

如果你是在 Workbuddy 上开发的 Agent，那么可以安装我们提供的 Skill：

npx skills add TencentEdgeOne/edgeone-makers-tools

这个 Skill 会先检查你有没有装 EdgeOne CLI，没有的话自动帮你配置。接着，它会问你两个问题：你用的是腾讯云国内站账号还是国际站账号，以及你打算怎么登录。

通常情况下，Workbuddy 会在浏览器中弹出腾讯云登录页，完成授权即可。如果你在特殊环境或者浏览器没法弹出，则会切换到 Token 登录模式，可以自行在 Makers 控制台的设置中生成 API Token，粘贴回来即完成授权。

登录完成后，需要手动在项目设置页里上传环境变量，并再重新部署一次。

部署成功后，就可以点击项目右上角「预览」按钮，获取临时预览链接。

3. 自定义域名

为保障内容合规，临时链接仅提供3小时限时预览，这个时候可以先对 Agent 做快速的正常运行测试。如果有对外提供访问或者长期使用的打算，建议及时添加自定义域名以确保服务持续可用。

点击「自定义域名」，或者直接点击左边的「域名管理」选项卡，就能来到域名管理页面。在这里能看到 EdgeOne 提供的默认临时域名。

点击「添加自定义域名」按钮，可以绑定你自己拥有的域名。

添加完域名后，需要手动调整域名的 CNAME 解析和配置 HTTPS。

如果你的域名注册在腾讯云的话，可以一键添加 CNAME 解析，等待一分钟即可生效。或者去你所使用的域名控制台手动修改解析。

HTTPS 配置则需要进一步操作。点击 HTTPS 配置列的「配置」按钮，再点击「边缘 HTTPS 证书」方框里的「配置」。

EdgeOne 提供了两种配置方式。第一种是针对没有证书但想实现 HTTPS 访问的用户。选择「申请免费证书」，EdgeOne 提供可自动申请、自动续签、自动部署的免费证书。

第二种则适用于已有 SSL 证书的用户。选择「申请 SSL 托管证书」可以将托管在腾讯云内的 SSL 的证书部署至 EdgeOne。

完成这两项配置后，就可以从你的自定义域名访问 Agent 了。

4. 观测能力

Agent 部署上线以后，另一个很重要的问题是：它到底有没有按预期运行？

普通 Web 应用出问题时，我们通常还能看接口日志、错误堆栈、请求耗时。但 Agent 应用的执行链路更长：用户发起一次对话后，模型可能会先理解问题，再调用工具，工具返回结果后模型再继续组织回答。如果中间某一步表现异常，只看最终回复很难判断问题出在哪里。

Makers 提供的观测能力，解决的就是这个问题。它会自动记录 Agent 的运行过程，不需要开发者从零搭一套日志系统。无论是在本地调试，还是部署到线上，都可以通过观测面板看到 Agent 的调用情况。

我们可以在 Makers 平台中点击要查看的项目，在左侧标签中展开「Agent」，可以看到 Metrics 和 Traces 两个观测面板。

Metrics 更适合看整体状态。比如 Agent 一共被调用了多少次、模型调用了多少次、平均耗时是多少、Token 消耗情况如何、有没有出现错误。它适合用来判断服务整体是否正常：是不是调用量上来了、是不是某个阶段变慢了、是不是 Token 消耗异常。

而 Traces 则更适合看单次执行细节。

每一次 Agent 请求都会形成一条完整的调用链。展开后可以看到这次请求里模型调用了几次、调用了哪些工具、工具入参是什么、返回了什么、每一步耗时多久。如果某一步报错，也可以直接在对应节点看到错误信息。

有了观测能力，开发者就不是靠猜来修 Agent，而是能沿着链路定位问题。对于 MVP 来说，这一点很重要：早期用户反馈往往很碎，只有把运行链路看清楚，才能判断是 Prompt 要改、工具要改，还是外部依赖要替换。

5. 构建版本

在构建部署页，你可以管理所有托管代码的版本，点击「更多」按钮还可以实现版本回滚。迭代过程中的每一次改动都有可能引入新问题，Makers 的构建版本和回滚能力，可以让开发者在新版本异常时先恢复到上一个稳定版本，再慢慢排查原因。这样 Agent 可以持续迭代，但线上服务不至于因为一次改动导致长时间不可用。

假设你对 Agent 代码进行了调整，想要同步到平台构建新版本，有两种方法能实现。

5.1 自动触发

如果你的代码托管在代码仓库，并且是使用代码仓库上传的形式部署的。那么只要再次往仓库的 main 分支推送新版本代码，Makers 平台会自动触发新建部署，无需额外操作。

5.2 手动构建

如果你的代码是本地上传，那么构建新版本时，需要进入项目的构建部署页。

点击「新建部署」按钮，上传新的代码文件或文件夹，再点击「开始部署」即可完成构建。

结语

到这里，一个摄影师智能体就完成了从模板到上线的完整过程。

回过头看，这个过程并不是从零开始搭建一套复杂系统，而是基于 Makers 已经提供好的 Agent 模板，把摄影场景里的经验、资料和判断逻辑一步步接进去：先明确 Agent 要解决什么问题，再整理知识库、拆分工具、接入实时能力、补充说明书检索，最后通过部署、观测和持续迭代，让它真正变成一个可以被用户访问和使用的服务。

这也是 Makers 的价值所在。它没有把开发者锁定在某一种框架、语言或模型里，而是把模型接入、工具调用、上下文记忆、沙箱运行、观测排查和部署上线这些通用能力提前打通。开发者真正需要关注的，是自己的业务场景：用户会问什么、哪些经验值得沉淀、哪些能力需要工具化、怎样让 Agent 的回答更稳定、更可信。

摄影师智能体只是一个例子。把“摄影”换成其他场景，本质上都可以沿用同样的方法：从模板出发，保留平台提供的基础链路，把自己的知识、工具和交互体验逐步替换进去，实现从 idea 到 MVP 的快速上线。

当一个 Agent 能够稳定承接问题、调用工具、引用资料、被观测、可部署，它就不再只是一个聊天窗口，而是一个可以持续迭代的业务服务。接下来，你可以根据前期用户反馈，继续扩展它的知识库、增加更多相机说明书、优化 Prompt 和前端体验，也可以把这套方法迁移到下一个领域，让那些原本依赖个人经验和重复沟通的工作，逐渐沉淀成可复用、可访问、可持续进化的智能服务。