AWS CLI Command Reference

Note:

You are viewing the documentation for an older major version of the AWS CLI (version 1). To view this page for the AWS CLI version 2, click here.

We announced the upcoming end-of-support for the AWS CLI v1. For dates, additional details, and information on how to migrate, please refer to the linked announcement. For more information see the AWS CLI version 2 installation instructions and migration guide.

[ aws . bedrock-agentcore-control ]

update-harness

Description

Operation to update a Harness.

See also: AWS API Documentation

update-harness uses document type values. Document types follow the JSON data model where valid values are: strings, numbers, booleans, null, arrays, and objects. For command input, options and nested parameters that are labeled with the type document must be provided as JSON. Shorthand syntax does not support document types.

Synopsis

  update-harness
--harness-id <value>
[--client-token <value>]
[--execution-role-arn <value>]
[--environment <value>]
[--environment-artifact <value>]
[--environment-variables <value>]
[--authorizer-configuration <value>]
[--model <value>]
[--system-prompt <value>]
[--tools <value>]
[--skills <value>]
[--allowed-tools <value>]
[--memory <value>]
[--truncation <value>]
[--max-iterations <value>]
[--max-tokens <value>]
[--timeout-seconds <value>]
[--cli-input-json <value>]
[--generate-cli-skeleton <value>]
[--debug]
[--endpoint-url <value>]
[--no-verify-ssl]
[--no-paginate]
[--output <value>]
[--query <value>]
[--profile <value>]
[--region <value>]
[--version <value>]
[--color <value>]
[--no-sign-request]
[--ca-bundle <value>]
[--cli-read-timeout <value>]
[--cli-connect-timeout <value>]
[--v2-debug]

Options

--harness-id (string)

The ID of the harness to update.

--client-token (string)

A unique, case-sensitive identifier to ensure idempotency of the request.

--execution-role-arn (string)

The ARN of the IAM role that the harness assumes when running. If not specified, the existing value is retained.

--environment (tagged union structure)

The compute environment configuration for the harness. If not specified, the existing value is retained.

Note

This is a Tagged Union structure. Only one of the following top level keys can be set: agentCoreRuntimeEnvironment.

agentCoreRuntimeEnvironment -> (structure)

The AgentCore Runtime environment configuration.

lifecycleConfiguration -> (structure)

LifecycleConfiguration lets you manage the lifecycle of runtime sessions and resources in AgentCore Runtime. This configuration helps optimize resource utilization by automatically cleaning up idle sessions and preventing long-running instances from consuming resources indefinitely.

idleRuntimeSessionTimeout -> (integer)

Timeout in seconds for idle runtime sessions. When a session remains idle for this duration, it will be automatically terminated. Default: 900 seconds (15 minutes).

maxLifetime -> (integer)

Maximum lifetime for the instance in seconds. Once reached, instances will be automatically terminated and replaced. Default: 28800 seconds (8 hours).

networkConfiguration -> (structure)

SecurityConfig for the Agent.

networkMode -> (string)

The network mode for the AgentCore Runtime.

networkModeConfig -> (structure)

The network mode configuration for the AgentCore Runtime.

securityGroups -> (list)

The security groups associated with the VPC configuration.

(string)

subnets -> (list)

The subnets associated with the VPC configuration.

(string)

filesystemConfigurations -> (list)

The filesystem configurations for the runtime environment.

(tagged union structure)

Configuration for a filesystem that can be mounted into the AgentCore Runtime.

Note

This is a Tagged Union structure. Only one of the following top level keys can be set: sessionStorage.

sessionStorage -> (structure)

Configuration for session storage. Session storage provides persistent storage that is preserved across AgentCore Runtime session invocations.

mountPath -> (string)

The mount path for the session storage filesystem inside the AgentCore Runtime. The path must be under /mnt with exactly one subdirectory level (for example, /mnt/data ).

JSON Syntax:

{
  "agentCoreRuntimeEnvironment": {
    "lifecycleConfiguration": {
      "idleRuntimeSessionTimeout": integer,
      "maxLifetime": integer
    },
    "networkConfiguration": {
      "networkMode": "PUBLIC"|"VPC",
      "networkModeConfig": {
        "securityGroups": ["string", ...],
        "subnets": ["string", ...]
      }
    },
    "filesystemConfigurations": [
      {
        "sessionStorage": {
          "mountPath": "string"
        }
      }
      ...
    ]
  }
}

--environment-artifact (structure)

The environment artifact for the harness. Use the optionalValue wrapper to set a new value, or set it to null to clear the existing configuration.

optionalValue -> (tagged union structure)

The updated environment artifact value, or null to clear the existing configuration.

Note

This is a Tagged Union structure. Only one of the following top level keys can be set: containerConfiguration.

containerConfiguration -> (structure)

Representation of a container configuration.

containerUri -> (string)

The ECR URI of the container.

Shorthand Syntax:

optionalValue={containerConfiguration={containerUri=string}}

JSON Syntax:

{
  "optionalValue": {
    "containerConfiguration": {
      "containerUri": "string"
    }
  }
}

--environment-variables (map)

Environment variables to set in the harness runtime environment. If specified, this replaces all existing environment variables. If not specified, the existing value is retained.

key -> (string)

value -> (string)

Shorthand Syntax:

KeyName1=string,KeyName2=string

JSON Syntax:

{"string": "string"
  ...}

--authorizer-configuration (structure)

Wrapper for updating an optional AuthorizerConfiguration field with PATCH semantics. When present in an update request, the authorizer configuration is replaced with optionalValue. When absent, the authorizer configuration is left unchanged. To unset, include the wrapper with optionalValue not specified.

optionalValue -> (tagged union structure)

The updated authorizer configuration value. If not specified, it will clear the current authorizer configuration of the resource.

Note

This is a Tagged Union structure. Only one of the following top level keys can be set: customJWTAuthorizer.

customJWTAuthorizer -> (structure)

The inbound JWT-based authorization, specifying how incoming requests should be authenticated.

discoveryUrl -> (string)

This URL is used to fetch OpenID Connect configuration or authorization server metadata for validating incoming tokens.

allowedAudience -> (list)

Represents individual audience values that are validated in the incoming JWT token validation process.

(string)

allowedClients -> (list)

Represents individual client IDs that are validated in the incoming JWT token validation process.

(string)

allowedScopes -> (list)

An array of scopes that are allowed to access the token.

(string)

customClaims -> (list)

An array of objects that define a custom claim validation name, value, and operation

(structure)

Defines the name of a custom claim field and rules for finding matches to authenticate its value.

inboundTokenClaimName -> (string)

The name of the custom claim field to check.

inboundTokenClaimValueType -> (string)

The data type of the claim value to check for.

  • Use STRING if you want to find an exact match to a string you define.
  • Use STRING_ARRAY if you want to fnd a match to at least one value in an array you define.

authorizingClaimMatchValue -> (structure)

Defines the value or values to match for and the relationship of the match.

claimMatchValue -> (tagged union structure)

The value or values to match for.

Note

This is a Tagged Union structure. Only one of the following top level keys can be set: matchValueString, matchValueStringList.

matchValueString -> (string)

The string value to match for.

matchValueStringList -> (list)

An array of strings to check for a match.

(string)

claimMatchOperator -> (string)

Defines the relationship between the claim field value and the value or values you’re matching for.

privateEndpoint -> (tagged union structure)

The private endpoint configuration for a gateway target. Defines how the gateway connects to private resources in your VPC.

Note

This is a Tagged Union structure. Only one of the following top level keys can be set: selfManagedLatticeResource, managedVpcResource.

selfManagedLatticeResource -> (tagged union structure)

Configuration for connecting to a private resource using a self-managed VPC Lattice resource configuration.

Note

This is a Tagged Union structure. Only one of the following top level keys can be set: resourceConfigurationIdentifier.

resourceConfigurationIdentifier -> (string)

The ARN or ID of the VPC Lattice resource configuration.

managedVpcResource -> (structure)

Configuration for connecting to a private resource using a managed VPC Lattice resource. The gateway creates and manages the VPC Lattice resources on your behalf.

vpcIdentifier -> (string)

The ID of the VPC that contains your private resource.

subnetIds -> (list)

The subnet IDs within the VPC where the VPC Lattice resource gateway is placed.

(string)

endpointIpAddressType -> (string)

The IP address type for the resource configuration endpoint.

securityGroupIds -> (list)

The security group IDs to associate with the VPC Lattice resource gateway. If not specified, the default security group for the VPC is used.

(string)

tags -> (map)

Tags to apply to the managed VPC Lattice resource gateway.

key -> (string)

value -> (string)

routingDomain -> (string)

An intermediate publicly resolvable domain used as the VPC Lattice resource configuration endpoint. Required when your private endpoint uses a domain that is not publicly resolvable.

privateEndpointOverrides -> (list)

A list of private endpoint overrides for the JWT authorizer. Each override maps a specific domain to a private endpoint, enabling secure connectivity through VPC Lattice resource configurations.

(structure)

A mapping of a specific domain to a private endpoint for secure connectivity through a VPC Lattice resource configuration.

domain -> (string)

The domain to override with a private endpoint.

privateEndpoint -> (tagged union structure)

The private endpoint configuration for the specified domain.

Note

This is a Tagged Union structure. Only one of the following top level keys can be set: selfManagedLatticeResource, managedVpcResource.

selfManagedLatticeResource -> (tagged union structure)

Configuration for connecting to a private resource using a self-managed VPC Lattice resource configuration.

Note

This is a Tagged Union structure. Only one of the following top level keys can be set: resourceConfigurationIdentifier.

resourceConfigurationIdentifier -> (string)

The ARN or ID of the VPC Lattice resource configuration.

managedVpcResource -> (structure)

Configuration for connecting to a private resource using a managed VPC Lattice resource. The gateway creates and manages the VPC Lattice resources on your behalf.

vpcIdentifier -> (string)

The ID of the VPC that contains your private resource.

subnetIds -> (list)

The subnet IDs within the VPC where the VPC Lattice resource gateway is placed.

(string)

endpointIpAddressType -> (string)

The IP address type for the resource configuration endpoint.

securityGroupIds -> (list)

The security group IDs to associate with the VPC Lattice resource gateway. If not specified, the default security group for the VPC is used.

(string)

tags -> (map)

Tags to apply to the managed VPC Lattice resource gateway.

key -> (string)

value -> (string)

routingDomain -> (string)

An intermediate publicly resolvable domain used as the VPC Lattice resource configuration endpoint. Required when your private endpoint uses a domain that is not publicly resolvable.

JSON Syntax:

{
  "optionalValue": {
    "customJWTAuthorizer": {
      "discoveryUrl": "string",
      "allowedAudience": ["string", ...],
      "allowedClients": ["string", ...],
      "allowedScopes": ["string", ...],
      "customClaims": [
        {
          "inboundTokenClaimName": "string",
          "inboundTokenClaimValueType": "STRING"|"STRING_ARRAY",
          "authorizingClaimMatchValue": {
            "claimMatchValue": {
              "matchValueString": "string",
              "matchValueStringList": ["string", ...]
            },
            "claimMatchOperator": "EQUALS"|"CONTAINS"|"CONTAINS_ANY"
          }
        }
        ...
      ],
      "privateEndpoint": {
        "selfManagedLatticeResource": {
          "resourceConfigurationIdentifier": "string"
        },
        "managedVpcResource": {
          "vpcIdentifier": "string",
          "subnetIds": ["string", ...],
          "endpointIpAddressType": "IPV4"|"IPV6",
          "securityGroupIds": ["string", ...],
          "tags": {"string": "string"
            ...},
          "routingDomain": "string"
        }
      },
      "privateEndpointOverrides": [
        {
          "domain": "string",
          "privateEndpoint": {
            "selfManagedLatticeResource": {
              "resourceConfigurationIdentifier": "string"
            },
            "managedVpcResource": {
              "vpcIdentifier": "string",
              "subnetIds": ["string", ...],
              "endpointIpAddressType": "IPV4"|"IPV6",
              "securityGroupIds": ["string", ...],
              "tags": {"string": "string"
                ...},
              "routingDomain": "string"
            }
          }
        }
        ...
      ]
    }
  }
}

--model (tagged union structure)

The model configuration for the harness. If not specified, the existing value is retained.

Note

This is a Tagged Union structure. Only one of the following top level keys can be set: bedrockModelConfig, openAiModelConfig, geminiModelConfig.

bedrockModelConfig -> (structure)

Configuration for an Amazon Bedrock model.

modelId -> (string)

The Bedrock model ID.

maxTokens -> (integer)

The maximum number of tokens to allow in the generated response per iteration.

temperature -> (float)

The temperature to set when calling the model.

topP -> (float)

The topP set when calling the model.

openAiModelConfig -> (structure)

Configuration for an OpenAI model.

modelId -> (string)

The OpenAI model ID.

apiKeyArn -> (string)

The ARN of your OpenAI API key on AgentCore Identity.

maxTokens -> (integer)

The maximum number of tokens to allow in the generated response per iteration.

temperature -> (float)

The temperature to set when calling the model.

topP -> (float)

The topP set when calling the model.

geminiModelConfig -> (structure)

Configuration for a Google Gemini model.

modelId -> (string)

The Gemini model ID.

apiKeyArn -> (string)

The ARN of your Gemini API key on AgentCore Identity.

maxTokens -> (integer)

The maximum number of tokens to allow in the generated response per iteration.

temperature -> (float)

The temperature to set when calling the model.

topP -> (float)

The topP set when calling the model.

topK -> (integer)

The topK set when calling the model.

Shorthand Syntax:

bedrockModelConfig={modelId=string,maxTokens=integer,temperature=float,topP=float},openAiModelConfig={modelId=string,apiKeyArn=string,maxTokens=integer,temperature=float,topP=float},geminiModelConfig={modelId=string,apiKeyArn=string,maxTokens=integer,temperature=float,topP=float,topK=integer}

JSON Syntax:

{
  "bedrockModelConfig": {
    "modelId": "string",
    "maxTokens": integer,
    "temperature": float,
    "topP": float
  },
  "openAiModelConfig": {
    "modelId": "string",
    "apiKeyArn": "string",
    "maxTokens": integer,
    "temperature": float,
    "topP": float
  },
  "geminiModelConfig": {
    "modelId": "string",
    "apiKeyArn": "string",
    "maxTokens": integer,
    "temperature": float,
    "topP": float,
    "topK": integer
  }
}

--system-prompt (list)

The system prompt that defines the agent’s behavior. If not specified, the existing value is retained.

(tagged union structure)

A content block in the system prompt.

Note

This is a Tagged Union structure. Only one of the following top level keys can be set: text.

text -> (string)

The text content of the system prompt block.

Shorthand Syntax:

text=string ...

JSON Syntax:

[
  {
    "text": "string"
  }
  ...
]

--tools (list)

The tools available to the agent. If specified, this replaces all existing tools. If not specified, the existing value is retained.

(structure)

A tool available to the agent loop.

type -> (string)

The type of tool.

name -> (string)

Unique name for the tool. If not provided, a name will be inferred or generated.

config -> (tagged union structure)

Tool-specific configuration.

Note

This is a Tagged Union structure. Only one of the following top level keys can be set: remoteMcp, agentCoreBrowser, agentCoreGateway, inlineFunction, agentCoreCodeInterpreter.

remoteMcp -> (structure)

Configuration for remote MCP server.

url -> (string)

URL of the MCP endpoint.

headers -> (map)

Map of key/value pairs for HTTP headers.

key -> (string)

The key of an HTTP header.

value -> (string)

The value of an HTTP header.

agentCoreBrowser -> (structure)

Configuration for AgentCore Browser.

browserArn -> (string)

If not populated, the built-in Browser ARN is used.

agentCoreGateway -> (structure)

Configuration for AgentCore Gateway.

gatewayArn -> (string)

The ARN of the desired AgentCore Gateway.

outboundAuth -> (tagged union structure)

How Loopy authenticates to this Gateway. Defaults to AWS_IAM (SigV4) if omitted.

Note

This is a Tagged Union structure. Only one of the following top level keys can be set: awsIam, none, oauth.

awsIam -> (structure)

SigV4-sign requests using the agent’s execution role.

none -> (structure)

No authentication.

oauth -> (structure)

An OAuth credential provider for gateway authentication. This structure contains the configuration for authenticating with the target endpoint using OAuth.

providerArn -> (string)

The Amazon Resource Name (ARN) of the OAuth credential provider. This ARN identifies the provider in Amazon Web Services.

scopes -> (list)

The OAuth scopes for the credential provider. These scopes define the level of access requested from the OAuth provider.

(string)

customParameters -> (map)

The custom parameters for the OAuth credential provider. These parameters provide additional configuration for the OAuth authentication process.

key -> (string)

value -> (string)

grantType -> (string)

Specifies the kind of credentials to use for authorization:

  • CLIENT_CREDENTIALS - Authorization with a client ID and secret.
  • AUTHORIZATION_CODE - Authorization with a token that is specific to an individual end user.

defaultReturnUrl -> (string)

The URL where the end user’s browser is redirected after obtaining the authorization code. Generally points to the customer’s application.

inlineFunction -> (structure)

Configuration for an inline function tool.

description -> (string)

Description of what the tool does, provided to the model.

inputSchema -> (document)

JSON Schema describing the tool’s input parameters.

agentCoreCodeInterpreter -> (structure)

Configuration for AgentCore Code Interpreter.

codeInterpreterArn -> (string)

If not populated, the built-in Code Interpreter ARN is used.

JSON Syntax:

[
  {
    "type": "remote_mcp"|"agentcore_browser"|"agentcore_gateway"|"inline_function"|"agentcore_code_interpreter",
    "name": "string",
    "config": {
      "remoteMcp": {
        "url": "string",
        "headers": {"string": "string"
          ...}
      },
      "agentCoreBrowser": {
        "browserArn": "string"
      },
      "agentCoreGateway": {
        "gatewayArn": "string",
        "outboundAuth": {
          "awsIam": {

          },
          "none": {

          },
          "oauth": {
            "providerArn": "string",
            "scopes": ["string", ...],
            "customParameters": {"string": "string"
              ...},
            "grantType": "CLIENT_CREDENTIALS"|"AUTHORIZATION_CODE",
            "defaultReturnUrl": "string"
          }
        }
      },
      "inlineFunction": {
        "description": "string",
        "inputSchema": {...}
      },
      "agentCoreCodeInterpreter": {
        "codeInterpreterArn": "string"
      }
    }
  }
  ...
]

--skills (list)

The skills available to the agent. If specified, this replaces all existing skills. If not specified, the existing value is retained.

(tagged union structure)

A skill available to the agent.

Note

This is a Tagged Union structure. Only one of the following top level keys can be set: path.

path -> (string)

The filesystem path to the skill definition.

Shorthand Syntax:

path=string ...

JSON Syntax:

[
  {
    "path": "string"
  }
  ...
]

--allowed-tools (list)

The tools that the agent is allowed to use. If specified, this replaces all existing allowed tools. If not specified, the existing value is retained.

(string)

Syntax:

"string" "string" ...

--memory (structure)

The AgentCore Memory configuration. Use the optionalValue wrapper to set a new value, or set it to null to clear the existing configuration.

optionalValue -> (tagged union structure)

The updated memory configuration value, or null to clear the existing configuration.

Note

This is a Tagged Union structure. Only one of the following top level keys can be set: agentCoreMemoryConfiguration.

agentCoreMemoryConfiguration -> (structure)

The AgentCore Memory configuration.

arn -> (string)

The ARN of the AgentCore Memory resource.

actorId -> (string)

The actor ID for memory operations.

messagesCount -> (integer)

The number of messages to retrieve from memory.

retrievalConfig -> (map)

The retrieval configuration for long-term memory, mapping namespace path templates to retrieval settings.

key -> (string)

value -> (structure)

Configuration for memory retrieval within a namespace.

topK -> (integer)

The maximum number of memory entries to retrieve.

relevanceScore -> (float)

The minimum relevance score for retrieved memories.

strategyId -> (string)

The ID of the retrieval strategy to use.

JSON Syntax:

{
  "optionalValue": {
    "agentCoreMemoryConfiguration": {
      "arn": "string",
      "actorId": "string",
      "messagesCount": integer,
      "retrievalConfig": {"string": {
            "topK": integer,
            "relevanceScore": float,
            "strategyId": "string"
          }
        ...}
    }
  }
}

--truncation (structure)

The truncation configuration for managing conversation context. If not specified, the existing value is retained.

strategy -> (string)

The truncation strategy to use.

config -> (tagged union structure)

The strategy-specific configuration.

Note

This is a Tagged Union structure. Only one of the following top level keys can be set: slidingWindow, summarization.

slidingWindow -> (structure)

Configuration for sliding window truncation.

messagesCount -> (integer)

The number of recent messages to retain in the context window.

summarization -> (structure)

Configuration for summarization-based truncation.

summaryRatio -> (float)

The ratio of content to summarize.

preserveRecentMessages -> (integer)

The number of recent messages to preserve without summarization.

summarizationSystemPrompt -> (string)

The system prompt used for generating summaries.

Shorthand Syntax:

strategy=string,config={slidingWindow={messagesCount=integer},summarization={summaryRatio=float,preserveRecentMessages=integer,summarizationSystemPrompt=string}}

JSON Syntax:

{
  "strategy": "sliding_window"|"summarization"|"none",
  "config": {
    "slidingWindow": {
      "messagesCount": integer
    },
    "summarization": {
      "summaryRatio": float,
      "preserveRecentMessages": integer,
      "summarizationSystemPrompt": "string"
    }
  }
}

--max-iterations (integer)

The maximum number of iterations the agent loop can execute per invocation. If not specified, the existing value is retained.

--max-tokens (integer)

The maximum number of tokens the agent can generate per iteration. If not specified, the existing value is retained.

--timeout-seconds (integer)

The maximum duration in seconds for the agent loop execution per invocation. If not specified, the existing value is retained.

--cli-input-json (string) Performs service operation based on the JSON string provided. The JSON string follows the format provided by --generate-cli-skeleton. If other arguments are provided on the command line, the CLI values will override the JSON-provided values. It is not possible to pass arbitrary binary values using a JSON-provided value as the string will be taken literally.

--generate-cli-skeleton (string) Prints a JSON skeleton to standard output without sending an API request. If provided with no value or the value input, prints a sample input JSON that can be used as an argument for --cli-input-json. If provided with the value output, it validates the command inputs and returns a sample output JSON for that command.

Global Options

--debug (boolean)

Turn on debug logging.

--endpoint-url (string)

Override command’s default URL with the given URL.

--no-verify-ssl (boolean)

By default, the AWS CLI uses SSL when communicating with AWS services. For each SSL connection, the AWS CLI will verify SSL certificates. This option overrides the default behavior of verifying SSL certificates.

--no-paginate (boolean)

Disable automatic pagination. If automatic pagination is disabled, the AWS CLI will only make one call, for the first page of results.

--output (string)

The formatting style for command output.

  • json
  • text
  • table

--query (string)

A JMESPath query to use in filtering the response data.

--profile (string)

Use a specific profile from your credential file.

--region (string)

The region to use. Overrides config/env settings.

--version (string)

Display the version of this tool.

--color (string)

Turn on/off color output.

  • on
  • off
  • auto

--no-sign-request (boolean)

Do not sign requests. Credentials will not be loaded if this argument is provided.

--ca-bundle (string)

The CA certificate bundle to use when verifying SSL certificates. Overrides config/env settings.

--cli-read-timeout (int)

The maximum socket read time in seconds. If the value is set to 0, the socket read will be blocking and not timeout. The default value is 60 seconds.

--cli-connect-timeout (int)

The maximum socket connect time in seconds. If the value is set to 0, the socket connect will be blocking and not timeout. The default value is 60 seconds.

--v2-debug (boolean)

Enable AWS CLI v2 migration assistance. Prints warnings if the command would face a breaking change after swapping AWS CLI v1 for AWS CLI v2 in the current environment. Prints one warning for each breaking change detected.

Output

harness -> (structure)

The updated harness.

harnessId -> (string)

The ID of the Harness.

harnessName -> (string)

The name of the Harness.

arn -> (string)

The ARN of the Harness.

status -> (string)

The status of the Harness.

executionRoleArn -> (string)

IAM role the Harness assumes when running.

createdAt -> (timestamp)

The createdAt time of the Harness.

updatedAt -> (timestamp)

The updatedAt time of the Harness.

model -> (tagged union structure)

The configuration of the default model used by the Harness.

Note

This is a Tagged Union structure. Only one of the following top level keys can be set: bedrockModelConfig, openAiModelConfig, geminiModelConfig.

bedrockModelConfig -> (structure)

Configuration for an Amazon Bedrock model.

modelId -> (string)

The Bedrock model ID.

maxTokens -> (integer)

The maximum number of tokens to allow in the generated response per iteration.

temperature -> (float)

The temperature to set when calling the model.

topP -> (float)

The topP set when calling the model.

openAiModelConfig -> (structure)

Configuration for an OpenAI model.

modelId -> (string)

The OpenAI model ID.

apiKeyArn -> (string)

The ARN of your OpenAI API key on AgentCore Identity.

maxTokens -> (integer)

The maximum number of tokens to allow in the generated response per iteration.

temperature -> (float)

The temperature to set when calling the model.

topP -> (float)

The topP set when calling the model.

geminiModelConfig -> (structure)

Configuration for a Google Gemini model.

modelId -> (string)

The Gemini model ID.

apiKeyArn -> (string)

The ARN of your Gemini API key on AgentCore Identity.

maxTokens -> (integer)

The maximum number of tokens to allow in the generated response per iteration.

temperature -> (float)

The temperature to set when calling the model.

topP -> (float)

The topP set when calling the model.

topK -> (integer)

The topK set when calling the model.

systemPrompt -> (list)

The system prompt of the Harness.

(tagged union structure)

A content block in the system prompt.

Note

This is a Tagged Union structure. Only one of the following top level keys can be set: text.

text -> (string)

The text content of the system prompt block.

tools -> (list)

The tools of the Harness.

(structure)

A tool available to the agent loop.

type -> (string)

The type of tool.

name -> (string)

Unique name for the tool. If not provided, a name will be inferred or generated.

config -> (tagged union structure)

Tool-specific configuration.

Note

This is a Tagged Union structure. Only one of the following top level keys can be set: remoteMcp, agentCoreBrowser, agentCoreGateway, inlineFunction, agentCoreCodeInterpreter.

remoteMcp -> (structure)

Configuration for remote MCP server.

url -> (string)

URL of the MCP endpoint.

headers -> (map)

Map of key/value pairs for HTTP headers.

key -> (string)

The key of an HTTP header.

value -> (string)

The value of an HTTP header.

agentCoreBrowser -> (structure)

Configuration for AgentCore Browser.

browserArn -> (string)

If not populated, the built-in Browser ARN is used.

agentCoreGateway -> (structure)

Configuration for AgentCore Gateway.

gatewayArn -> (string)

The ARN of the desired AgentCore Gateway.

outboundAuth -> (tagged union structure)

How Loopy authenticates to this Gateway. Defaults to AWS_IAM (SigV4) if omitted.

Note

This is a Tagged Union structure. Only one of the following top level keys can be set: awsIam, none, oauth.

awsIam -> (structure)

SigV4-sign requests using the agent’s execution role.

none -> (structure)

No authentication.

oauth -> (structure)

An OAuth credential provider for gateway authentication. This structure contains the configuration for authenticating with the target endpoint using OAuth.

providerArn -> (string)

The Amazon Resource Name (ARN) of the OAuth credential provider. This ARN identifies the provider in Amazon Web Services.

scopes -> (list)

The OAuth scopes for the credential provider. These scopes define the level of access requested from the OAuth provider.

(string)

customParameters -> (map)

The custom parameters for the OAuth credential provider. These parameters provide additional configuration for the OAuth authentication process.

key -> (string)

value -> (string)

grantType -> (string)

Specifies the kind of credentials to use for authorization:

  • CLIENT_CREDENTIALS - Authorization with a client ID and secret.
  • AUTHORIZATION_CODE - Authorization with a token that is specific to an individual end user.

defaultReturnUrl -> (string)

The URL where the end user’s browser is redirected after obtaining the authorization code. Generally points to the customer’s application.

inlineFunction -> (structure)

Configuration for an inline function tool.

description -> (string)

Description of what the tool does, provided to the model.

inputSchema -> (document)

JSON Schema describing the tool’s input parameters.

agentCoreCodeInterpreter -> (structure)

Configuration for AgentCore Code Interpreter.

codeInterpreterArn -> (string)

If not populated, the built-in Code Interpreter ARN is used.

skills -> (list)

The skills of the Harness.

(tagged union structure)

A skill available to the agent.

Note

This is a Tagged Union structure. Only one of the following top level keys can be set: path.

path -> (string)

The filesystem path to the skill definition.

allowedTools -> (list)

The allowed tools of the Harness. All tools are allowed by default.

(string)

truncation -> (structure)

Configuration for truncating model context.

strategy -> (string)

The truncation strategy to use.

config -> (tagged union structure)

The strategy-specific configuration.

Note

This is a Tagged Union structure. Only one of the following top level keys can be set: slidingWindow, summarization.

slidingWindow -> (structure)

Configuration for sliding window truncation.

messagesCount -> (integer)

The number of recent messages to retain in the context window.

summarization -> (structure)

Configuration for summarization-based truncation.

summaryRatio -> (float)

The ratio of content to summarize.

preserveRecentMessages -> (integer)

The number of recent messages to preserve without summarization.

summarizationSystemPrompt -> (string)

The system prompt used for generating summaries.

environment -> (tagged union structure)

The compute environment on which the Harness runs.

Note

This is a Tagged Union structure. Only one of the following top level keys can be set: agentCoreRuntimeEnvironment.

agentCoreRuntimeEnvironment -> (structure)

The AgentCore Runtime environment configuration.

agentRuntimeArn -> (string)

The ARN of the underlying AgentCore Runtime.

agentRuntimeName -> (string)

The name of the underlying AgentCore Runtime.

agentRuntimeId -> (string)

The ID of the underlying AgentCore Runtime.

lifecycleConfiguration -> (structure)

LifecycleConfiguration lets you manage the lifecycle of runtime sessions and resources in AgentCore Runtime. This configuration helps optimize resource utilization by automatically cleaning up idle sessions and preventing long-running instances from consuming resources indefinitely.

idleRuntimeSessionTimeout -> (integer)

Timeout in seconds for idle runtime sessions. When a session remains idle for this duration, it will be automatically terminated. Default: 900 seconds (15 minutes).

maxLifetime -> (integer)

Maximum lifetime for the instance in seconds. Once reached, instances will be automatically terminated and replaced. Default: 28800 seconds (8 hours).

networkConfiguration -> (structure)

SecurityConfig for the Agent.

networkMode -> (string)

The network mode for the AgentCore Runtime.

networkModeConfig -> (structure)

The network mode configuration for the AgentCore Runtime.

securityGroups -> (list)

The security groups associated with the VPC configuration.

(string)

subnets -> (list)

The subnets associated with the VPC configuration.

(string)

filesystemConfigurations -> (list)

The filesystem configurations for the runtime environment.

(tagged union structure)

Configuration for a filesystem that can be mounted into the AgentCore Runtime.

Note

This is a Tagged Union structure. Only one of the following top level keys can be set: sessionStorage.

sessionStorage -> (structure)

Configuration for session storage. Session storage provides persistent storage that is preserved across AgentCore Runtime session invocations.

mountPath -> (string)

The mount path for the session storage filesystem inside the AgentCore Runtime. The path must be under /mnt with exactly one subdirectory level (for example, /mnt/data ).

environmentArtifact -> (tagged union structure)

The environment artifact (e.g., container) in which the Harness operates.

Note

This is a Tagged Union structure. Only one of the following top level keys can be set: containerConfiguration.

containerConfiguration -> (structure)

Representation of a container configuration.

containerUri -> (string)

The ECR URI of the container.

environmentVariables -> (map)

Environment variables exposed in the environment in which the Harness operates.

key -> (string)

value -> (string)

authorizerConfiguration -> (tagged union structure)

Represents inbound authorization configuration options used to authenticate incoming requests.

Note

This is a Tagged Union structure. Only one of the following top level keys can be set: customJWTAuthorizer.

customJWTAuthorizer -> (structure)

The inbound JWT-based authorization, specifying how incoming requests should be authenticated.

discoveryUrl -> (string)

This URL is used to fetch OpenID Connect configuration or authorization server metadata for validating incoming tokens.

allowedAudience -> (list)

Represents individual audience values that are validated in the incoming JWT token validation process.

(string)

allowedClients -> (list)

Represents individual client IDs that are validated in the incoming JWT token validation process.

(string)

allowedScopes -> (list)

An array of scopes that are allowed to access the token.

(string)

customClaims -> (list)

An array of objects that define a custom claim validation name, value, and operation

(structure)

Defines the name of a custom claim field and rules for finding matches to authenticate its value.

inboundTokenClaimName -> (string)

The name of the custom claim field to check.

inboundTokenClaimValueType -> (string)

The data type of the claim value to check for.

  • Use STRING if you want to find an exact match to a string you define.
  • Use STRING_ARRAY if you want to fnd a match to at least one value in an array you define.

authorizingClaimMatchValue -> (structure)

Defines the value or values to match for and the relationship of the match.

claimMatchValue -> (tagged union structure)

The value or values to match for.

Note

This is a Tagged Union structure. Only one of the following top level keys can be set: matchValueString, matchValueStringList.

matchValueString -> (string)

The string value to match for.

matchValueStringList -> (list)

An array of strings to check for a match.

(string)

claimMatchOperator -> (string)

Defines the relationship between the claim field value and the value or values you’re matching for.

privateEndpoint -> (tagged union structure)

The private endpoint configuration for a gateway target. Defines how the gateway connects to private resources in your VPC.

Note

This is a Tagged Union structure. Only one of the following top level keys can be set: selfManagedLatticeResource, managedVpcResource.

selfManagedLatticeResource -> (tagged union structure)

Configuration for connecting to a private resource using a self-managed VPC Lattice resource configuration.

Note

This is a Tagged Union structure. Only one of the following top level keys can be set: resourceConfigurationIdentifier.

resourceConfigurationIdentifier -> (string)

The ARN or ID of the VPC Lattice resource configuration.

managedVpcResource -> (structure)

Configuration for connecting to a private resource using a managed VPC Lattice resource. The gateway creates and manages the VPC Lattice resources on your behalf.

vpcIdentifier -> (string)

The ID of the VPC that contains your private resource.

subnetIds -> (list)

The subnet IDs within the VPC where the VPC Lattice resource gateway is placed.

(string)

endpointIpAddressType -> (string)

The IP address type for the resource configuration endpoint.

securityGroupIds -> (list)

The security group IDs to associate with the VPC Lattice resource gateway. If not specified, the default security group for the VPC is used.

(string)

tags -> (map)

Tags to apply to the managed VPC Lattice resource gateway.

key -> (string)

value -> (string)

routingDomain -> (string)

An intermediate publicly resolvable domain used as the VPC Lattice resource configuration endpoint. Required when your private endpoint uses a domain that is not publicly resolvable.

privateEndpointOverrides -> (list)

A list of private endpoint overrides for the JWT authorizer. Each override maps a specific domain to a private endpoint, enabling secure connectivity through VPC Lattice resource configurations.

(structure)

A mapping of a specific domain to a private endpoint for secure connectivity through a VPC Lattice resource configuration.

domain -> (string)

The domain to override with a private endpoint.

privateEndpoint -> (tagged union structure)

The private endpoint configuration for the specified domain.

Note

This is a Tagged Union structure. Only one of the following top level keys can be set: selfManagedLatticeResource, managedVpcResource.

selfManagedLatticeResource -> (tagged union structure)

Configuration for connecting to a private resource using a self-managed VPC Lattice resource configuration.

Note

This is a Tagged Union structure. Only one of the following top level keys can be set: resourceConfigurationIdentifier.

resourceConfigurationIdentifier -> (string)

The ARN or ID of the VPC Lattice resource configuration.

managedVpcResource -> (structure)

Configuration for connecting to a private resource using a managed VPC Lattice resource. The gateway creates and manages the VPC Lattice resources on your behalf.

vpcIdentifier -> (string)

The ID of the VPC that contains your private resource.

subnetIds -> (list)

The subnet IDs within the VPC where the VPC Lattice resource gateway is placed.

(string)

endpointIpAddressType -> (string)

The IP address type for the resource configuration endpoint.

securityGroupIds -> (list)

The security group IDs to associate with the VPC Lattice resource gateway. If not specified, the default security group for the VPC is used.

(string)

tags -> (map)

Tags to apply to the managed VPC Lattice resource gateway.

key -> (string)

value -> (string)

routingDomain -> (string)

An intermediate publicly resolvable domain used as the VPC Lattice resource configuration endpoint. Required when your private endpoint uses a domain that is not publicly resolvable.

memory -> (tagged union structure)

AgentCore Memory instance configuration for short and long term memory.

Note

This is a Tagged Union structure. Only one of the following top level keys can be set: agentCoreMemoryConfiguration.

agentCoreMemoryConfiguration -> (structure)

The AgentCore Memory configuration.

arn -> (string)

The ARN of the AgentCore Memory resource.

actorId -> (string)

The actor ID for memory operations.

messagesCount -> (integer)

The number of messages to retrieve from memory.

retrievalConfig -> (map)

The retrieval configuration for long-term memory, mapping namespace path templates to retrieval settings.

key -> (string)

value -> (structure)

Configuration for memory retrieval within a namespace.

topK -> (integer)

The maximum number of memory entries to retrieve.

relevanceScore -> (float)

The minimum relevance score for retrieved memories.

strategyId -> (string)

The ID of the retrieval strategy to use.

maxIterations -> (integer)

The maximum number of iterations in the agent loop allowed before exiting per invocation.

maxTokens -> (integer)

The maximum number of tokens allowed before exiting per invocation.

timeoutSeconds -> (integer)

The maximum duration per invocation.

failureReason -> (string)

Reason why create or update operations fail.