通过凭证与 RAM 签名访问 AgentRun 数据链路

URL 结构说明

请求 URL 由以下部分组成：

凭证认证

若 Agent 运行时配置了访问凭证，需在请求头中携带对应的认证信息。AgentRun 支持多种凭证形式：

• API Key：在请求头中携带配置的 Key。例如：

  -H "X-API-Key: ********"

• JWT：需由调用方自行向 Issuer 获取 JWT。AgentRun 通过 JWKS 公钥验证 JWT 的合法性，不负责签发 JWT。

Agentrun-Authorization 请求头格式

AGENTRUN4-HMAC-SHA256 Credential=<AccessKeyId>/<date>/<region>/<product>/aliyun_v4_request,SignedHeaders=<SignedHeaders>,Signature=<Signature>

重要约定

• 签名算法标识为 AGENTRUN4-HMAC-SHA256。

• 请求体参与签名的方式为 UNSIGNED-PAYLOAD：规范化请求最后一行及请求头 x-acs-content-sha256 均为字面量 UNSIGNED-PAYLOAD，不对请求体做 SHA256 十六进制摘要。

• 授权头字段名为 Agentrun-Authorization（不是 Authorization）。

• 密钥派生使用前缀 aliyun_v4，对 AccessKey Secret 做多段 HMAC-SHA256 派生得到 SigningKey，不能直接用 AccessKey Secret 对 StringToSign 做 HMAC。

签名机制

采用 AccessKey ID 和 AccessKey Secret（及可选的 STS SecurityToken）对 HTTP/HTTPS 请求签名。服务端按相同规则重算签名并与请求中的授权信息比对，以校验调用方身份与请求完整性。

CanonicalRequest =
  HTTPRequestMethod + '\n' +
  CanonicalURI + '\n' +
  CanonicalQueryString + '\n' +
  CanonicalHeaders + '\n' +
  SignedHeaders + '\n' +
  RequestPayloadPlaceholder

host;x-acs-content-sha256;x-acs-date;x-acs-security-token

UNSIGNED-PAYLOAD

HashedCanonicalRequest = HexEncode( SHA256( CanonicalRequest ) )

StringToSign =
  SignatureAlgorithm + '\n' +
  HashedCanonicalRequest

AGENTRUN4-HMAC-SHA256
7ea06492da5221eba5297e897ce16e55f964061054b7695beedaac1145b1e259

k0 = HMAC-SHA256( key = UTF8(SIGN_PREFIX + AccessKeySecret), data = date )
k1 = HMAC-SHA256( key = k0, data = region )
k2 = HMAC-SHA256( key = k1, data = product )
SigningKey = HMAC-SHA256( key = k2, data = SIGN_PREFIX + "_request" )

Signature = HexEncode( HMAC-SHA256( key = SigningKey, data = StringToSign ) )

AGENTRUN4-HMAC-SHA256 Credential=<AccessKeyId>/<date>/<region>/<product>/aliyun_v4_request,SignedHeaders=<SignedHeaders>,Signature=<Signature>

签名代码示例

以下为 Node.js 参考实现，可用于生成 Agentrun-Authorization 及配套请求头。

const crypto = require('crypto');

const SIGN_PREFIX = 'aliyun_v4';
const ALGORITHM = 'AGENTRUN4-HMAC-SHA256';

function percentEncode(value) {
  if (value == null) return '';
  return encodeURIComponent(value).replace(/%7E/g, '~');
}

function hmacSha256(key, data) {
  const hmac = crypto.createHmac('sha256', key);
  hmac.update(data, 'utf8');
  return hmac.digest();
}

function getSigningKey(secret, product, region, date) {
  const sc = SIGN_PREFIX + secret;
  const dateKey = hmacSha256(Buffer.from(sc, 'utf8'), date);
  const regionKey = hmacSha256(dateKey, region);
  const productKey = hmacSha256(regionKey, product);
  return hmacSha256(productKey, SIGN_PREFIX + '_request');
}

function getSignedHeaders(headers) {
  const headerSet = new Set();
  for (const [key, value] of Object.entries(headers)) {
    const lowerKey = key.toLowerCase();
    if (value != null && (lowerKey.startsWith('x-acs-') || lowerKey === 'host' || lowerKey === 'content-type')) {
      headerSet.add(lowerKey);
    }
  }
  return Array.from(headerSet).sort();
}

function buildCanonicalizedResource(query) {
  if (!query || Object.keys(query).length === 0) return '';
  const parts = [];
  for (const key of Object.keys(query).sort()) {
    const value = query[key];
    if (value != null && value !== '') {
      parts.push(`${percentEncode(key)}=${percentEncode(value)}`);
    } else {
      parts.push(`${percentEncode(key)}=`);
    }
  }
  return parts.join('&');
}

function buildCanonicalizedHeaders(headers) {
  const newHeaders = {};
  const processedKeys = new Set();

  for (const [key, value] of Object.entries(headers)) {
    const lowerKey = key.toLowerCase();
    if (value != null) {
      if (!processedKeys.has(lowerKey) || lowerKey === 'host') {
        processedKeys.add(lowerKey);
        newHeaders[lowerKey] = String(value).trim();
      } else {
        newHeaders[lowerKey] = newHeaders[lowerKey] + ',' + String(value).trim();
      }
    }
  }

  const signedHeaders = getSignedHeaders(headers);
  let result = '';
  for (const h of signedHeaders) {
    result += `${h}:${newHeaders[h]}\n`;
  }
  return result;
}

/**
 * 生成 AgentRun 签名头
 *
 * @param {Object} options
 * @param {string} options.url - 请求 URL
 * @param {string} [options.method='GET'] - HTTP 方法
 * @param {string} [options.accessKeyId] - AccessKey ID
 * @param {string} [options.accessKeySecret] - AccessKey Secret
 * @param {string} [options.securityToken] - Security Token (STS)
 * @param {string} [options.region='cn-hangzhou'] - Region
 * @param {string} [options.product='agentrun'] - Product
 * @param {Buffer|Uint8Array} [options.body] - 请求体
 * @param {Date} [options.signTime] - 签名时间，默认当前 UTC
 * @returns {Object} 包含 host, x-acs-date, x-acs-content-sha256, Agentrun-Authorization 等
 */
function getAgentrunSignedHeaders(options = {}) {
  const {
    url,
    method = 'GET',
    accessKeyId = process.env.ALIBABA_CLOUD_ACCESS_KEY_ID,
    accessKeySecret = process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET,
    securityToken = process.env.ALIBABA_CLOUD_SECURITY_TOKEN,
    region = 'cn-hangzhou',
    product = 'agentrun',
    body,
    signTime,
  } = options;

  if (!accessKeyId || !accessKeySecret) {
    throw new Error('Access Key ID and Secret are required');
  }

  const parsed = new URL(url);
  const host = parsed.host;
  const pathname = parsed.pathname || '/';

  const queryParams = {};
  if (parsed.search) {
    for (const [k, v] of parsed.searchParams) {
      queryParams[k] = v;
    }
  }

  const now = signTime ? new Date(signTime) : new Date();
  const timestamp = now.toISOString().replace(/\.\d{3}Z$/, 'Z');
  const date = now.toISOString().slice(0, 10).replace(/-/g, '');

  const headers = {
    host,
    'x-acs-date': timestamp,
    'x-acs-content-sha256': 'UNSIGNED-PAYLOAD',
  };
  if (securityToken) {
    headers['x-acs-security-token'] = securityToken;
  }

  const hashPayload = 'UNSIGNED-PAYLOAD';

  const signingKey = getSigningKey(accessKeySecret, product, region, date);
  const canonicalUri = pathname || '/';
  const canonicalizedResource = buildCanonicalizedResource(queryParams);
  const canonicalizedHeaders = buildCanonicalizedHeaders(headers);
  const signedHeaders = getSignedHeaders(headers);
  const signedHeadersStr = signedHeaders.join(';');

  const stringToSignFirst =
    method.toUpperCase() +
    '\n' +
    canonicalUri +
    '\n' +
    canonicalizedResource +
    '\n' +
    canonicalizedHeaders +
    '\n' +
    signedHeadersStr +
    '\n' +
    hashPayload;

  const hashHex = crypto.createHash('sha256').update(stringToSignFirst, 'utf8').digest('hex');
  const stringToSignFinal = ALGORITHM + '\n' + hashHex;

  const signature = hmacSha256(signingKey, stringToSignFinal).toString('hex');

  const authHeader =
    `${ALGORITHM} Credential=${accessKeyId}/${date}/${region}/${product}/` +
    `${SIGN_PREFIX}_request,SignedHeaders=${signedHeadersStr},Signature=${signature}`;

  headers['Agentrun-Authorization'] = authHeader;
  return headers;
}

module.exports = { getAgentrunSignedHeaders };

const https = require('https');
const { getAgentrunSignedHeaders } = require('./agentrun-sign');

const url = 'https://12345678901234-ram.agentrun-data.cn-hangzhou.aliyuncs.com/agent-runtimes/my-agent/endpoints/Default/invocations/openai/v1/chat/completions';
const body = JSON.stringify({
  messages: [{ role: 'user', content: '你好' }],
  stream: false,
});

const signedHeaders = getAgentrunSignedHeaders({
  url,
  method: 'POST',
  accessKeyId: process.env.ALIBABA_CLOUD_ACCESS_KEY_ID,
  accessKeySecret: process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET,
  region: 'cn-hangzhou',
  product: 'agentrun',
});

const parsed = new URL(url);
const options = {
  hostname: parsed.hostname,
  path: parsed.pathname,
  method: 'POST',
  headers: {
    ...signedHeaders,
    'Content-Type': 'application/json',
    'Content-Length': Buffer.byteLength(body),
  },
};

const req = https.request(options, (res) => {
  let data = '';
  res.on('data', (chunk) => { data += chunk; });
  res.on('end', () => { console.log(JSON.parse(data)); });
});

req.write(body);
req.end();