托管 Harness Agent 使用指南

选择 Harness

QwenPaw 与 Qoder 的差异集中在模型来源和上下文压缩机制两项：

需要在平台侧切换模型或模型提供方时选择 QwenPaw，使用 Qoder 原生模型时选择 Qoder。其余能力的支持范围两者一致，详见“能力支持范围”。

准备工作

开始前需满足以下条件：

• 已创建 Workspace，且具备创建 Agent 的权限。

• 已按管理模型配置可用的模型连接和模型。

• 本地已安装 curl。

创建 Agent

1. 登录 AgentCore 控制台，进入目标 Workspace，打开 Agent 创建 页面并选择 托管 Harness。

2. 在 基本信息 区域完成以下配置。

   配置项	配置值
   Harness	QwenPaw
   Agent 模板	不使用模板
   Agent 名称	quickstart-assistant
   模型连接	已验证可用的连接
   模型	该连接下的模型
   Token 配额	暂不启用
   描述	留空

3. 在 文件配置 区域，将以下内容填写为系统提示词。

   你是一个中文问答助手，帮助用户解答问题、整理信息和撰写文案。请用简洁、准确的中文回答；用户要求列举时，使用编号列表。

4. 在 Agent 资产配置 区域暂不添加资产。

5. 在 资源配置 区域选择实例规格，保留预填的 实例最大 Session 数 和 Session TTL，并关闭 自动扩缩容。

6. 在 网络配置 区域开启 允许默认网卡访问公网；本示例不开启 允许访问 VPC，即不接入专有网络 VPC。在 存储配置 区域不添加对象存储 OSS 挂载。

7. 单击 提交创建。进入详情页后打开 实例与 Session，等待实例和 Session 就绪后再发起对话。

通过 AG-UI 发起对话

1. 在 Agent 详情页中依次打开 外部渠道配置 和 直接访问，获取 Endpoint 与 API Key。

2. 在应用服务端设置 AGENTCORE_ENDPOINT 和 AGENTCORE_ENDPOINT_API_KEY。AGENTCORE_ENDPOINT 不包含 /ag-ui/agent 路径。

   重要

   API Key 只能保存在应用服务端，不要写入前端代码或前端配置。

   export AGENTCORE_ENDPOINT="<Endpoint>"
   export AGENTCORE_ENDPOINT_API_KEY="<API Key>"

3. 使用以下命令发起对话。

   curl --no-buffer --request POST "${AGENTCORE_ENDPOINT%/}/ag-ui/agent" \
     --header "x-api-key: ${AGENTCORE_ENDPOINT_API_KEY}" \
     --header 'Content-Type: application/json' \
     --header 'Accept: text/event-stream' \
     --data '{"threadId":"session-001","runId":"run-001","messages":[{"id":"message-001","role":"user","content":"请用三个要点介绍你的功能。"}],"state":{},"tools":[],"context":[],"forwardedProps":{}}'

判断对话结果

SSE 事件中的 TEXT_MESSAGE_CONTENT 事件，其 delta 字段为回复文本。可根据以下事件判断本次调用的状态：

续聊时保持 threadId 不变，并使用新的 runId 和消息 ID。

基本信息

文件配置

未使用模板时，直接在 文件配置 区域填写系统提示词；使用模板时，角色文件由模板提供，无需自行准备 SOUL.md 或 AGENTS.md。模板的管理方法参见管理 Agent 模板。

Agent 资产配置

在 Agent 资产配置 区域可配置以下资产：

内置 Shell 和文件工具无需额外添加。使用模板时可以额外添加 Skill，但 Skill 名称不能重复；模板或 Skill 发布新版本后，需要核对已绑定的版本。

资源配置

网络配置

网络配置 控制 Agent 对外部服务的访问能力。允许默认网卡访问公网 用于访问公网网站、下载资源或调用公网服务；允许访问 VPC 用于访问 Workspace 关联的 VPC，目标服务也需要允许访问。外部应用调用 Agent 的方式参见“外部访问”。

存储配置

启用 OSS 挂载后，Agent 可通过本地路径访问 OSS。配置挂载前需要获得相应授权。

修改配置后的生效方式

模型、提示词、Skill、Subagent、MCP 和凭证的修改支持热更新，无需重启。实例规格、镜像和挂载点的修改需要重启后生效，涉及重启的配置建议在任务结束后修改。

实例、Session 与上下文

实例是运行 Agent 的计算环境。Session（会话）是一组连续交互，具有独立 ID。上下文是 Agent 处理请求时参考的信息，包含此前的对话和工具执行结果。一个 Agent 可以运行多个实例，一个实例可以承载多个 Session；同一实例中的 Session 共享 CPU 和内存，因此提高 实例最大 Session 数 不会增加计算资源。

查看实例与 Session

在 Agent 详情页打开 实例与 Session，可查看实例状态和 Session 数，按实例 ID 或 Session ID 搜索，并查看单个 Session 的详情。创建 Agent 后，也在该页面确认实例和 Session 是否就绪。

Session 的来源与分配

Session 可从直接访问 Endpoint 调用、钉钉、飞书或企业微信渠道，以及协作实例聊天和协作实例 Task 创建；已有 Session 会继续使用原实例。启用 自动扩缩容 后，新 Session 优先分配给已就绪且未达到上限的实例，存在多个可选实例时优先选择已有 Session 更多的实例。容量不足时，平台会按配置新增实例，新 Session 在实例就绪后执行。

并发与自动扩缩容

同一 Session 同时只能处理一个请求，后续请求会排队；不同 Session 可以并发处理。启用 自动扩缩容 后，平台根据 Session 数和 实例最大 Session 数 计算所需实例数，以 最小实例数 为下限，以 最大实例数 为上限。计入容量的 Session 数包含尚未回收的 Session 和正在申请的新 Session；请求结束后，Session 仍会保留一段时间并占用容量。例如，每实例支持 5 个 Session、最小实例数 为 1、最大实例数 为 3 时：

所有实例达到上限后，新的 Session 申请会返回容量不足。新实例需要启动时间；关闭 自动扩缩容 后，平台不会自动增加实例。

空闲回收与缩容

存在请求处理或排队的 Session 不会因空闲超时而回收。Session TTL 决定请求结束后空闲 Session 的保留时间，例如 600 表示空闲 10 分钟后回收。Session 回收后不再占用容量；使用原 Session ID 再次请求时，会重新分配实例。

启用 自动扩缩容 后，平台只回收无 Session 的多余实例，并保留 最小实例数。Session 分散在多个实例时不会集中迁移，而是在 Session 回收后再缩容。TTL 较长会使 Session 保留更久、缩容更晚；TTL 较短可更快释放容量，但更可能发生实例重新分配。

上下文、历史与工作文件

对话较长时，Harness 会压缩历史上下文以腾出空间，QwenPaw 和 Qoder 分别使用各自的原生机制；压缩后可能不会保留全部原始对话内容。

原生 Session 会定期备份，并在启动时恢复。原 Session ID 可以参考已保存的历史；TTL 不决定历史保存时长，Session 回收也不会删除历史。恢复不会自动续接已中断的请求或工具操作。

每个 Session 都有独立工作目录，同一 Agent 的不同 Session 可通过 shared/ 目录共享文件。工作文件不属于对话历史备份范围，需要持久化时应通过 OSS 挂载路径保存。

直接访问

直接访问用于从应用服务端调用 Agent：服务端通过 AG-UI 协议发送请求，并将 SSE 返回的文本展示给客户端。Endpoint 与 API Key 的获取方式、调用示例和事件判断方法参见“通过 AG-UI 发起对话”和“判断对话结果”。

接入 IM 渠道

可将 Agent 接入钉钉、飞书或企业微信：

1. 在目标 IM 平台创建机器人并获取凭证。

2. 在 Agent 的 外部渠道配置 区域选择对应渠道，绑定 Endpoint 并填写凭证。

3. 保存配置后，在测试群中 @ 机器人验证对话。

   完整配置说明参见将 Agent 接入 IM 渠道。

使用团队协作

加入 Team 后，可参与聊天、任务和子任务；协作实例聊天和协作实例 Task 也会创建 Session，参见“Session 的来源与分配”。