# AgentCard定义规范

本文档定义了AgentCard的完整字段规范。AgentCard是Agent的元数据描述文件，用于向A2A中的Remote Agent、Server描述自身的能力、接口和元数据信息。  

#### 核心字段对照表

以下为AgentCard的完整字段定义，包含类型、必填性、说明及实际使用示例。  

|字段名称|类型|必填|最大长度|说明|备注|使用示例|
|:-----------------|:----------------|:-|:----|:---------------------------|:-----------------------------------------------|:---------------------------------------------------------------------------------------|
|name|string|是|64|Agent的可读名称|A2A标准字段|``` "出行助手智能体" ```|
|description|string|是|512|Agent的可读描述，帮助用户和其他Agent理解其用途|A2A标准字段，一句话描述|``` "出行助手智能体，提供路线规划、语音出行、服务伴随等服务" ```|
|agentId|string|是|64|内部Agent ID，非全局唯一，在同包名下唯一|不支持导入导出（内部存储时，采用平台的agentId）|``` "XXPHONE_TRAFFIC_AGENT" ```|
|version|string|是|32|AgentCard定义的版本号|A2A标准字段，建议遵循语义化版本|``` "1.0.0" ```|
|iconUrl|string|是|512|Agent图标的URL|A2A标准字段，建议使用 HTTPS|``` "智能体的icon地址" ```|
|capabilities|AgentCapabilities|否|-|Agent支持的A2A能力集合|包括streaming、pushNotifications、extensions 等，不约束扩展|``` {"streaming": true, "pushNotifications": false, "stateTransitionHistory": false} ```|
|defaultInputModes|string\[\]|是|-|Agent在所有技能中支持的默认输入交互模式（媒体类型）|可在单个技能中覆盖，数组元素为MIME类型|``` ["text/plain"] ```|
|defaultOutputModes|string\[\]|是|-|Agent支持的默认输出媒体类型|数组元素为MIME类型|``` ["text/plain"] ```|
|skills|AgentSkill\[\]|是|-|Agent的技能列表。|需要拓宽字段定义|``` [{"id": "travel_scene_recommend", "name": "景点推荐", ...}] ```|
|provider|AgentProvider|否|-|Agent的服务提供商信息|包含organization和url|``` {"organization": "XXPAY", "url": "https://www.XXpay.com/"} ```|
|documentationUrl|string|否|512|提供有关Agent额外文档的URL|不涉及|"" (空字符串)|
|extension|string|否|51200|扩展信息，按JSON存储，详情见ExtInfo|扩展字段，例如隐私等。IDE可考虑支持string或结构化配置|-|
|appInfo|AppInfo|是|-|应用相关信息|在此承载应用相关信息。不支持导入导出。|-|

#### 嵌套对象详细说明

supportedInterfaces

用于定义Agent支持的通信接口列表，有序排列，第一个为首选接口。  

|字段|类型|必填|最大长度|说明|
|:--------------|:-----|:-|:---|:-------------------------|
|url|string|是|512|接口的URL，生产环境必须是有效的HTTPS URL|
|protocolBinding|string|是|32|支持的协议绑定类型，核心支持: JSONRPC|
|protocolVersion|string|是|16|A2A协议版本，例如: "0.3"、"1.0"|

AgentCapabilities  

|字段|类型|必填|说明|
|:----------------|:------|:-|:-------------------------|
|streaming|boolean|可选|是否支持流式响应|
|pushNotifications|boolean|可选|是否支持异步任务更新的推送通知|
|extension|string|否|Agent支持的协议扩展列表，JSON String|
|extendedAgentCard|boolean|可选|是否支持身份验证后提供扩展的AgentCard|

AgentSkill  

|字段|类型|必填|最大长度|说明|
|:----------|:---------|:-|:---|:-----------------------|
|id|string|是|64|技能的唯一标识符|
|name|string|是|128|技能的可读名称|
|description|string|是|512|技能的详细描述|
|tags|string\[\]|是|32|描述技能能力的关键词集合|
|examples|string\[\]|否|256|此技能可以处理的示例提示或场景|
|inputModes|string\[\]|否|-|此技能支持的输入媒体类型（覆盖Agent默认值）|
|outputModes|string\[\]|否|-|此技能支持的输出媒体类型（覆盖Agent默认值）|
|extension|string|否|-|扩展信息|

AgentProvider  

|字段|类型|必填|最大长度|说明|
|:-----------|:-----|:-|:---|:-------------|
|organization|string|是|128|提供商的组织名称|
|url|string|是|512|提供商网站或相关文档的URL|

ExtInfo

新增自定义字段，用于承载业务特有信息。  

|字段名称|类型|必填|最大长度|说明|
|:------------------|:-----------------|:-|:---|:------------------------------|
|introduction|string|是|256|Agent开场白，用于用户初次交互|
|reqMetaRequired|string\[\]|否|-|Request中meta必须携带的字段列表|
|securityInfo|Object|否|-|认证信息|
|protocolVersion|string|是|-|协议版本，初始默认 1.0|
|supportedInterfaces|AgentInterface\[\]|否|-|支持的接口列表（有序），第一个是首选接口|
|developmentType|string|否|64|开发类型：NATIVE（缺省）、PROCODE、LOWCODE|

AppInfo

新增自定义字段，用于描述Agent所在的应用信息。  

|字段名称|类型|必填|最大长度|说明|
|:------------|:-----|:-|:---|:--------------------|
|deviceTypes|string|否|128|设备类型，逗号分隔。没配置则同APP类型。|
|bundleName|string|否|255|应用包名|
|moduleName|string|条件|255|模块名称|
|abilityName|string|条件|255|Ability名称|
|minAppVersion|string|否|32|最小APP版本要求|