获取 Effective Config

GET /api/v1/forward/identities/{identity_id}/templates/{template_id}/effective 返回 Template 基线叠加 Identity Config 后的有效配置。响应面向运行时执行，不返回 enabled 或 op 等 Forward DSL 字段。

请求头

Header	是否必填	说明
Authorization	是	`Bearer <PAT 或 SAT>`

路径参数

参数	类型	是否必填	说明
identity_id	string	是	Forward Identity ID。
template_id	string	是	Forward Template ID。

示例请求

curl -s -X GET 'https://api.qoder.com/api/v1/forward/identities/idn_019eabc123/templates/tmpl_support/effective' \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"

示例响应

HTTP 200 OK

{
  "type": "effective_spec",
  "id": "config_123",
  "identity_id": "idn_019eabc123",
  "template_id": "tmpl_support",
  "agent_effective_hash": "sha256:...",
  "session_effective_hash": "sha256:...",
  "effective_hash": "sha256:...",
  "agent": {
    "model": "ultimate",
    "system": "You are a support assistant.\nPrefer CRM data when answering.",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "configs": [
          {
            "name": "Read",
            "enabled": true
          },
          {
            "name": "Grep",
            "enabled": true
          },
          {
            "name": "WebSearch",
            "enabled": false
          }
        ]
      }
    ],
    "mcp_servers": [],
    "skills": []
  },
  "session": {
    "environment_id": "env_support",
    "environment_variables": {
      "BASE_MODE": "identity",
      "USER_MODE": "enabled"
    },
    "vault_ids": [
      "vault_019f18f2761b"
    ],
    "resources": [
      {
        "type": "file",
        "file_id": "file_019eXXXX"
      },
      {
        "type": "github_repository",
        "url": "https://github.com/acme/support-agent",
        "mount_path": "/data/workspace/support-agent"
      }
    ]
  }
}

响应字段

字段	类型	说明
type	string	固定为 `effective_spec`。
agent_effective_hash	string	Agent 部分编译结果 hash。
session_effective_hash	string	Session 部分编译结果 hash。
effective_hash	string	完整有效配置 hash。
`agent`	object	编译后的 Agent 配置，详见 Agent 结构及下方字段说明。
session	object	编译后的 Session 默认配置。
session.environment_variables	object\|string	Template 与 Identity Config 合并后的最终环境变量。

Agent 配置结构

agent 的字段结构如下。

字段	类型	结构与说明
name / description	string	有效 Agent 配置中存在时返回的名称、描述；可能省略。
`model`	string \| object	模型 ID 字符串，或包含 `id` 及可选 `effort`、`speed`、`context_window` 的对象，见 Model。
max_tool_rounds	integer	从 Template 继承的单次 Turn 工具调用轮数上限。
system	string	已按 `replace` / `append` 编译的最终提示词，不再包含 `mode`、`content` 对象。
tools	array	Agent tool，包括 Tool config 和 Permission policy；Identity 的 `tools`、`toolsets` 覆盖均合入该数组。
mcp_servers	array	每项包含 `name`、`type`、`url`，结构见创建 Template — MCP servers。
skills	array	Skill binding，包含 `type`、`skill_id` 和可选 `version`。
metadata	object	Template 的 Agent metadata 与 `identity_config.agent_metadata` 合并后的结果。
`multiagent`	object \| null	Multiagent 配置，可包含 `{"type":"advisor","model":"ultimate"}`；Advisor 的 `model` 为字符串。配置入口见 Multiagent。

读取或提交原始覆盖对象时，请参考Identity Config 对象，其中 system、tools、mcp_servers、skills 等字段的形态与本响应不同。

错误

HTTP	Type	Code	触发条件
400	`invalid_request_error`	-	Effective Config 无法编译。
404	`not_found_error`	-	Identity 或 Template 不存在。
422	`invalid_request_error`	-	运行时配置校验失败。
401	`authentication_error`	`authentication_required`	PAT 或 SAT 无效或已过期。

备注

Identity Config 按字段级合并规则覆盖 Template 基线。
没有 Identity Config 时按空覆盖层处理。
响应不返回 managed_tool_config 等 Forward 覆盖 DSL；该结果不应直接作为 Upsert Identity Config 的请求体。
默认 Memory Store 注入由创建 Session 流程处理。

获取 Effective Config

请求头

路径参数

示例请求

示例响应

响应字段

Agent 配置结构

错误

备注

相关

获取 Identity Config

创建 Session

​请求头

​路径参数

​示例请求

​示例响应

​响应字段

​Agent 配置结构

​错误

​备注

​相关

获取 Identity Config

创建 Session

请求头

路径参数

示例请求

示例响应

响应字段

Agent 配置结构

错误

备注

相关