企业官网建设流程全解析

AWS Provider 数据源 aws_bedrockagent_agent_versions 完全指南：查询 Amazon Bedrock Agent 的版本列表

【免费下载链接】terraform-provider-awsThe AWS Provider enables Terraform to manage AWS resources.项目地址: https://gitcode.com/GitHub_Trending/te/terraform-provider-aws

导读

aws_bedrockagent_agent_versions是 terraform-provider-aws 提供的一个 Terraform 数据源（Data Source），用于读取 AWS Agents for Amazon Bedrock（Bedrock Agent）下全部已发布的 Agent 版本（Agent Versions）信息。本文以该数据源的官方文档为核心，结合仓库内 数据源实现、验收测试 与 Agent 资源文档 的源码证据，系统讲解其参数、导出属性、底层 API 调用链与真实使用场景，帮助你用 Terraform 对 Bedrock Agent 的版本生命周期进行可编程的观测与管理。

一、数据源概览：它能做什么

Bedrock Agent 是 Amazon Bedrock 的智能体服务，允许开发者构建可调用工具、知识库和基础模型（Foundation Model）的自动化 Agent。Agent 在迭代过程中会通过“准备（Prepare）”操作生成不可变的版本快照——例如默认草稿版本DRAFT以及每次准备后递增的数字版本（如1、2……），这些版本可以被 Alias 稳定引用，供外部应用调用。

aws_bedrockagent_agent_versions数据源正是为了只读地列出某个 Agent 的全部版本及每个版本的元数据而设计，典型应用场景包括：

• 在 Terraform 配置中获取 Agent 当前所有版本，用于条件判断、资源计数或与其他资源联动；
• 审计版本创建时间、更新时间和描述，追踪 Agent 的演进历史；
• 结合aws_bedrockagent_agent_alias等资源，实现"为新版本自动创建 Alias"之类的编排逻辑；
• 查看每个版本关联的 Guardrail（护栏）配置，确认安全策略是否随版本生效。

它不对 AWS 资源做任何创建或修改，仅执行读取操作，是典型的只读型数据源。

二、前置条件：先有一个 Bedrock Agent

要使用该数据源，你首先需要通过aws_bedrockagent_agent资源创建一个 Agent。数据源通过必填参数agent_id定位目标 Agent。一个最小可用的 Agent 资源配置如下（摘自 Agent 资源官方文档 中的 Basic Usage 示例）：

data "aws_caller_identity" "current" {} data "aws_partition" "current" {} data "aws_region" "current" {} data "aws_iam_policy_document" "example_agent_trust" { statement { actions = ["sts:AssumeRole"] principals { identifiers = ["bedrock.amazonaws.com"] type = "Service" } condition { test = "StringEquals" values = [data.aws_caller_identity.current.account_id] variable = "aws:SourceAccount" } condition { test = "ArnLike" values = ["arn:${data.aws_partition.current.partition}:bedrock:${data.aws_region.current.region}:${data.aws_caller_identity.current.account_id}:agent/*"] variable = "AWS:SourceArn" } } } data "aws_iam_policy_document" "example_agent_permissions" { statement { actions = ["bedrock:InvokeModel"] resources = [ "arn:${data.aws_partition.current.partition}:bedrock:${data.aws_region.current.region}::foundation-model/anthropic.claude-v2", ] } } resource "aws_iam_role" "example" { assume_role_policy = data.aws_iam_policy_document.example_agent_trust.json name_prefix = "AmazonBedrockExecutionRoleForAgents_" } resource "aws_iam_role_policy" "example" { policy = data.aws_iam_policy_document.example_agent_permissions.json role = aws_iam_role.example.id } resource "aws_bedrockagent_agent" "example" { agent_name = "my-agent-name" agent_resource_role_arn = aws_iam_role.example.arn idle_session_ttl_in_seconds = 500 instruction = "You are a friendly assistant who helps answer questions." foundation_model = "anthropic.claude-v2" }

关于 Agent 版本，有一个关键概念需要理解：在 agent.go 的agentResource实现中，prepare_agent参数（默认true）控制创建/更新后是否自动执行PrepareAgentAPI。从 waitAgentVersioned 的等待逻辑可以看到，Agent 会经历VERSIONING（版本化中）状态并收敛到PREPARED状态；而agent_version作为该资源的计算属性（Computed），保存了 Agent 当前所处的版本号。也就是说，版本是 Agent 经过 Prepare 流程后的产物，每次 Prepare 都会产生一个新的版本条目，这正是本数据源要枚举的对象。

三、基本用法（Example Usage）

原文档给出的数据源用法非常简洁，只要求指定agent_id：

data "aws_bedrockagent_agent_versions" "test" { agent_id = aws_bedrockagent_agent.test.agent_id }

其中agent_id直接取自同配置中aws_bedrockagent_agent资源导出的agent_id属性，从而在创建 Agent 后自动列举其全部版本。

在真实的验收测试中，这个用法会被放到完整的可执行配置里。下面是从 agent_versions_data_source_test.go 提取的测试配置骨架，展示了 Agent 资源与数据源如何联动：

resource "aws_bedrockagent_agent" "test" { agent_name = "test-agent" agent_resource_role_arn = aws_iam_role.test_agent.arn description = "basic claude" idle_session_ttl_in_seconds = 500 instruction = file("${path.module}/test-fixtures/instruction.txt") foundation_model = "anthropic.claude-v2" } data "aws_bedrockagent_agent_versions" "test" { agent_id = aws_bedrockagent_agent.test.agent_id }

测试中的instruction通过file()函数读取仓库内 internal/service/bedrockagent/test-fixtures/instruction.txt 的提示词文件。这段配置同时证明了数据源与 Agent 资源之间通过agent_id建立依赖关系的标准写法。

四、参数说明（Argument Reference）

数据源支持以下参数：

关于region参数，从数据源模型可以印证其底层实现：在 agent_versions_data_source.go 中，数据源结构体agentVersionsDataSourceModel内嵌了framework.WithRegionModel，这使得数据源天然支持区域级配置，并在读取时通过d.Meta().BedrockAgentClient(ctx)获取对应区域的 Bedrock Agent 客户端。

五、导出属性说明（Attribute Reference）

除参数本身外，数据源导出以下属性：

5.1 顶层属性

5.2 Agent Version Summaries 块

列表agent_version_summaries中的每个对象包含以下属性：

5.3 Guardrail Configuration 块

guardrail_configuration嵌套块包含：

注：原文档中该块写作GuardrailConfiguration，实际 Terraform 配置中以小写蛇形命名guardrail_configuration引用。

六、源码级实现原理：数据源如何工作

要深入理解该数据源，可以阅读其完整实现 internal/service/bedrockagent/agent_versions_data_source.go。它基于 Terraform Plugin Framework 实现（区别于旧的 SDKv2 风格资源），核心流程如下：

6.1 Schema 定义

在Schema()方法中（agent_versions_data_source.go#L32-L82）：

• agent_id被声明为Required的StringAttribute；
• agent_version_summaries被声明为ListNestedBlock，其中agent_status使用了fwtypes.StringEnum[awstypes.AgentStatus]类型，即 AWS SDK 的AgentStatus枚举，确保状态值严格匹配 AWS 定义；
• created_at与updated_at使用timetypes.RFC3339类型，保证时间属性以 RFC 3339 字符串形式在 Terraform 状态中呈现。

6.2 Read 流程：分页拉取全部版本

在Read()方法中（agent_versions_data_source.go#L84-L118）：

1. 通过d.Meta().BedrockAgentClient(ctx)获取 Bedrock Agent 的 AWS SDK Go v2 客户端；
2. 从配置中读取agent_id，构造bedrockagent.ListAgentVersionsInput{AgentId: ...}；
3. 使用 SDK 提供的bedrockagent.NewListAgentVersionsPaginator分页迭代器逐页调用ListAgentVersionsAPI，将每一页返回的AgentVersionSummaries追加到结果切片中——这意味着即使某个 Agent 拥有大量版本，数据源也会自动遍历所有分页，返回完整列表；
4. 通过框架工具flex.Flatten将 AWS SDK 的输出结构扁平化为 Terraform 状态模型，写入resp.State。

因此，从调用链看，该数据源本质上是对 AWSListAgentVersionsAPI 的完整封装，天然处理了分页、类型转换和状态持久化。

6.3 与 Guardrail 的关系

guardrail_configuration来源于每个版本快照中保存的 Guardrail 引用。在 agent.go 中，Agent 资源本身也接受可选的guardrail_configuration块（guardrail_identifier+guardrail_version，最多 1 个），创建 Agent 时会随CreateAgent一并提交。数据源只是将各版本快照中保存的 Guardrail 信息原样回显，便于审计"某个版本究竟应用了哪个护栏策略"。

七、测试验证：如何确认数据源行为

仓库为数据源提供了完整的验收测试 agent_versions_data_source_test.go，其中TestAccBedrockAgentVersionsDataSource_basic（第 15-40 行）验证了核心行为：

• 创建测试 Agent（使用anthropic.claude-v2基础模型和basic claude描述）；
• 声明数据源并绑定agent_id；
• 断言数据源的agent_id与 Agent 资源的agent_id一致（TestCheckResourceAttrPair）；
• 断言agent_version_summaries.#（列表长度）非空、agent_version_summaries.0.%非空、agent_version_summaries.0.agent_name与agent_version_summaries.0.agent_version均已设置。

这段测试展示了如何在 Terraform 配置层面验证一个数据源：先创建被依赖的资源，再声明数据源，最后用属性断言确认输出。如果你在自己的 Terraform 项目中引用该数据源，也可以仿照这一模式对返回的版本列表进行断言，例如：

output "agent_latest_version" { value = data.aws_bedrockagent_agent_versions.test.agent_version_summaries }

八、实战：完整可运行示例

综合以上内容，下面是一个端到端可运行的完整示例——创建 Agent、列出其版本，并输出每个版本的元数据与 Guardrail 信息：

# 1. 创建 Agent（依赖 IAM 角色，此处省略角色声明，参见上文 Basic Usage） resource "aws_bedrockagent_agent" "my_agent" { agent_name = "customer-support-agent" agent_resource_role_arn = aws_iam_role.example.arn instruction = "You are a helpful customer support assistant." foundation_model = "anthropic.claude-v2" prepare_agent = true # 默认 true：创建后立即 Prepare，从而生成 DRAFT 与首个版本 } # 2. 列出该 Agent 的全部版本 data "aws_bedrockagent_agent_versions" "all" { agent_id = aws_bedrockagent_agent.my_agent.agent_id # region = "us-east-1" # 可选：跨区域读取时指定 } # 3. 输出版本摘要 output "agent_versions" { description = "Agent 的全部版本摘要" value = [ for v in data.aws_bedrockagent_agent_versions.all.agent_version_summaries : { version = v.agent_version status = v.agent_status created_at = v.created_at updated_at = v.updated_at description = v.description guardrail_id = try(v.guardrail_configuration[0].guardrail_identifier, null) guardrail_ver = try(v.guardrail_configuration[0].guardrail_version, null) } ] }

运行terraform plan/terraform apply后，agent_versions输出将呈现该 Agent 从草稿版本到最新数字版本的全部演进历史，便于你进一步驱动 Alias 切换、触发下游流程或进行合规审计。

九、使用注意事项与小结

1. 只读语义：该数据源仅执行读取，不会修改 Agent 或其版本，可安全地在plan阶段反复求值。
2. 版本产生依赖 Prepare：只有执行过PrepareAgent（对应资源prepare_agent = true）的 Agent 才会产生可枚举的版本条目；新创建但未准备的 Agent，agent_version_summaries可能为空。
3. 区域一致性：Agent 与数据源的region必须指向同一区域（除非显式配置跨区域读取），否则ListAgentVersions会因找不到 Agent 而报错。
4. 状态语义：agent_status描述的是 Agent 整体状态而非版本状态，解读结果时需结合 Agent 的生命周期状态机理解。

通过本文的讲解，你可以将该数据源无缝接入自己的 Terraform 工作流，用基础设施即代码的方式观测 Bedrock Agent 的版本演进。若需进一步了解 Agent 资源的全部配置能力（包括memory_configuration、prompt_override_configuration、超时与导入等），可继续查阅 Agent 资源文档；深入源码可阅读 数据源实现、数据源测试 与 Agent 资源实现。

【免费下载链接】terraform-provider-awsThe AWS Provider enables Terraform to manage AWS resources.项目地址: https://gitcode.com/GitHub_Trending/te/terraform-provider-aws