diff --git a/01-tutorials/10-Agent-Registry/01-advanced/kiro/kiro-power-publisher-workflow/README.md b/01-tutorials/10-Agent-Registry/01-advanced/kiro/kiro-power-publisher-workflow/README.md new file mode 100644 index 000000000..268cabad0 --- /dev/null +++ b/01-tutorials/10-Agent-Registry/01-advanced/kiro/kiro-power-publisher-workflow/README.md @@ -0,0 +1,170 @@ +# AWS Agent Registry Kiro Power — Publisher Workflow + +## Overview + +Kiro Powers bundle MCP tools, steering files, and hooks into a single install, giving your agents specialized knowledge without overwhelming them with context. Learn more in the [Kiro Powers Documentation](https://kiro.dev/docs/powers/). + +This Kiro Power enables the **publisher persona** to create, manage, and submit agent/MCP records to the AWS Agent Registry. + +> Publisher workflow assumes a registry already exists (created by an admin). + +### Tutorial Details + +| Information | Details | +|:--------------------|:------------------------------------------------------------------------| +| Tutorial type | Workflow | +| Persona | Publisher | +| Power type | Knowledge (steering only, no MCP tools) | +| Components | `POWER.md`, Steering file with workflow guidance and code snippets | +| Registry operations | Create, List, Submit, Delete registry records (MCP and A2A) | +| Example complexity | Intermediate | +| SDK used | boto3 | + +### What a Power Includes + +- `POWER.md`: The entry point steering file acts as an onboarding manual for the Kiro agent, defining available tools and usage context. It also defines the set of APIs available and includes troubleshooting guidelines. +- `Steering`: Automates tasks and workflow-specific guidance, along with reference documentation and example code snippets for the power to execute. This is a Knowledge power, so it only has instructions. + +These two files are packaged together and loaded dynamically as per the user query. + +### Publisher Workflow Architecture + +
+ +
+ +### Key Features + +* Publisher persona operations for AWS Agent Registry +* Create and manage MCP server records +* Create and manage A2A agent card records +* Submit records for admin approval +* Workflow guidance via Kiro steering files + +--- + +## Activate the Power + +Install this power directly in Kiro using the GitHub URL below: + +[Publisher Kiro Power for AWS Agent Registry on Github](https://github.com/awslabs/agentcore-samples/tree/main/01-tutorials/10-Agent-Registry/01-advanced/kiro/kiro-power-publisher-workflow/aws-agent-registry) + +In Kiro, open the Powers panel, select "Add Custom Power -> Import Power from Github", and paste the link above. + +
+ +
+ +
+ +
+ +
+ +
+ +--- + +## Prerequisites + +### 1. AWS CLI installed + +```bash +aws --version +# Expected: aws-cli/2.x.x ... +``` + +[Install AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html) + +--- + +### 2. boto3 installed + +```bash +pip install boto3 +``` + +--- + +### 3. AWS Identity configured with publisher persona permissions + +Your AWS identity needs permission to carry out registry operations. Use whichever method matches your setup: + +Option A — named profile: +```bash +aws configure --profile +``` + +Option B — IAM user access keys (environment variables): +```bash +export AWS_ACCESS_KEY_ID=your_access_key +export AWS_SECRET_ACCESS_KEY=your_secret_key +export AWS_DEFAULT_REGION=your_region +``` + +Option C — IAM role — credentials are picked up automatically + +Verify your identity resolves correctly: +```bash +aws sts get-caller-identity +# Expected: returns AccountId, Arn, UserId +``` + +--- + +### 4. Publisher persona policy + +For carrying out AWS Agent Registry operations for publisher workflow, create an IAM role with the following policy: + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "RegistryPublisherPermission", + "Effect": "Allow", + "Action": [ + "bedrock-agentcore:ListRegistries", + "bedrock-agentcore:GetRegistry", + "bedrock-agentcore:CreateRegistryRecord", + "bedrock-agentcore:ListRegistryRecords", + "bedrock-agentcore:GetRegistryRecord", + "bedrock-agentcore:DeleteRegistryRecord", + "bedrock-agentcore:UpdateRegistryRecord", + "bedrock-agentcore:SubmitRegistryRecordForApproval" + ], + "Resource": ["*"] + } + ] +} +``` + +> Note: Publishers cannot `CreateRegistry`, `DeleteRegistry`, or approve/reject records — those are admin-only operations. + +--- + +### 5. IAM trust policy to assume the publisher role + +To assume the publisher IAM role, your IAM user must be granted `sts:AssumeRole` permission, and the target role's trust policy must allow your user as a principal. Refer to the AWS documentation on [how to configure trust policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user.html) and [how to assume a role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html) for setup instructions. + +--- + +## Next Steps + +Once prerequisites are met, you are now ready to use **AWS Agent Registry** Kiro Power for the publisher workflow. + +--- + +## Sample Prompts + +> Tip: If you are in a single Kiro IDE session, you don't have to mention the registry name every time — Kiro remembers it from context. + +1. "List all registries in my account in the us-west-2 region" +2. "Show me the list of records in registry ``" +3. "Create a new MCP server record in registry `` for my ``" +4. "Create an A2A agent card record for my `` in registry ``" +5. "Show all records in `PENDING_APPROVAL` state" +6. "Submit all records in `DRAFT` status for approval in registry ``" +7. "Show me the details of record ``" +8. "Update the description of record `` in registry ``" +9. "Delete all records in registry ``" diff --git a/01-tutorials/10-Agent-Registry/01-advanced/kiro/kiro-power-publisher-workflow/aws-agent-registry/POWER.md b/01-tutorials/10-Agent-Registry/01-advanced/kiro/kiro-power-publisher-workflow/aws-agent-registry/POWER.md new file mode 100644 index 000000000..7b3bf3ebf --- /dev/null +++ b/01-tutorials/10-Agent-Registry/01-advanced/kiro/kiro-power-publisher-workflow/aws-agent-registry/POWER.md @@ -0,0 +1,67 @@ +--- +name: "AWS Agent Registry Kiro Power" +displayName: "AWS Agent Registry for Publisher workflow" +description: "Publish and discover agents and tools in AWS Agent Registry — create MCP and A2A records, submit for approval" +keywords: ["agentcore", "bedrock", "registry", "boto3", "python", "agent", "mcp", "a2a"] +author: "anantmu" +--- + +# AWS Agent Registry + +## Overview + +AWS Agent Registry is a service that provides a central catalog to govern and control access to AI agents and tools across an AWS organization. + +This power covers **publisher persona operations** — creating and managing registry records (MCP and A2A protocols), submitting them for approval, and searching the catalog. Admin operations (create/delete registry, approve records) are out of scope here. + +Record status flow: `DRAFT` → `PENDING_APPROVAL` → `APPROVED` + + +## Files in This Power + +``` +aws-agent-registry/ +├── POWER.md +└── steering/ + └── publisher-workflow.md ← step-by-step publisher workflow +``` + +IAM setup and boto3 venv configuration are handled as prerequisites separately. + +## Available Steering Files + +- **publisher-workflow** — end-to-end publisher workflow (assumes registry and boto3 venvs already set up) + +## AWS Agent Registry — Publisher APIs + +| API | Description | +|-----|-------------| +| `ListRegistries` | List registries visible to the publisher | +| `GetRegistry` | Get details of a specific registry | +| `CreateRegistryRecord` | Publish an A2A or MCP record to a registry | +| `GetRegistryRecord` | Get details of a specific record | +| `ListRegistryRecords` | List all records in a registry | +| `UpdateRegistryRecord` | Update an existing record (resets status to DRAFT) | +| `DeleteRegistryRecord` | Delete a record you own | +| `SubmitRegistryRecordForApproval` | Move a DRAFT record to PENDING_APPROVAL | + + +## Notes + +- Publisher **cannot** `CreateRegistry`, `DeleteRegistry`, `UpdateRegistry`, or `UpdateRegistryRecordStatus` (approve/reject) — those are admin-only. +- Record status flow: `DRAFT` → `PENDING_APPROVAL` → `APPROVED` +- Updating a record resets its status back to `DRAFT` — must re-submit for approval. + +## Troubleshooting + +**`NoCredentialsError`** — run `aws configure` or set `AWS_PROFILE`. + +**`ResourceNotFoundException`** — registry or record ID is wrong; use `list_registries()` or `list_registry_records()` to get valid IDs. + +**`ServiceQuotaExceededException`** — account has hit the 5-registry limit; ask an admin to delete unused registries. + +**Search returns nothing** — records must be `APPROVED` and the OpenSearch index needs ~30s after approval to update. + +**Name validation error** — record names must match `[a-zA-Z][a-zA-Z0-9_]{0,63}` — no hyphens. + +**`update_registry_record` resets status** — any field update moves the record back to `DRAFT`; re-submit for approval after updating. diff --git a/01-tutorials/10-Agent-Registry/01-advanced/kiro/kiro-power-publisher-workflow/aws-agent-registry/steering/publisher_workflow.md b/01-tutorials/10-Agent-Registry/01-advanced/kiro/kiro-power-publisher-workflow/aws-agent-registry/steering/publisher_workflow.md new file mode 100644 index 000000000..d0ab6a600 --- /dev/null +++ b/01-tutorials/10-Agent-Registry/01-advanced/kiro/kiro-power-publisher-workflow/aws-agent-registry/steering/publisher_workflow.md @@ -0,0 +1,329 @@ +# AWS Agent Registry Publisher Workflow + +Below are the sample code snippets to carry out the operations for AWS Agent Registry for the publisher persona. Generate necessary python scripts, including a `utils.py` where necessary, to execute the below operations if the API operation is too long. + +--- + +## 1. Assume publisher_persona role + +```python +import boto3 +import json +import time +import utils +import os +from botocore.exceptions import ClientError + +AWS_REGION = os.environ.get("AWS_DEFAULT_REGION", "") + +# Auto-detect account ID from current credentials +sts = boto3.client("sts", region_name=AWS_REGION) +ACCOUNT_ID = sts.get_caller_identity()["Account"] +CALLER_ARN = sts.get_caller_identity()["Arn"] + +PUBLISHER_ROLE_ARN = f"arn:aws:iam::{ACCOUNT_ID}:role/publisher_persona" + +print(f"Account: {PUBLISHER_ROLE_ARN}") + +# Assume the Admin role +creds = utils.assume_role( + role_arn=PUBLISHER_ROLE_ARN, + session_name="publisher_session", +) +session = boto3.Session( + aws_access_key_id=creds["AccessKeyId"], + aws_secret_access_key=creds["SecretAccessKey"], + aws_session_token=creds["SessionToken"], + region_name=AWS_REGION, +) + + +``` + +## 2. List Registries + +Create or update src/list_registries.py + +```python +registries = cp_client.list_registries() +print(f"Publisher can see {len(registries.get('registries', []))} registries:\n") +for reg in registries.get("registries", []): + utils.pp(reg) +``` + +--- + +## 3. Publish MCP Record to Registry + +Create or update src/create_registry_record_mcp.py + +Define the MCP server and tools schema, then create the registry record. + +```python +mcp_server_schema = json.dumps({ + "name": "io.novacorp/payment-processing-server", + "description": "A payment processing MCP server for handling transactions, refunds, and payment status queries", + "version": "1.0.0", + "title": "Payment Processing Server", + "packages": [ + { + "registryType": "npm", + "identifier": "@novacorp/payment-processing-mcp", + "version": "1.0.0", + "registryBaseUrl": "https://registry.npmjs.org", + "runtimeHint": "npx", + "transport": {"type": "stdio"}, + } + ], +}) + +mcp_tool_schema = json.dumps({ + "tools": [ + { + "name": "process_payment", + "description": "Process a new payment transaction for a given amount and currency", + "inputSchema": { + "type": "object", + "properties": { + "amount": {"type": "number", "description": "Payment amount"}, + "currency": {"type": "string", "description": "ISO 4217 currency code (e.g. USD, EUR)"}, + "customer_id": {"type": "string", "description": "Unique customer identifier"}, + "payment_method": { + "type": "string", + "description": "Payment method type", + "enum": ["credit_card", "debit_card", "bank_transfer", "digital_wallet"], + }, + "description": {"type": "string", "description": "Optional payment description"}, + }, + "required": ["amount", "currency", "customer_id", "payment_method"], + }, + }, + { + "name": "get_payment_status", + "description": "Retrieve the current status of a payment by transaction ID", + "inputSchema": { + "type": "object", + "properties": { + "transaction_id": {"type": "string", "description": "Unique transaction identifier"}, + }, + "required": ["transaction_id"], + }, + }, + { + "name": "process_refund", + "description": "Initiate a full or partial refund for a completed transaction", + "inputSchema": { + "type": "object", + "properties": { + "transaction_id": {"type": "string", "description": "Original transaction ID to refund"}, + "amount": {"type": "number", "description": "Refund amount (omit for full refund)"}, + "reason": {"type": "string", "description": "Reason for the refund"}, + }, + "required": ["transaction_id", "reason"], + }, + }, + ] +}) +``` + +```python +MCP_RECORD_ID = None +try: + mcp_resp = cp_client.create_registry_record( + registryId=REGISTRY_ID, + name="mcp_payment_processing_server", + description="MCP server for processing payments, refunds, and transaction queries", + descriptorType="MCP", + descriptors={ + "mcp": { + "server": { + "schemaVersion": "2025-12-11", + "inlineContent": mcp_server_schema, + }, + "tools": { + "inlineContent": mcp_tool_schema, + }, + } + }, + recordVersion="1.0", + ) + MCP_RECORD_ID = mcp_resp["recordArn"].split("/")[-1] + print(f"Created MCP record: {MCP_RECORD_ID}") + record = utils.wait_for_record_ready(cp_client, REGISTRY_ID, MCP_RECORD_ID) + print(f"Status: {record.get('status', 'UNKNOWN')}") + +except ClientError as e: + if e.response["Error"]["Code"] == "ConflictException": + print("Record 'mcp_payment_processing_server' already exists — looking it up...") + records = cp_client.list_registry_records(registryId=REGISTRY_ID) + for rec in records.get("registryRecords", []): + if rec["name"] == "mcp_payment_processing_server": + MCP_RECORD_ID = rec["registryRecordId"] + break + print(f" Using existing record: {MCP_RECORD_ID}") + else: + raise + +print(f"\nMCP_RECORD_ID = {MCP_RECORD_ID}") +``` + +--- + +## 4. Publish Agent Card to Registry + +Create or update src/create_registry_record_a2a.py + +Fetch the agent card and pass it as `inlineContent` in the descriptors. + +```python +a2a_agent_card = json.dumps({ + "protocolVersion": "0.3.0", + "name": "Payment Processing Agent", + "description": "Handles payment transactions, refunds, and billing inquiries", + "url": "https://example.com/agents/payment", + "version": "1.0.0", + "capabilities": {"streaming": True}, + "defaultInputModes": ["text"], + "defaultOutputModes": ["text"], + "preferredTransport": "JSONRPC", + "skills": [ + {"id": "payment_processing", "name": "Payment Processing", "description": "Process payments", "tags": []}, + {"id": "refund_handling", "name": "Refund Handling", "description": "Handle refunds", "tags": []}, + {"id": "billing_inquiry", "name": "Billing Inquiry", "description": "Answer billing questions", "tags": []}, + ], +}) +``` + +```python +REGISTRY_ID = "" # Replace with your registry ID + +resp2 = cp_client.create_registry_record( + registryId=REGISTRY_ID, + name=AGENT_NAME, + descriptorType="A2A", + recordVersion="1.0", + description="Test agent", + descriptors={ + "a2a": { + "agentCard": { + "schemaVersion": "0.3", + "inlineContent": a2a_agent_card, + } + } + }, +) + +A2A_RECORD_ID = resp2["recordArn"].split("/")[-1] +print(f"Creating A2A registry record: {A2A_RECORD_ID}") + +record = utils.wait_for_record_ready(cp_client, REGISTRY_ID, A2A_RECORD_ID) +print(f"\nName: {record['name']} | Status: {record['status']}") +``` + +--- + +## 5. List Registry Records + +Create or update src/list_registry_records.py + +```python +all_records = [] +resp = cp_client.list_registry_records(registryId=REGISTRY_ID) +all_records.extend(resp.get("registryRecords", [])) +while resp.get("nextToken"): + resp = cp_client.list_registry_records(registryId=REGISTRY_ID, nextToken=resp["nextToken"]) + all_records.extend(resp.get("registryRecords", [])) + +print(f"Found {len(all_records)} record(s) in registry {REGISTRY_ID}\n") +print(f"{'#':<4} {'Name':<35} {'Record ID':<20} {'Status'}") +print("-" * 85) +for i, r in enumerate(all_records, 1): + print(f"{i:<4} {r.get('name','N/A'):<35} {r.get('recordId','N/A'):<20} {r.get('status','N/A')}") +``` + +--- + +## 6. Submit for Approval + +Create or update src/submit_registry_record_for_approval.py + +```python +draft_resp = cp_client.list_registry_records( + registryId=REGISTRY_ID, + status="DRAFT", +) +draft_records = draft_resp.get("registryRecords", []) +print(f"Found {len(draft_records)} DRAFT records\n") + +for rec in draft_records: + record_id = rec["recordId"] + try: + submit_resp = cp_client.submit_registry_record_for_approval( + registryId=REGISTRY_ID, + recordId=record_id, + ) + print(f"Submitted: {rec['name']} ({rec['descriptorType']}) — {record_id}") + utils.wait_for_record_ready(cp_client, REGISTRY_ID, record_id) + except ClientError as e: + error_code = e.response["Error"]["Code"] + error_msg = e.response["Error"].get("Message", "") + print(f"Failed: {rec['name']} ({record_id}) — {error_code}: {error_msg}") + print() +``` + +--- + +## 7. Deleting Records + +### Option A: Delete records by status + +Create or update src/delete_registry_record.py + +```python +STATUS_TO_DELETE = "CREATE_FAILED" +targets = [r for r in all_records if r.get("status") == STATUS_TO_DELETE] +print(f"{len(targets)} record(s) with status '{STATUS_TO_DELETE}'\n") +for r in targets: + print(f" {r.get('name')} — {r.get('recordId')}") +for r in targets: + try: + cp_client.delete_registry_record(registryId=REGISTRY_ID, recordId=r["recordId"]) + print(f" Deleted: {r['name']} ({r['recordId']})") + except Exception as e: + print(f" FAILED: {r['name']} ({r['recordId']}) — {e}") +``` + +### Option B: Delete specific record IDs + +Create or update src/delete_registry_record.py + +```python +IDS_TO_DELETE = [ + "DWEXC7BNKJzq", + "GRtJFOsueLll", +] +targets = [r for r in all_records if r.get("recordId") in IDS_TO_DELETE] +print(f"{len(targets)} record(s) matched\n") +for r in targets: + print(f" {r.get('name')} — {r.get('recordId')}") +for r in targets: + try: + cp_client.delete_registry_record(registryId=REGISTRY_ID, recordId=r["recordId"]) + print(f" Deleted: {r['name']} ({r['recordId']})") + except Exception as e: + print(f" FAILED: {r['name']} ({r['recordId']}) — {e}") +``` + +### Option C: Delete all records + +Create or update src/delete_registry_record.py + +```python +print(f"This will delete ALL {len(all_records)} record(s) in registry {REGISTRY_ID}\n") +for r in all_records: + try: + cp_client.delete_registry_record(registryId=REGISTRY_ID, recordId=r["recordId"]) + print(f" Deleted: {r['name']} ({r['recordId']})") + except Exception as e: + print(f" FAILED: {r['name']} ({r['recordId']}) — {e}") +``` diff --git a/01-tutorials/10-Agent-Registry/01-advanced/kiro/kiro-power-publisher-workflow/images/activate-kiro-power.png b/01-tutorials/10-Agent-Registry/01-advanced/kiro/kiro-power-publisher-workflow/images/activate-kiro-power.png new file mode 100644 index 000000000..b804dad03 Binary files /dev/null and b/01-tutorials/10-Agent-Registry/01-advanced/kiro/kiro-power-publisher-workflow/images/activate-kiro-power.png differ diff --git a/01-tutorials/10-Agent-Registry/01-advanced/kiro/kiro-power-publisher-workflow/images/aws-agent-registry-power.png b/01-tutorials/10-Agent-Registry/01-advanced/kiro/kiro-power-publisher-workflow/images/aws-agent-registry-power.png new file mode 100644 index 000000000..fbc6d542e Binary files /dev/null and b/01-tutorials/10-Agent-Registry/01-advanced/kiro/kiro-power-publisher-workflow/images/aws-agent-registry-power.png differ diff --git a/01-tutorials/10-Agent-Registry/01-advanced/kiro/kiro-power-publisher-workflow/images/import-from-github.png b/01-tutorials/10-Agent-Registry/01-advanced/kiro/kiro-power-publisher-workflow/images/import-from-github.png new file mode 100644 index 000000000..ba742c54f Binary files /dev/null and b/01-tutorials/10-Agent-Registry/01-advanced/kiro/kiro-power-publisher-workflow/images/import-from-github.png differ diff --git a/01-tutorials/10-Agent-Registry/01-advanced/kiro/kiro-power-publisher-workflow/images/publisher-workflow.png b/01-tutorials/10-Agent-Registry/01-advanced/kiro/kiro-power-publisher-workflow/images/publisher-workflow.png new file mode 100644 index 000000000..b5fa7759b Binary files /dev/null and b/01-tutorials/10-Agent-Registry/01-advanced/kiro/kiro-power-publisher-workflow/images/publisher-workflow.png differ diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md index c3cd74c52..0d2213550 100644 --- a/CONTRIBUTORS.md +++ b/CONTRIBUTORS.md @@ -108,5 +108,6 @@ - Swara Gandhi - Shubham Gupta (guptashs) - Vibhu Pareek (vibhup) -- Richa Gupta +- Richa Gupta (richagpt) - Chandra Dhandapani +- Anant Murarka (anantmu)