@caddis/cli 0.1.0 → 0.2.0

package/bundles/antigravity-plugin-extras/skills/aws-agentic-ai/services/browser/README.md

@@ -0,0 +1,363 @@
+# AgentCore Browser Service
+
+> **Status**: ✅ Available
+
+## Overview
+
+Amazon Bedrock AgentCore Browser provides a fast, secure, cloud-based browser runtime enabling AI agents to interact with websites at scale without infrastructure management.
+
+## Core Capabilities
+
+### Cloud-Based Runtime
+- **Fast Execution**: High-performance browser instances with minimal latency
+- **Auto Scaling**: Automatic scaling based on demand without configuration
+- **Zero Infrastructure**: No servers or containers to manage
+- **Multi-Region**: Deploy browser instances across AWS regions globally
+
+### Security and Compliance
+- **Enterprise Security**: Industry-standard security controls and encryption
+- **Isolated Sessions**: Each browsing session runs in complete isolation
+- **Data Protection**: Secure data handling and privacy controls
+- **Compliance Ready**: Meets enterprise compliance requirements (SOC, HIPAA, GDPR)
+
+### Web Interaction Capabilities
+- **Full Automation**: Complete browser automation capabilities
+- **JavaScript Support**: Execute JavaScript in browser context
+- **Form Interaction**: Fill forms, click buttons, navigate pages
+- **Content Extraction**: Extract text, data, and media from pages
+- **Session Management**: Handle cookies, local storage, and sessions
+- **Screenshot Capture**: Take screenshots of pages and elements
+
+### Observability
+- **Execution Logging**: Comprehensive logs of browser actions
+- **Performance Metrics**: Track page load times and operation latency
+- **Error Tracking**: Detailed error capture and debugging information
+- **Request Monitoring**: Monitor network requests and responses
+
+## Use Cases
+
+### Web Scraping and Data Extraction
+Enable agents to:
+- Extract data from websites at scale
+- Scrape content from dynamic pages
+- Collect structured data from multiple sources
+- Monitor website changes over time
+
+### Automated Testing and QA
+Support scenarios like:
+- Automated UI testing of web applications
+- Regression testing for web features
+- Cross-browser compatibility testing
+- Performance testing and monitoring
+
+### Form Filling and Workflow Automation
+Allow agents to:
+- Automate form submissions
+- Complete multi-step workflows
+- Handle authentication and logins
+- Process batch operations on web interfaces
+
+### Real-Time Monitoring
+Enable agents to:
+- Monitor website availability and uptime
+- Track content changes and updates
+- Verify website functionality
+- Gather competitive intelligence
+
+### Content Verification
+Support tasks like:
+- Validate web content accuracy
+- Check link integrity
+- Verify page rendering
+- Test responsive designs
+
+## Architecture
+
+### Browser Execution Flow
+
+```
+Agent Request
+    ↓
+┌─────────────────────────────────────────┐
+│  Browser Service API                    │
+│  - Parse browser action request         │
+│  - Validate parameters                  │
+│  - Allocate browser instance            │
+└─────────────────────────────────────────┘
+    ↓
+┌─────────────────────────────────────────┐
+│  Browser Instance                       │
+│  - Navigate to URL                      │
+│  - Execute JavaScript                   │
+│  - Interact with page elements          │
+│  - Extract content and data             │
+└─────────────────────────────────────────┘
+    ↓
+┌─────────────────────────────────────────┐
+│  Result Processing                      │
+│  - Package extracted data               │
+│  - Capture screenshots (if requested)   │
+│  - Log execution details                │
+│  - Return results to agent              │
+└─────────────────────────────────────────┘
+```
+
+### Security Architecture
+
+1. **Session Isolation**: Each browser session runs in isolated environment
+2. **Network Security**: Controlled outbound internet access
+3. **Data Encryption**: All data encrypted in transit and at rest
+4. **Resource Limits**: CPU, memory, and time limits per session
+5. **Access Control**: IAM-based authentication and authorization
+
+## Configuration
+
+### Basic Browser Session
+
+```bash
+# Configure browser service for agent
+aws bedrock-agentcore-control configure-browser \
+  --agent-id <AGENT_ID> \
+  --session-timeout 600 \
+  --viewport-width 1920 \
+  --viewport-height 1080 \
+  --region <REGION>
+```
+
+### Advanced Configuration
+
+```bash
+# Set browser preferences and capabilities
+aws bedrock-agentcore-control update-browser-config \
+  --agent-id <AGENT_ID> \
+  --browser-config '{
+    "headless": true,
+    "javascript": true,
+    "images": true,
+    "cookies": true,
+    "userAgent": "CustomUserAgent/1.0",
+    "timeout": 30000
+  }' \
+  --region <REGION>
+```
+
+## Browser Actions
+
+### Navigation
+```javascript
+// Navigate to URL
+{
+  "action": "navigate",
+  "url": "https://example.com"
+}
+
+// Go back
+{
+  "action": "goBack"
+}
+
+// Refresh page
+{
+  "action": "reload"
+}
+```
+
+### Element Interaction
+```javascript
+// Click element
+{
+  "action": "click",
+  "selector": "#submit-button"
+}
+
+// Fill input field
+{
+  "action": "type",
+  "selector": "#username",
+  "text": "user@example.com"
+}
+
+// Select option
+{
+  "action": "select",
+  "selector": "#country",
+  "value": "US"
+}
+```
+
+### Content Extraction
+```javascript
+// Extract text
+{
+  "action": "getText",
+  "selector": ".article-content"
+}
+
+// Get element attribute
+{
+  "action": "getAttribute",
+  "selector": "img.logo",
+  "attribute": "src"
+}
+
+// Evaluate JavaScript
+{
+  "action": "evaluate",
+  "script": "return document.title;"
+}
+```
+
+### Screenshots
+```javascript
+// Full page screenshot
+{
+  "action": "screenshot",
+  "fullPage": true
+}
+
+// Element screenshot
+{
+  "action": "screenshot",
+  "selector": "#chart-container"
+}
+```
+
+## Best Practices
+
+### Performance Optimization
+- Use headless mode for non-visual operations
+- Disable unnecessary resources (images, stylesheets)
+- Set appropriate timeouts for page loads
+- Reuse browser sessions when possible
+- Implement exponential backoff for retries
+
+### Reliability
+- Handle network failures gracefully
+- Implement proper error handling
+- Use explicit waits for dynamic content
+- Verify element existence before interaction
+- Set reasonable timeout values
+
+### Security
+- Validate all URLs before navigation
+- Sanitize extracted data
+- Use secure credential storage
+- Implement rate limiting
+- Monitor for suspicious patterns
+
+### Cost Optimization
+- Close browser sessions when done
+- Use session pooling for frequent operations
+- Set appropriate resource limits
+- Monitor usage patterns
+- Implement caching where appropriate
+
+## Integration Patterns
+
+### With Memory Service
+```
+Browser ←→ Memory Service
+- Store extracted data in memory
+- Cache frequently accessed pages
+- Share session state across agents
+```
+
+### With Identity Service
+```
+Browser ←→ Identity Service
+- Authenticate browser sessions
+- Access credentials for protected sites
+- Manage authentication tokens
+```
+
+### With Code Interpreter
+```
+Browser ←→ Code Interpreter
+- Process scraped data with code
+- Transform extracted content
+- Analyze website data
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**Page Load Timeout**
+- Symptom: Page takes too long to load
+- Solution: Increase timeout or optimize target page
+
+**Element Not Found**
+- Symptom: Cannot locate page element
+- Solution: Use explicit waits or verify selector
+
+**JavaScript Errors**
+- Symptom: Page JavaScript fails
+- Solution: Check console logs, handle errors
+
+**Session Terminated**
+- Symptom: Browser session unexpectedly ends
+- Solution: Check resource limits and session timeout
+
+**Authentication Required**
+- Symptom: Cannot access protected pages
+- Solution: Configure credentials via Identity service
+
+## Monitoring
+
+### Key Metrics
+- **Session Count**: Number of active browser sessions
+- **Success Rate**: Percentage of successful operations
+- **Page Load Time**: Average time to load pages
+- **Error Rate**: Percentage of failed operations
+- **Resource Usage**: CPU and memory utilization
+
+### CloudWatch Integration
+```bash
+# Query browser metrics
+aws cloudwatch get-metric-statistics \
+  --namespace AWS/BedrockAgentCore/Browser \
+  --metric-name SessionCount \
+  --dimensions Name=AgentId,Value=<AGENT_ID> \
+  --start-time <START> \
+  --end-time <END> \
+  --period 3600 \
+  --statistics Average
+```
+
+### Logging
+```bash
+# View browser execution logs
+aws logs tail /aws/bedrock-agentcore/browser/<AGENT_ID> \
+  --follow \
+  --format short
+```
+
+## Performance Considerations
+
+### Optimization Techniques
+1. **Disable Unnecessary Resources**: Turn off images/stylesheets when not needed
+2. **Use Headless Mode**: Faster execution without rendering overhead
+3. **Implement Caching**: Cache static resources and repeated queries
+4. **Parallel Execution**: Run multiple browser sessions concurrently
+5. **Smart Waiting**: Use explicit waits instead of fixed delays
+
+### Scaling Patterns
+- **Horizontal Scaling**: Launch multiple browser instances
+- **Session Pooling**: Reuse browser sessions for efficiency
+- **Request Queuing**: Queue browser operations during high load
+- **Regional Distribution**: Distribute load across AWS regions
+
+## Additional Resources
+
+- **AWS Documentation**: [Bedrock AgentCore Browser](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/browser.html)
+- **Best Practices**: [Browser Automation Guide](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/browser-best-practices.html)
+- **API Reference**: [Browser API](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/)
+- **Selector Reference**: [CSS Selectors](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors)
+
+---
+
+**Related Services**:
+- [Runtime Service](../runtime/README.md) - Agent execution
+- [Code Interpreter](../code-interpreter/README.md) - Data processing
+- [Memory Service](../memory/README.md) - State management
+- [Observability Service](../observability/README.md) - Monitoring

package/bundles/antigravity-plugin-extras/skills/aws-agentic-ai/services/code-interpreter/README.md

@@ -0,0 +1,232 @@
+# AgentCore Code Interpreter Service
+
+> **Status**: ✅ Available
+
+## Overview
+
+Amazon Bedrock AgentCore Code Interpreter enables agents to securely execute code in isolated sandbox environments, supporting complex data analysis workflows and computational tasks.
+
+## Core Capabilities
+
+### Secure Execution
+- **Isolated Sandboxes**: Each code execution runs in a completely isolated environment
+- **No Cross-Contamination**: Sessions are independent with no shared state
+- **Enterprise Security**: Meets enterprise security and compliance requirements
+- **Resource Controls**: Configurable limits and timeout controls for execution
+
+### Framework Integration
+- **Popular Frameworks**: Seamless integration with LangGraph, CrewAI, Strands, and other agent frameworks
+- **Multi-Language Support**: Execute code in Python, JavaScript, and other languages
+- **Advanced Configuration**: Extensive customization options for runtime environments
+- **Custom Runtimes**: Support for specialized runtime configurations
+
+### Data Processing
+- **File Operations**: Upload and download files for processing
+- **Multi-Modal Data**: Handle structured and unstructured data
+- **Result Formatting**: Format and visualize execution results
+- **Error Handling**: Comprehensive error reporting and debugging support
+
+## Use Cases
+
+### Data Analysis and Transformation
+Enable agents to:
+- Process and analyze datasets
+- Transform data formats
+- Perform statistical calculations
+- Generate data insights
+
+### Complex Computational Workflows
+Support scenarios like:
+- Running scientific computations
+- Executing business logic calculations
+- Processing batch operations
+- Performing iterative algorithms
+
+### Visualization and Reporting
+Allow agents to:
+- Generate charts and graphs
+- Create formatted reports
+- Build visualizations from data
+- Export results in various formats
+
+### Dynamic Code Testing
+Enable agents to:
+- Test code snippets dynamically
+- Validate logic and algorithms
+- Debug code execution issues
+- Prototype solutions quickly
+
+## Architecture
+
+### Execution Flow
+
+```
+Agent Request
+    ↓
+┌─────────────────────────────────────────┐
+│  Code Interpreter Service               │
+│  - Parse code execution request         │
+│  - Validate code and parameters         │
+│  - Allocate isolated sandbox            │
+└─────────────────────────────────────────┘
+    ↓
+┌─────────────────────────────────────────┐
+│  Sandbox Environment                    │
+│  - Execute code in isolation            │
+│  - Process data and files               │
+│  - Generate outputs                     │
+│  - Capture errors and logs              │
+└─────────────────────────────────────────┘
+    ↓
+┌─────────────────────────────────────────┐
+│  Result Processing                      │
+│  - Format execution results             │
+│  - Package outputs and artifacts        │
+│  - Return to agent                      │
+└─────────────────────────────────────────┘
+```
+
+### Security Model
+
+1. **Sandbox Isolation**: Each execution runs in a completely isolated environment
+2. **Resource Limits**: CPU, memory, and time limits prevent resource exhaustion
+3. **Network Restrictions**: Controlled network access from sandbox environments
+4. **Data Encryption**: Data at rest and in transit is encrypted
+5. **Audit Logging**: All code executions are logged for compliance
+
+## Configuration
+
+### Basic Setup
+
+```bash
+# Configure code interpreter for agent
+aws bedrock-agentcore-control configure-code-interpreter \
+  --agent-id <AGENT_ID> \
+  --execution-timeout 300 \
+  --memory-limit 2048 \
+  --region <REGION>
+```
+
+### Custom Runtime Configuration
+
+```bash
+# Set custom runtime environment
+aws bedrock-agentcore-control update-code-interpreter-runtime \
+  --agent-id <AGENT_ID> \
+  --runtime-config '{
+    "language": "python3.11",
+    "packages": ["pandas", "numpy", "matplotlib"],
+    "environment": {
+      "CUSTOM_VAR": "value"
+    }
+  }' \
+  --region <REGION>
+```
+
+## Best Practices
+
+### Code Security
+- Validate all code inputs before execution
+- Implement input sanitization for user-provided code
+- Use resource limits to prevent denial of service
+- Monitor code execution patterns for anomalies
+
+### Performance Optimization
+- Cache common dependencies in runtime images
+- Use appropriate timeout values for expected workload
+- Optimize code for execution within timeout limits
+- Batch similar operations when possible
+
+### Error Handling
+- Implement comprehensive error catching in code
+- Provide clear error messages for debugging
+- Log execution details for troubleshooting
+- Use structured output formats for results
+
+### Data Management
+- Minimize data transfer in and out of sandboxes
+- Use streaming for large data processing
+- Clean up temporary files after execution
+- Implement data validation before processing
+
+## Integration Patterns
+
+### With Memory Service
+```
+Code Interpreter ←→ Memory Service
+- Store execution results in memory
+- Retrieve past computation results
+- Share data across agent sessions
+```
+
+### With Identity Service
+```
+Code Interpreter ←→ Identity Service
+- Authenticate code execution requests
+- Access credentials for external APIs
+- Manage permissions for data access
+```
+
+### With Observability Service
+```
+Code Interpreter ←→ Observability Service
+- Trace code execution workflows
+- Monitor performance metrics
+- Log execution events
+- Alert on execution failures
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**Execution Timeout**
+- Symptom: Code execution exceeds timeout limit
+- Solution: Increase timeout or optimize code performance
+
+**Memory Limit Exceeded**
+- Symptom: Code runs out of memory
+- Solution: Increase memory limit or process data in chunks
+
+**Package Import Errors**
+- Symptom: Required packages not found
+- Solution: Configure custom runtime with needed packages
+
+**Permission Denied**
+- Symptom: Cannot access required resources
+- Solution: Configure IAM permissions for code interpreter
+
+## Monitoring
+
+### Key Metrics
+- **Execution Count**: Number of code executions
+- **Success Rate**: Percentage of successful executions
+- **Average Duration**: Mean execution time
+- **Error Rate**: Percentage of failed executions
+- **Resource Utilization**: CPU and memory usage
+
+### CloudWatch Integration
+```bash
+# Query execution metrics
+aws cloudwatch get-metric-statistics \
+  --namespace AWS/BedrockAgentCore/CodeInterpreter \
+  --metric-name ExecutionCount \
+  --dimensions Name=AgentId,Value=<AGENT_ID> \
+  --start-time <START> \
+  --end-time <END> \
+  --period 3600 \
+  --statistics Sum
+```
+
+## Additional Resources
+
+- **AWS Documentation**: [Bedrock AgentCore Code Interpreter](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/code-interpreter.html)
+- **Security Best Practices**: [Secure Code Execution](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/code-interpreter-security.html)
+- **API Reference**: [Code Interpreter API](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/)
+
+---
+
+**Related Services**:
+- [Runtime Service](../runtime/README.md) - Agent execution environment
+- [Memory Service](../memory/README.md) - State management
+- [Observability Service](../observability/README.md) - Monitoring and tracing

package/bundles/antigravity-plugin-extras/skills/aws-agentic-ai/services/gateway/README.md

@@ -0,0 +1,100 @@
+# Gateway Service
+
+The Gateway service converts REST APIs into MCP tools that AI agents can use. It handles authentication, schema validation, and request routing.
+
+## Quick Start
+
+### Prerequisites
+- AWS CLI configured with appropriate permissions
+- An existing Gateway (created via AWS Console or CLI)
+- OpenAPI schema for your target API
+
+### Deploy a Gateway Target
+
+**Step 1: Upload OpenAPI schema to S3**
+```bash
+aws s3 cp my-api-openapi.yaml s3://<BUCKET_NAME>/schemas/
+```
+
+**Step 2: Create credential provider (API Key auth only)**
+```bash
+aws bedrock-agentcore-control create-api-key-credential-provider \
+  --name MyAPICredentialProvider \
+  --api-key "YOUR_API_KEY" \
+  --region us-west-2
+```
+
+**Step 3: Create gateway target**
+```bash
+aws bedrock-agentcore-control create-gateway-target \
+  --gateway-identifier <GATEWAY_ID> \
+  --name MyAPITarget \
+  --endpoint-configuration '{"openApiSchema": {"s3": {"uri": "s3://<BUCKET_NAME>/schemas/my-api-openapi.yaml"}}}' \
+  --credential-provider-configurations '[{"credentialProviderType": "GATEWAY_API_KEY_CREDENTIAL_PROVIDER", "apiKeyCredentialProvider": {"providerArn": "arn:aws:bedrock-agentcore:us-west-2:<ACCOUNT_ID>:api-key-credential-provider/MyAPICredentialProvider"}}]' \
+  --region us-west-2
+```
+
+**Step 4: Verify deployment**
+```bash
+aws bedrock-agentcore-control get-gateway-target \
+  --gateway-identifier <GATEWAY_ID> \
+  --target-identifier <TARGET_ID> \
+  --region us-west-2
+```
+
+## Authentication Options
+
+### Outbound (Accessing External APIs)
+
+| Target Type | IAM | OAuth 2LO | OAuth 3LO | API Key |
+|-------------|-----|-----------|-----------|---------|
+| Lambda function | Yes | No | No | No |
+| API Gateway | Yes | No | No | Yes |
+| OpenAPI schema | No | Yes | Yes | Yes |
+| Smithy schema | Yes | Yes | Yes | No |
+| MCP server | No | Yes | No | No |
+
+### Inbound (Who Can Invoke Tools)
+- **IAM**: AWS IAM credentials
+- **JWT**: Tokens from identity providers (Cognito, Entra ID)
+- **No Auth**: Open access (use with caution)
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [Deployment Strategies](deployment-strategies.md) | Credential provider patterns, multi-environment setup, key rotation |
+| [Troubleshooting Guide](troubleshooting-guide.md) | Common errors, diagnosis steps, solutions |
+| [Deploy Template Script](deploy-template.sh) | Automated deployment script |
+| [Validate Deployment Script](validate-deployment.sh) | Post-deployment verification |
+
+## Common Operations
+
+### List Gateway Targets
+```bash
+aws bedrock-agentcore-control list-gateway-targets \
+  --gateway-identifier <GATEWAY_ID> \
+  --region us-west-2
+```
+
+### Update Credential Provider
+```bash
+aws bedrock-agentcore-control update-api-key-credential-provider \
+  --name MyAPICredentialProvider \
+  --api-key "NEW_API_KEY" \
+  --region us-west-2
+```
+
+### Delete Gateway Target
+```bash
+aws bedrock-agentcore-control delete-gateway-target \
+  --gateway-identifier <GATEWAY_ID> \
+  --target-identifier <TARGET_ID> \
+  --region us-west-2
+```
+
+## Related Resources
+
+- [Cross-Service Credential Management](../../cross-service/credential-management.md)
+- [AWS Gateway Documentation](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway.html)
+- [Bedrock AgentCore CLI Reference](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/bedrock-agentcore-control/index.html)