Skip to content

Commit 668cd49

Browse files
giedrigiedri
authored
Merge pull request #272 from giedri/main
Kiro Power for centralized guidance
2 parents 5305d5e + 68bbb0a commit 668cd49

File tree

6 files changed

+358
-1
lines changed

6 files changed

+358
-1
lines changed

‎apigw-ai-agents/README.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,12 @@ This set of samples includes three different implementations of the AI agents us
3939

4040
All implementations follow the same core architecture and implement similar components.
4141

42+
### Kiro Power
43+
44+
In addition to the agents, sample includes sample custom [Kiro Power](./kiro-power/POWER.md) which allows organizations to provide centralized guidance in [Kiro](https://kiro.dev/) - agentic AI with an IDE and CLI.
45+
46+
The power uses Knowledge Base and MCP server implemented in the [Strands framework and Amazon Bedrock AgentCore](./strands-agentcore/) example.
47+
4248
### Knowledge base
4349

4450
Knowledge base focuses on covering information that is changing, need to be curated, and may include sources that aren't available publicly (or need processing, such as re:Invent video transcriptions)

‎apigw-ai-agents/kiro-power/POWER.md‎

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
---
2+
name: "centralized-developer-guidance"
3+
displayName: "Centralized Developer Guidance"
4+
description: "Provides organization-wide, centralized developer guidance. API expertise, best practices, and configuration inspection directly in your IDE."
5+
keywords: ["api-gateway", "governance", "best-practices", "api-expert"]
6+
author: "Your Organization"
7+
---
8+
9+
# Centralized Developer Guidance
10+
11+
## Overview
12+
13+
This power provides centralized, AI-powered developer guidance for your organization. It connects to an Amazon Bedrock AgentCore-based agent that has access to your organization's knowledge base containing best practices, governance requirements, and curated documentation.
14+
15+
**This is a sample implementation, not limited to API development.** While this example focuses on API development guidance, the underlying architecture can be tailored for any use case or development area - security practices, infrastructure patterns, data engineering, frontend development, or any domain where your organization wants to provide centralized guidance. The Knowledge Base content, agent prompts, and tools can all be customized to fit your specific needs.
16+
17+
Unlike project-specific steering files, this power enables organization-wide guidance that can be shared across all teams from a central location. Teams can install this power from a shared directory and receive consistent guidance alongside their project-specific steering files.
18+
19+
**Key capabilities (in this API-focused example):**
20+
- **API Expert Consultation** - Get answers about API development, security, AWS services, and your organization's specific standards
21+
- **API Inspector** - Analyze existing API Gateway configurations and receive improvement recommendations based on AWS best practices and your organization's requirements
22+
23+
**Adapt for your use case** by modifying the Knowledge Base content, agent instructions, and MCP tools to cover your organization's specific domain expertise.
24+
25+
## Available Steering Files
26+
27+
This power includes steering files that provide detailed workflow guidance:
28+
29+
- **api-requirements** - Comprehensive guide for gathering API requirements, covering all aspects from endpoints and authentication to performance and security requirements
30+
31+
## When to Use This Power
32+
33+
Use this power when you need:
34+
- Organization-specific development standards and best practices
35+
- Guidance on API development, management, and governance
36+
- Help with Amazon API Gateway configuration
37+
- Inspection of existing API configurations
38+
39+
## Onboarding
40+
41+
### Prerequisites
42+
43+
Before using this power, your organization needs to deploy the backend infrastructure:
44+
45+
1. **Knowledge Base** - See [strands-agentcore/iac](../strands-agentcore/iac/README.md) for deployment instructions:
46+
- CloudFormation template: [bedrock-kb-s3.yaml](../strands-agentcore/iac/bedrock-kb-s3.yaml)
47+
- S3 bucket with organization documentation
48+
- Bedrock Knowledge Base with vector embeddings
49+
- Data sources for your content and optionally AWS public docs
50+
51+
2. **AgentCore Agent** - See [strands-agentcore/api-expert-agent](../strands-agentcore/api-expert-agent/README.md) for deployment instructions:
52+
- Strands-based agent with Knowledge Base access
53+
- Deployed to Amazon Bedrock AgentCore Runtime
54+
55+
3. **MCP Server** - See [strands-agentcore/mcp](../strands-agentcore/mcp/README.md) for setup details:
56+
- Python-based FastMCP server
57+
- Requirements: [api-helper/requirements.txt](../strands-agentcore/mcp/api-helper/requirements.txt)
58+
59+
> **Important:** For production environments, organizations should deploy a remote MCP server with appropriate authentication and authorization instead of running locally on each developer's machine.
60+
61+
### Local Setup
62+
63+
1. Ensure AWS CLI is configured with appropriate credentials
64+
2. Install this power from your organization's shared location
65+
66+
## Best Practices
67+
68+
- **Combine with project steering** - Use this power for organization-wide guidance alongside project-specific `.kiro/steering/` files
69+
- **Keep Knowledge Base updated** - Ensure your platform team regularly syncs the Knowledge Base with latest documentation
70+
- **Review recommendations** - AI-generated advice should be reviewed by humans, especially for security-related decisions
71+
- **Add organization content** - Customize the Knowledge Base with your internal standards, patterns, and governance requirements
72+
73+
## Configuration
74+
75+
### Local MCP Server Setup (Development/Testing)
76+
77+
For local development and testing, configure the MCP server to run on your machine:
78+
79+
**Step 1: Update `mcp.json` with the actual path to `api_helper.py`**
80+
81+
```json
82+
{
83+
"mcpServers": {
84+
"api-expert-server": {
85+
"command": "python",
86+
"args": [
87+
"/absolute/path/to/strands-agentcore/mcp/api-helper/api_helper.py"
88+
],
89+
"disabled": false,
90+
"env": {
91+
"AWS_REGION": "us-east-1",
92+
"AGENTCORE_AGENT_ARN": "arn:aws:bedrock-agentcore:us-east-1:123456789012:agent-runtime/XXXXXXXXXX"
93+
}
94+
}
95+
}
96+
}
97+
```
98+
99+
**Step 2: Replace placeholders with your actual values**
100+
101+
| Placeholder | Description | How to Get It |
102+
|-------------|-------------|---------------|
103+
| `/absolute/path/to/.../api_helper.py` | Full path to the MCP server script | Run `pwd` in the `strands-agentcore/mcp/api-helper` directory and append `/api_helper.py` |
104+
| `AWS_REGION` | AWS region where your agent is deployed | Check your AgentCore deployment output |
105+
| `AGENTCORE_AGENT_ARN` | ARN of your Bedrock AgentCore Runtime agent | Get from deployment output or AWS Console: Bedrock → AgentCore → Agents |
106+
107+
**Step 3: Configure AWS credentials**
108+
109+
The MCP server uses boto3 which reads credentials from your AWS configuration. Ensure your `~/.aws/config` has valid credentials
110+
111+
**Step 4: Install Python dependencies**
112+
113+
```bash
114+
cd strands-agentcore/mcp/api-helper
115+
pip install -r requirements.txt
116+
```
117+
118+
**Step 5: Reconnect the MCP server**
119+
120+
After updating `mcp.json`, reconnect the MCP server from the Kiro MCP Server panel to apply changes.
121+
122+
### Remote MCP Server Setup (Production)
123+
124+
> **Important:** For production environments, organizations should deploy a remote MCP server with appropriate authentication and authorization instead of running locally on each developer's machine.
125+
126+
**Benefits of remote MCP server:**
127+
- Centralized credential management (no AWS credentials on developer machines)
128+
- Consistent configuration across all developers
129+
- Audit logging and access control
130+
- Easier updates and maintenance
131+
132+
**Remote server configuration in `mcp.json`:**
133+
134+
```json
135+
{
136+
"mcpServers": {
137+
"api-expert-server": {
138+
"url": "https://your-mcp-server.example.com/sse",
139+
"headers": {
140+
"Authorization": "Bearer YOUR_AUTH_TOKEN"
141+
}
142+
}
143+
}
144+
}
145+
```
146+
147+
**Recommended production architecture:**
148+
- Deploy the MCP server behind an API Gateway or Application Load Balancer
149+
- Use OAuth 2.0, OIDC, or your organization's SSO for authentication
150+
- Implement IAM roles for the server to access Bedrock AgentCore
151+
- Enable CloudWatch logging for audit and troubleshooting
152+
- Consider using AWS PrivateLink for private connectivity
153+
154+
### Environment Variables Reference
155+
156+
| Variable | Description | Required |
157+
|----------|-------------|----------|
158+
| `AWS_REGION` | AWS region where AgentCore agent is deployed | Yes |
159+
| `AGENTCORE_AGENT_ARN` | ARN of the Bedrock AgentCore Runtime agent | Yes |
160+
161+
## Sharing This Power
162+
163+
To share this power across your organization:
164+
165+
1. **Host on shared storage** - Place the power directory on a network drive or shared location
166+
2. **Teams install locally** - Each developer adds the power via Kiro Powers UI → "Add Custom Power" → "Local Directory"
167+
3. **Keep synchronized** - Update the shared copy when infrastructure changes
168+
169+

‎apigw-ai-agents/kiro-power/README.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Centralized Developer Guidance - Kiro Power Sample
2+
3+
This is a sample Kiro Power implementation that demonstrates how organizations can provide centralized, AI-powered developer guidance across all teams. The sample connects to an Amazon Bedrock AgentCore-based agent with access to a Knowledge Base containing best practices, governance requirements, and curated documentation. While this example focuses on API development guidance, the architecture can be adapted for any domain — security practices, infrastructure patterns, data engineering, or any area where your organization wants to deliver consistent guidance from a central location.
4+
5+
For detailed information about capabilities, configuration, and deployment, see [POWER.md](./POWER.md).

‎apigw-ai-agents/kiro-power/mcp.json‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
{
2+
"mcpServers": {
3+
"api-expert-server": {
4+
"command": "python",
5+
"args": [
6+
"<path to helper directory>/api_helper.py"
7+
],
8+
"disabled": false,
9+
"env": {
10+
"AWS_REGION": "us-east-1",
11+
"AGENTCORE_AGENT_ARN": "XXXX"
12+
}
13+
}
14+
}
15+
}

‎apigw-ai-agents/kiro-power/steering/api-requirements.md‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
# API Requirements Gathering Guide
2+
3+
When helping users define requirements for APIs, guide them through a structured process covering all aspects of API development. Ask one question at a time—do not overwhelm with lists of questions.
4+
5+
## Requirements Categories to Cover
6+
7+
### 1. API Purpose and Overview
8+
- What problem does the API solve?
9+
- Who are the primary users/consumers?
10+
- Expected usage volume (requests per day/hour)?
11+
- Business context and value proposition?
12+
13+
### 2. Endpoints and Operations
14+
- Resources to expose (users, orders, products, etc.)?
15+
- Operations needed for each resource (GET, POST, PUT, DELETE, PATCH)?
16+
- URL paths and naming conventions?
17+
- Nested resources or relationships?
18+
- Query parameters for filtering, sorting, pagination?
19+
20+
### 3. Request/Response Specifications
21+
- Data sent in request bodies?
22+
- Required or optional headers?
23+
- Query parameters needed?
24+
- Data returned in responses?
25+
- Expected response codes for success and error scenarios?
26+
- Response format (JSON, XML, etc.)?
27+
28+
### 4. Data Models and Schemas
29+
- Domain entities and their attributes?
30+
- Data types for each field?
31+
- Relationships between entities?
32+
- Required vs optional fields?
33+
- Validation rules and constraints?
34+
- Enumerations or fixed value sets?
35+
36+
### 5. Authentication and Authorization
37+
- Authentication method (API keys, JWT, OAuth 2.0, AWS Cognito)?
38+
- Authorization model (RBAC, ABAC, resource-based)?
39+
- Different permission levels or user roles?
40+
- Lambda authorizers for custom authorization?
41+
- IP whitelisting or other access controls?
42+
43+
### 6. Integration Requirements
44+
- Backend services to integrate (Lambda, DynamoDB, RDS, etc.)?
45+
- External API integrations?
46+
- Integration type preference (Lambda proxy vs custom)?
47+
- VPC integrations for private resources?
48+
- Data transformations needed?
49+
50+
### 7. Performance and Scalability
51+
- Expected request rates (per second)?
52+
- Latency requirements (target response time)?
53+
- Caching at API Gateway level?
54+
- Appropriate cache TTL?
55+
- Throttling limits (rate limit, burst limit)?
56+
- Different throttling for different endpoints or tiers?
57+
58+
### 8. Error Handling
59+
- Error scenarios to handle?
60+
- Error messages for clients?
61+
- Custom error responses for different types?
62+
- Error format (standard vs custom)?
63+
- How to communicate validation errors?
64+
65+
### 9. Logging and Monitoring
66+
- Level of logging (execution logs, access logs, both)?
67+
- Appropriate log level (ERROR, INFO, DEBUG)?
68+
- AWS X-Ray tracing for request tracing?
69+
- Metrics to track?
70+
- Alarms to configure?
71+
- CloudWatch dashboard requirements?
72+
73+
### 10. Security Requirements
74+
- AWS WAF configuration?
75+
- CORS requirements?
76+
- Data encryption requirements?
77+
- API keys or usage plans?
78+
- Compliance requirements (HIPAA, PCI-DSS, etc.)?
79+
80+
### 11. Deployment and Environment
81+
- Environments needed (dev, staging, production)?
82+
- Stage-specific configurations?
83+
- Canary deployments?
84+
- Deployment strategy preference?
85+
- Stage variables needed?
86+
87+
### 12. Documentation
88+
- Level of API documentation needed?
89+
- OpenAPI/Swagger UI for interactive docs?
90+
- Specific documentation standards?
91+
- Example requests and responses?
92+
- Internal documentation requirements?
93+
94+
## Requirements Gathering Workflow
95+
96+
1. Greet user and explain you'll help gather comprehensive API requirements
97+
2. Use the `ask_api_expert` tool to check for internal standards before detailed questions
98+
3. Start with API purpose and overview, incorporating internal standards
99+
4. Progress through each category systematically
100+
5. Use `ask_api_expert` tool as needed for internal policies and best practices
101+
6. Ask clarifying questions for gaps, referencing internal standards
102+
7. Once complete, generate a final requirements summary
103+
8. Present summary for confirmation and refinement
104+
105+
## Guidelines
106+
107+
- **Start Broad, Then Narrow**: Begin with high-level questions, then drill into specifics
108+
- **Ask One Category at a Time**: Don't overwhelm users
109+
- **Provide Examples**: Clarify technical details with examples
110+
- **Confirm Understanding**: Summarize and ask for confirmation
111+
- **Identify Gaps**: Proactively identify and address missing information
112+
- **Be Conversational**: Use natural language, not rigid questionnaire format
113+
- **Adapt to Expertise**: Adjust technical depth based on user responses
114+
- **Suggest Best Practices**: Offer AWS best practices when appropriate
115+
- **Reference Internal Standards**: Always check the Knowledge Base for organization-specific requirements
116+
117+
## Output Format
118+
119+
When requirements gathering is complete, produce a structured summary:
120+
121+
```markdown
122+
# API Requirements Summary
123+
124+
## Overview
125+
- API Name: [name]
126+
- Purpose: [description]
127+
- Target Users: [consumers]
128+
- Expected Volume: [requests/day]
129+
130+
## Endpoints
131+
| Resource | Method | Path | Description |
132+
|----------|--------|------|-------------|
133+
| ... | ... | ... | ... |
134+
135+
## Authentication & Authorization
136+
- Method: [auth method]
137+
- Authorization Model: [model]
138+
- Roles/Permissions: [details]
139+
140+
## Data Models
141+
[Entity definitions with attributes and types]
142+
143+
## Performance Requirements
144+
- Target Latency: [ms]
145+
- Rate Limits: [requests/second]
146+
- Caching: [yes/no, TTL]
147+
148+
## Security Requirements
149+
- WAF: [yes/no]
150+
- CORS: [configuration]
151+
- Encryption: [requirements]
152+
- Compliance: [standards]
153+
154+
## Monitoring & Logging
155+
- Logging Level: [level]
156+
- Tracing: [yes/no]
157+
- Key Metrics: [list]
158+
159+
## Deployment
160+
- Environments: [list]
161+
- Strategy: [approach]
162+
```

‎apigw-ai-agents/strands-agentcore/mcp/api-helper/api_helper.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -114,7 +114,7 @@ async def inspect_API(request: str) -> str:
114114
)
115115
try:
116116
logger.debug(f"API Inspector tool request: {request}")
117-
session_id= "api_inspector_session_"+api_id+str(uuid.uuid4())
117+
session_id= "api_inspector_session_"+str(uuid.uuid4())
118118
payload = json.dumps({"request": f"Inspect API with ID {request} and provide improvement recommendations"}).encode()
119119

120120
# Invoke bedrock API Expert agent and get response

0 commit comments

Comments
 (0)