English | 简体中文
Alibaba Cloud Agent Identity CLI for Python
A command-line tool for managing AI Agent identities on Alibaba Cloud. It provides capabilities to create RAM Roles, Permission Policies, and Workload Identities.
Requirements
- Python >= 3.8
Installation
pip install agent-identity-cli
For local development:
git clone <repository-url>
cd agent-identity-python-cli
pip install -e .
Configuration
Set the following environment variables before using the CLI:
# Required: Alibaba Cloud credentials
export ALIBABA_CLOUD_ACCESS_KEY_ID=<your_access_key_id>
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=<your_access_key_secret>
# Optional: Agent Identity region, defaults to cn-beijing
export AGENT_IDENTITY_REGION_ID=cn-beijing
# Optional: Custom endpoint for Agent Identity API (for pre-release testing)
export AGENT_IDENTITY_ENDPOINT=agentidentity.cn-beijing.aliyuncs.com
CLI Usage
create-role
Create a RAM Role with Agent Identity trust policy and permission policy.
# Basic usage: auto-generate role name, trust policy allows all workload identities
agent-identity-cli create-role
# Specify role name
agent-identity-cli create-role --role-name my-agent-role
# Specify workload identity name (for trust policy)
agent-identity-cli create-role --workload-identity-name my-identity
# Full parameters
agent-identity-cli create-role \
--role-name my-agent-role \
--workload-identity-name my-identity
Parameters:
| Parameter | Required | Description |
|---|---|---|
--role-name |
No | Role name. Defaults to AgentIdentityRole-{workload-identity-name} or AgentIdentityRole-{random} |
--workload-identity-name |
No | Workload Identity name for building trust policy. If not specified, allows all workload identities |
Output:
- Role ARN
- Role Name
- Policy Name
- Trust Policy (JSON)
- Permission Policy (JSON)
create-workload-identity
Create a Workload Identity with optional automatic Role creation.
# Auto-create associated Role
agent-identity-cli create-workload-identity --workload-identity-name my-identity
# Use existing Role
agent-identity-cli create-workload-identity \
--workload-identity-name my-identity \
--associated-role-arn acs:ram::123456789:role/my-role
# Full parameters
agent-identity-cli create-workload-identity \
--workload-identity-name my-identity \
--associated-role-arn acs:ram::123456789:role/my-role \
--identity-provider-name my-idp \
--allowed-resource-oauth2-return-urls "https://example.com/callback,https://app.example.com/oauth"
Parameters:
| Parameter | Required | Description |
|---|---|---|
--workload-identity-name |
Yes | Workload Identity name |
--associated-role-arn |
No | Associated Role ARN. If not specified, auto-creates a new Role |
--identity-provider-name |
No | Identity Provider name |
--allowed-resource-oauth2-return-urls |
No | OAuth2 callback URL list, comma-separated |
Output:
- Workload Identity ARN
- Workload Identity Name
- Role information (if a new Role was created)
Python SDK Usage
The CLI can also be used as a Python module for integration with other tools.
create_role
from agent_identity_cli import create_role, CreateRoleConfig
# Create Role (trust policy allows all workload identities)
result = create_role(CreateRoleConfig())
print(f"Role ARN: {result.role_arn}")
print(f"Trust Policy: {result.trust_policy}")
print(f"Permission Policy: {result.permission_policy}")
# Specify workload identity name
result = create_role(CreateRoleConfig(
role_name="my-agent-role",
workload_identity_name="my-identity",
))
print(f"Role ARN: {result.role_arn}")
create_workload_identity
from agent_identity_cli import create_workload_identity, CreateWorkloadIdentityConfig
# Auto-create Role
result = create_workload_identity(CreateWorkloadIdentityConfig(
workload_identity_name="my-identity",
))
print(f"Workload Identity ARN: {result.workload_identity_arn}")
print(f"Role ARN: {result.role_result.role_arn}")
# Use existing Role
result = create_workload_identity(CreateWorkloadIdentityConfig(
workload_identity_name="my-identity",
associated_role_arn="acs:ram::123456789:role/my-role",
))
Data Models
CreateRoleConfig:
| Field | Type | Required | Description |
|---|---|---|---|
role_name |
str | No | Role name, auto-generated if not specified |
workload_identity_name |
str | No | Workload Identity name for trust policy |
CreateRoleResult:
| Field | Type | Description |
|---|---|---|
role_arn |
str | Created Role ARN |
role_name |
str | Created Role name |
trust_policy |
dict | Trust policy content |
policy_name |
str | Created permission policy name |
permission_policy |
dict | Permission policy content |
CreateWorkloadIdentityConfig:
| Field | Type | Required | Description |
|---|---|---|---|
workload_identity_name |
str | Yes | Workload Identity name |
associated_role_arn |
str | No | Associated Role ARN |
identity_provider_name |
str | No | Identity Provider name |
allowed_resource_oauth2_return_urls |
List[str] | No | OAuth2 callback URL list |
CreateWorkloadIdentityResult:
| Field | Type | Description |
|---|---|---|
workload_identity_arn |
str | Created Workload Identity ARN |
workload_identity_name |
str | Created Workload Identity name |
role_result |
CreateRoleResult | Role information (if a new Role was created) |
Policy Formats
Trust Policy
{
"Version": "1",
"Statement": [{
"Effect": "Allow",
"Principal": {
"Service": "workload.agentidentity.aliyuncs.com"
},
"Action": ["sts:AssumeRole", "sts:SetContext"],
"Condition": {
"StringEquals": {
"sts:RequestContext/agentidentity:WorkloadIdentityArn":
"acs:agentidentity:{regionId}:{accountId}:workloadidentitydirectory/default/workloadidentity/{name}"
}
}
}]
}
- If
--workload-identity-nameis not specified, theConditionblock is omitted, allowing all Workload Identities.
Permission Policy
{
"Version": "1",
"Statement": [
{
"Effect": "Allow",
"Action": ["agentidentitydata:GetResourceOAuth2Token"],
"Resource": ["acs:agentidentity:{regionId}:{accountId}:workloadidentitydirectory/default/workloadidentity/{name}"]
},
{
"Effect": "Allow",
"Action": ["agentidentitydata:GetResourceAPIKey"],
"Resource": ["acs:agentidentity:{regionId}:{accountId}:workloadidentitydirectory/default/workloadidentity/{name}"]
}
]
}
License
Copyright (c) 2009-present, Alibaba Cloud All rights reserved.
Metadata
Release files for agent-identity-cli 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agent_identity_cli-0.1.1.tar.gz | 12.9 kB | Without provenance | Details for agent_identity_cli-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agent_identity_cli-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for agent_identity_cli-0.1.1-py3-none-any.whl |
Total release size: 28.1 kB
Release files / agent_identity_cli-0.1.1.tar.gz
| Download URL | agent_identity_cli-0.1.1.tar.gz |
|---|---|
| Size | 12.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e453cb942e3e465d54e57980c5ce81a6021400d95e92a6cd8e2218a3b24ed93f
|
|
BLAKE2b-256 checksum How to use checksums |
449a0acb970cb6dfc97ff3dd76b52076270c759039816ab71202402f36921eca
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/4.0.2 CPython/3.11.2
|
Release files / agent_identity_cli-0.1.1-py3-none-any.whl
| Download URL | agent_identity_cli-0.1.1-py3-none-any.whl |
|---|---|
| Size | 15.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9ccb72ac2faf9dd50c015fec7911097587addea7dd3fa4d13fa8405aaee47985
|
|
BLAKE2b-256 checksum How to use checksums |
86e2372645deb3a8fb9a30714e25b3e7e27060b70788f6faf254ef59ecd3cf31
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/4.0.2 CPython/3.11.2
|
Security for agent-identity-cli 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.