internal/function: add user_agent provider-defined function

This function will format a User-Agent entry given a product name,
product version, and optional comment. It can be paired with the
`user_agent` argument in the `provider` and `provider_meta` blocks.

```console
% TF_ACC=1 go test -v ./internal/function/... -run=TestUserAgentFunction_
2025/12/10 15:06:44 Creating Terraform AWS Provider (SDKv2-style)...
2025/12/10 15:06:45 Initializing Terraform AWS Provider (SDKv2-style)...

--- PASS: TestUserAgentFunction_missingName (1.01s)
--- PASS: TestUserAgentFunction_basic (21.86s)
PASS
ok      github.com/hashicorp/terraform-provider-aws/internal/function   28.277s
```

Author: jar-b

.changelog/45464.txt

@@ -4,3 +4,6 @@ provider: The `provider_meta` block is now supported. The `user_agent` argument
 ```release-note:enhancement
 provider: Add `user_agent` argument
 ```
+```release-note:new-function
+user_agent
+```

internal/function/user_agent.go

@@ -0,0 +1,71 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package function
+
+import (
+	"context"
+	"strings"
+
+	"github.com/hashicorp/terraform-plugin-framework/function"
+)
+
+var _ function.Function = userAgentFunction{}
+
+func NewUserAgentFunction() function.Function {
+	return &userAgentFunction{}
+}
+
+type userAgentFunction struct{}
+
+func (f userAgentFunction) Metadata(ctx context.Context, req function.MetadataRequest, resp *function.MetadataResponse) {
+	resp.Name = "user_agent"
+}
+
+func (f userAgentFunction) Definition(ctx context.Context, req function.DefinitionRequest, resp *function.DefinitionResponse) {
+	resp.Definition = function.Definition{
+		Summary:             "user_agent Function",
+		MarkdownDescription: "Formats a User-Agent product for use with the user_agent argument in the provider or provider_meta block.",
+		Parameters: []function.Parameter{
+			function.StringParameter{
+				Name:                "product_name",
+				MarkdownDescription: "Product name.",
+			},
+			function.StringParameter{
+				Name:                "product_version",
+				MarkdownDescription: "Product version.",
+			},
+			function.StringParameter{
+				Name:                "comment",
+				MarkdownDescription: "Comment describing any additional product details.",
+			},
+		},
+		Return: function.StringReturn{},
+	}
+}
+
+func (f userAgentFunction) Run(ctx context.Context, req function.RunRequest, resp *function.RunResponse) {
+	var name, version, comment string
+
+	resp.Error = function.ConcatFuncErrors(req.Arguments.Get(ctx, &name, &version, &comment))
+	if resp.Error != nil {
+		return
+	}
+
+	if name == "" {
+		resp.Error = function.ConcatFuncErrors(resp.Error, function.NewFuncError("product_name must be set"))
+		return
+	}
+
+	var sb strings.Builder
+
+	sb.WriteString(name)
+	if version != "" {
+		sb.WriteString("/" + version)
+	}
+	if comment != "" {
+		sb.WriteString(" (" + comment + ")")
+	}
+
+	resp.Error = function.ConcatFuncErrors(resp.Result.Set(ctx, sb.String()))
+}

internal/function/user_agent_test.go

@@ -0,0 +1,79 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package function_test
+
+import (
+	"fmt"
+	"testing"
+
+	"github.com/YakDriver/regexache"
+	"github.com/hashicorp/go-version"
+	"github.com/hashicorp/terraform-plugin-testing/helper/resource"
+	"github.com/hashicorp/terraform-plugin-testing/tfversion"
+	"github.com/hashicorp/terraform-provider-aws/internal/acctest"
+)
+
+func TestUserAgentFunction_basic(t *testing.T) {
+	t.Parallel()
+
+	resource.UnitTest(t, resource.TestCase{
+		ProtoV5ProviderFactories: acctest.ProtoV5ProviderFactories,
+		TerraformVersionChecks: []tfversion.TerraformVersionCheck{
+			tfversion.SkipBelow(version.Must(version.NewVersion("1.8.0"))),
+		},
+		Steps: []resource.TestStep{
+			{
+				Config: testUserAgentFunctionConfig("test-module", "0.0.1", "test comment"),
+				Check: resource.ComposeAggregateTestCheckFunc(
+					resource.TestCheckOutput("test", "test-module/0.0.1 (test comment)"),
+				),
+			},
+			{
+				Config: testUserAgentFunctionConfig("test-module", "0.0.1", ""),
+				Check: resource.ComposeAggregateTestCheckFunc(
+					resource.TestCheckOutput("test", "test-module/0.0.1"),
+				),
+			},
+			{
+				Config: testUserAgentFunctionConfig("test-module", "", ""),
+				Check: resource.ComposeAggregateTestCheckFunc(
+					resource.TestCheckOutput("test", "test-module"),
+				),
+			},
+			{
+				Config: testUserAgentFunctionConfig("test-module", "", "test comment"),
+				Check: resource.ComposeAggregateTestCheckFunc(
+					resource.TestCheckOutput("test", "test-module (test comment)"),
+				),
+			},
+		},
+	})
+}
+
+func TestUserAgentFunction_missingName(t *testing.T) {
+	t.Parallel()
+
+	resource.UnitTest(t, resource.TestCase{
+		ProtoV5ProviderFactories: acctest.ProtoV5ProviderFactories,
+		TerraformVersionChecks: []tfversion.TerraformVersionCheck{
+			tfversion.SkipBelow(version.Must(version.NewVersion("1.8.0"))),
+		},
+		Steps: []resource.TestStep{
+			{
+				Config: testUserAgentFunctionConfig("", "", ""),
+				// The full message is broken across lines, complicating validation.
+				// Check just the start.
+				ExpectError: regexache.MustCompile("product_name must be"),
+			},
+		},
+	})
+}
+
+func testUserAgentFunctionConfig(name, version, comment string) string {
+	return fmt.Sprintf(`
+output "test" {
+  value = provider::aws::user_agent(%[1]q, %[2]q, %[3]q)
+}
+`, name, version, comment)
+}

internal/provider/framework/provider.go

@@ -425,6 +425,7 @@ func (p *frameworkProvider) Functions(_ context.Context) []func() function.Funct
 		tffunction.NewARNBuildFunction,
 		tffunction.NewARNParseFunction,
 		tffunction.NewTrimIAMRolePathFunction,
+		tffunction.NewUserAgentFunction,
 	}
 }
 

website/docs/functions/user_agent.html.markdown

@@ -0,0 +1,31 @@
+---
+subcategory: ""
+layout: "aws"
+page_title: "AWS: user_agent"
+description: |-
+  Formats a User-Agent product for use with the user_agent argument in the provider or provider_meta block..
+---
+# Function: user_agent
+
+~> Provider-defined functions are supported in Terraform 1.8 and later.
+
+Formats a User-Agent product for use with the user_agent argument in the provider or provider_meta block..
+
+## Example Usage
+
+```terraform
+# result: foo-bar
+output "example" {
+  value = provider::aws::user_agent("foo")
+}
+```
+
+## Signature
+
+```text
+user_agent(arg string) string
+```
+
+## Arguments
+
+1. `arg` (String) Example argument description.