# Manage workload identities with AgentCore Identity
Manage agent identities

Agent identities in AgentCore Identity are implemented as workload identities with specialized attributes that enable agent-specific capabilities. This approach follows established industry patterns where workloads have granular properties that indicate their specific type and purpose. Unlike traditional service accounts that are tied to specific infrastructure, agent identities are designed to be environment-agnostic and can support multiple authentication credentials simultaneously. The AgentCore Identity directory acts as a centralized registry and management system for all agent identities. For information about workload identity limits, see [AgentCore Identity Service Quotas](bedrock-agentcore-limits.md#identity-service-limits).

**Topics**
+ [

# Understanding workload identities
](understanding-agent-identities.md)
+ [

# Understanding the agent identity directory
](agent-identity-directory.md)
+ [

# Create and manage workload identities
](creating-agent-identities.md)

# Understanding workload identities
Understanding identities

Workload identities represent the digital identity of your agents within the AWS environment. They serve as a stable anchor point that persists across different deployment environments and authentication schemes, allowing agents to maintain consistent identity whether they’re using IAM roles for AWS resource access, OAuth2 tokens for external service integration, or API keys for third-party tool access. The identity system abstracts the complexity of managing multiple credential types while providing a unified interface for authentication and authorization operations.

Workload identities integrate seamlessly with the broader AgentCore Identity framework, including the token vault for secure credential storage (see [Secure credential storage](key-features-and-benefits.md#secure-credential-storage) ), Resource credential providers for external service access (see [Configure credential provider](resource-providers.md) ), and the AgentCore Identity directory for centralized management. For more information about the directory, see [Understanding the agent identity directory](agent-identity-directory.md).

**Topics**
+ [

## How workload identities are created
](#workload-identity-creation)

## How workload identities are created


Workload identities are created automatically in several scenarios and can also be created manually when needed. These identities are used to obtain workload access tokens that authorize agent access to credentials. For details about how workload identities are used in the authentication flow, see [Get workload access token](get-workload-access-token.md).

 **Automatic creation by Runtime and Gateway** 
+ When you deploy an agent using AgentCore Runtime, a workload identity is automatically created and associated with your agent
+ AgentCore Gateway also creates workload identities automatically for agents deployed through the gateway service
+ These automatically created identities are managed by the service and include the necessary settings for your deployment environment
+ The workload identity ARN is returned in the deployment response and can be used for IAM policies and access control

 **Manual creation for custom deployments** 
+ For agents not hosted by Runtime or Gateway (such as self-hosted or hybrid deployments), you can manually create workload identities
+ Use the [CreateWorkloadIdentity API](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CreateWorkloadIdentity.html) or AWS CLI to create identities for custom agent deployments
+ Manual creation gives you control over the identity name and metadata
+ This approach is ideal when you need specific identity names or are integrating with existing identity management systems

 **When to use each approach** 
+ Use automatic creation when deploying through AgentCore Runtime or Gateway for simplified setup
+ Use manual creation when you need specific identity names or are deploying agents in non-standard environments
+ Manual creation is also useful for testing scenarios or when you need multiple identities for the same agent in different environments

Workload identities are used to obtain workload access tokens that authorize agent access to credentials. For details about how workload identities are used in the authentication flow, see [Get workload access token](get-workload-access-token.md).

Once you have created workload identities, you can use them to control access to credential providers. For information about implementing fine-grained access control, see [Scope down access to credential providers by workload identity](scope-credential-provider-access.md).

# Understanding the agent identity directory
Agent identity directory

The agent identity directory is a centralized collection of all workload identities within your AWS account. It serves as the authoritative registry for managing and organizing agent identities, providing a unified view of all identities whether they were created automatically by AgentCore Runtime and Gateway or manually through the AWS CLI and SDK. For information about creating workload identities, see [Create and manage workload identities](creating-agent-identities.md).

**Topics**
+ [

## Directory concepts and structure
](#directory-concepts)
+ [

## Directory management best practices
](#directory-management-best-practices)
+ [

## Listing and viewing directory contents
](#listing-directory-contents)
+ [

## Directory access control and permissions
](#directory-access-control)

## Directory concepts and structure


Understanding the fundamental concepts and organizational structure of the agent identity directory helps you effectively manage workload identities at scale.

 **Key characteristics** 
+  **Single directory per account** – Each AWS account has exactly one agent identity directory
+  **Automatic creation** – The directory is automatically created when the first workload identity is created in your account
+  **Centralized management** – All workload identities, regardless of how they were created, are stored in this directory
+  **Cross-service visibility** – The directory provides visibility into identities created by Runtime, Gateway, and manual processes

 **Directory structure** 

```
arn:aws:bedrock-agentcore:region:account-id:workload-identity-directory/default
├── workload-identity/runtime-created-agent-1
├── workload-identity/runtime-created-agent-2
├── workload-identity/gateway-created-agent-1
├── workload-identity/manually-created-agent-1
└── workload-identity/manually-created-agent-2
```

## Directory management best practices


Following established best practices for directory management helps maintain organization, security, and operational efficiency as your workload identity usage grows.

 **Naming conventions** 
+ Use descriptive names that indicate the agent’s purpose (such as "customer-support-agent", "data-analysis-agent")
+ Include environment indicators for multi-environment deployments (such as "prod-chatbot", "dev-chatbot")
+ Consider team or project prefixes for large organizations (such as "marketing-content-agent")

 **Organization strategies** 
+ Regularly audit your directory to identify unused or obsolete workload identities
+ Document the purpose and ownership of each workload identity
+ Implement consistent tagging strategies for workload identities when available. For more information, see [Tagging AgentCore Identity resources](identity-tagging.md).
+ Monitor directory growth and establish governance processes for identity creation

 **Security considerations** 
+ Regularly review IAM policies that grant access to the directory
+ Use least-privilege principles when granting directory access
+ Monitor directory access through AWS CloudTrail logs
+ Implement automated alerts for unauthorized directory modifications

## Listing and viewing directory contents


You can view all workload identities in your directory using the AWS CLI:

 **List all workload identities** 

```
aws bedrock-agentcore-control list-workload-identities
```

This command returns information about all workload identities in your account, including:
+ Workload identity names and ARNs
+ Creation timestamps
+ Associated metadata
+ Creation source (Runtime, Gateway, or manual)

 **Example output** 

```
{
  "workloadIdentities": [
    {
      "workloadIdentityArn": "arn:aws:bedrock-agentcore:us-east-1:123456789012:workload-identity-directory/default/workload-identity/my-runtime-agent",
      "workloadIdentityName": "my-runtime-agent",
      "createdAt": "2024-01-15T10:30:00Z",
      "createdBy": "AgentCore Runtime"
    },
    {
      "workloadIdentityArn": "arn:aws:bedrock-agentcore:us-east-1:123456789012:workload-identity-directory/default/workload-identity/my-custom-agent",
      "workloadIdentityName": "my-custom-agent",
      "createdAt": "2024-01-16T14:20:00Z",
      "createdBy": "Manual"
    }
  ]
}
```

 **Get details about a specific workload identity** 

```
aws bedrock-agentcore-control get-workload-identity \
    --workload-identity-name my-agent-name
```

## Directory access control and permissions


The agent identity directory integrates with IAM to provide fine-grained access control over workload identities and their associated resources. For information about using workload identities to control access to credential providers, see [Scope down access to credential providers by workload identity](scope-credential-provider-access.md).

 **Directory-level permissions** 
+  **List permissions** – Control who can view the directory contents
+  **Create permissions** – Control who can create new workload identities
+  **Read permissions** – Control who can view specific workload identity details
+  **Delete permissions** – Control who can remove workload identities

 **Example IAM policy for directory access** 

```
{
"Version": "2012-10-17",		 	 	 
  "Statement": [
    {
      "Sid": "ListWorkloadIdentities",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:ListWorkloadIdentities"
      ],
      "Resource": [
        "arn:aws:bedrock-agentcore:*:*:workload-identity-directory/default"
      ]
    },
    {
      "Sid": "ManageSpecificWorkloadIdentity",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:GetWorkloadIdentity",
        "bedrock-agentcore:CreateWorkloadIdentity",
        "bedrock-agentcore:DeleteWorkloadIdentity"
      ],
      "Resource": [
        "arn:aws:bedrock-agentcore:*:*:workload-identity-directory/default/workload-identity/my-agent-*"
      ]
    }
  ]
}
```

# Create and manage workload identities
Create identities

You can create agent identities using several methods, including the AWS CLI and the AgentCore SDK, depending on your workflow and integration requirements. AgentCore Identity provides multiple interfaces for identity creation including command-line tools for automation and scripting and programmatic APIs for integration with existing systems. Each creation method supports the full range of identity properties while providing appropriate interfaces for different use cases and user preferences.

**Topics**
+ [

## Manage identities with AWS CLI
](#cli-creation)
+ [

## Create identities with the AgentCore SDK
](#sdk-creation)

## Manage identities with AWS CLI


The AWS CLI provides a straightforward way to create and delete agent identities.

 **Create an identity** 

The following command creates a workload identity named *my-agent*.

```
aws bedrock-agentcore-control create-workload-identity \
    --name "my-agent"
```

 **List all identities** 

The following command lists all workload identities in your account.

```
aws bedrock-agentcore-control list-workload-identities
```

 **Delete an identity** 

The following command deletes the workload identity named *my-agent*.

```
aws bedrock-agentcore-control delete-workload-identity \
    --name "my-agent"
```

## Create identities with the AgentCore SDK


The AgentCore SDK provides support for creating workload identities in Python.

 **Python example** 

The following Python code creates a workload identity using the AgentCore SDK.

```
from bedrock_agentcore.services.identity import IdentityClient

# Initialize the client
identity_client = IdentityClient("us-east-1")

# Create a new workload identity for agent
response = identity_client.create_workload_identity(name='my-python-agent')
agentArn = response['workloadIdentityArn']

print(f"Created agent identity with ARN: {agentArn}")
```