@caddis/cli 0.1.0 → 0.2.0

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

@@ -0,0 +1,186 @@
+# AgentCore Identity Service
+
+> **Status**: ✅ Available
+
+## Overview
+
+Amazon Bedrock AgentCore Identity is an identity and credential management service designed specifically for AI agents and automated workloads. It provides secure authentication, authorization, and credential management capabilities that enable agents and tools to access AWS resources and third-party services on behalf of users while maintaining strict security controls and audit trails.
+
+## Core Capabilities
+
+### Centralized Agent Identity Management
+- **Workload Identities**: Agent identities implemented as workload identities with specialized attributes
+- **Unified Directory**: Create, manage, and organize agent identities through unified directory service
+- **Hierarchical Organization**: Group-based access controls and hierarchical organization
+- **Cross-Environment**: Consistent identity management regardless of deployment location
+
+### Secure Credential Storage
+- **Token Vault**: Securely store OAuth 2.0 tokens, client credentials, and API keys
+- **Encryption**: Comprehensive encryption at rest and in transit
+- **Access Controls**: Strict access controls with independent request validation
+- **Defense-in-Depth**: Protects end-user data from malicious or misbehaving agent code
+
+### OAuth 2.0 Flow Support
+- **Client Credentials Grant**: Machine-to-machine authentication (2LO)
+- **Authorization Code Grant**: User-delegated access (3LO)
+- **Built-in Providers**: Pre-configured providers for Google, GitHub, Slack, Salesforce
+- **Custom Providers**: Configurable OAuth 2.0 credential providers for custom integrations
+
+### Credential Provider Management
+- **API Key Providers**: Securely store and manage API keys
+- **OAuth Credential Providers**: Handle OAuth flow and token management
+- **Token Lifecycle**: Automatic token refresh and expiration handling
+- **Provider Discovery**: Automatically discover available credential providers
+
+### Agent Identity and Access Controls
+- **Impersonation Flow**: Agents access resources using provided credentials
+- **Audit Trails**: Maintain audit trails for all actions performed on behalf of users
+- **Request Verification**: Token signature verification, expiration checks, scope validation
+- **Identity-Aware Authorization**: Pass user context to agent code for dynamic decisions
+
+## Use Cases
+
+### Securing AI Agent Access
+Enable agents to:
+- Authenticate with external services securely
+- Access resources on behalf of users
+- Maintain proper audit trails
+- Implement least-privilege access patterns
+
+### Multi-Provider Authentication
+Support scenarios like:
+- Different authentication methods for different APIs
+- Unified credential management across services
+- OAuth flows for user-delegated access
+- API key management for service accounts
+
+### Zero-Trust Security Models
+Allow implementation of:
+- No long-lived credentials in application code
+- Centralized, audited credential vault
+- Automated rotation to reduce attack window
+- Comprehensive access logging
+
+### Compliance and Auditing
+Enable teams to:
+- Generate reports for compliance audits (SOC2, ISO27001)
+- Implement periodic access reviews
+- Maintain secrets inventory
+- Enforce credential policies
+
+## Quick Start
+
+### Create API Key Credential Provider
+
+```bash
+aws bedrock-agentcore-control create-api-key-credential-provider \
+  --name MyAPICredentialProvider \
+  --api-key "YOUR_API_KEY" \
+  --region us-west-2
+```
+
+### Create OAuth Credential Provider
+
+```bash
+aws bedrock-agentcore-control create-oauth2-credential-provider \
+  --name MyOAuthProvider \
+  --client-id "YOUR_CLIENT_ID" \
+  --client-secret "YOUR_CLIENT_SECRET" \
+  --authorization-url "https://provider.com/oauth/authorize" \
+  --token-url "https://provider.com/oauth/token" \
+  --scopes '["read", "write"]' \
+  --region us-west-2
+```
+
+### Using Credentials with SDK
+
+```python
+from bedrock_agentcore.identity import CredentialProvider
+
+# Get credentials for external API
+provider = CredentialProvider("MyAPICredentialProvider")
+api_key = provider.get_api_key()
+
+# Get OAuth token
+oauth_provider = CredentialProvider("MyOAuthProvider")
+token = oauth_provider.get_access_token()
+```
+
+## Common Operations
+
+### List Credential Providers
+
+```bash
+aws bedrock-agentcore-control list-api-key-credential-providers \
+  --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 Credential Provider
+
+```bash
+aws bedrock-agentcore-control delete-api-key-credential-provider \
+  --name MyAPICredentialProvider \
+  --region us-west-2
+```
+
+## Built-in OAuth Providers
+
+AgentCore Identity includes built-in providers for popular services:
+
+| Provider | Use Case |
+|----------|----------|
+| **Google** | Google Workspace, Gmail, Drive |
+| **GitHub** | Repository access, Actions |
+| **Slack** | Messaging, channel access |
+| **Salesforce** | CRM data access |
+
+## Best Practices
+
+### Security
+- Use credential providers instead of hardcoded credentials
+- Implement least-privilege access for each credential
+- Rotate credentials regularly (quarterly minimum)
+- Monitor credential usage with CloudWatch
+
+### Development
+- Use separate credential providers per environment
+- Implement proper error handling for credential access
+- Test credential flows in non-production first
+- Use SDK annotations for cleaner code
+
+### Operations
+- Set up alerts for credential access failures
+- Audit credential usage periodically
+- Implement automated rotation where possible
+- Document credential ownership and purpose
+
+## Troubleshooting
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Credential not found | Provider doesn't exist or name typo | Verify provider name with list command |
+| Invalid API key | Key expired or incorrect | Update credential provider with new key |
+| OAuth token expired | Token refresh failed | Check OAuth provider configuration |
+| Access denied | Insufficient permissions | Verify IAM policy for credential access |
+
+## Related Services
+
+- **[Gateway Service](../gateway/README.md)**: Uses Identity for MCP target authentication
+- **[Runtime Service](../runtime/README.md)**: Uses Identity for agent authentication
+- **[Memory Service](../memory/README.md)**: May use Identity for data encryption
+
+## References
+
+- [AWS Identity Documentation](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/identity.html)
+- [Credential Provider Setup](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/identity-outbound-credential-provider.html)
+- [Identity Features](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/key-features-and-benefits.html)
+- [Securing AI Agents Blog](https://aws.amazon.com/blogs/security/securing-ai-agents-with-amazon-bedrock-agentcore-identity/)

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

@@ -0,0 +1,253 @@
+# AgentCore Memory Service
+
+> **Status**: ✅ Available
+
+## Overview
+
+Amazon Bedrock AgentCore Memory is a fully managed service that gives AI agents the ability to remember past interactions, enabling more intelligent, context-aware, and personalized conversations. It addresses a fundamental challenge in agentic AI: statelessness. Without memory capabilities, AI agents treat each interaction as a new instance with no knowledge of previous conversations.
+
+## Memory Types
+
+AgentCore Memory offers two types of memory that work together:
+
+### Short-Term Memory
+Captures turn-by-turn interactions within a single session, allowing agents to maintain immediate context without requiring users to repeat information.
+
+**Example**: When a user asks "What's the weather like in Seattle?" and follows up with "What about tomorrow?", the agent relies on recent conversation history to understand that "tomorrow" refers to Seattle weather.
+
+### Long-Term Memory
+Automatically extracts and stores key insights from conversations across multiple sessions, including user preferences, important facts, and session summaries for persistent knowledge retention.
+
+**Example**: If a customer mentions they prefer window seats during flight booking, the agent stores this preference and proactively offers window seats in future interactions.
+
+## Core Capabilities
+
+### Memory Resource Management
+- **Logical Containers**: Encapsulate both raw events and processed long-term memories
+- **Retention Policies**: Define how long data is retained
+- **Security Configuration**: Control access and encryption
+- **Data Transformation**: Transform raw interactions into meaningful insights
+
+### Short-Term Memory Features
+- **Event Storage**: Store conversations, system events, and state changes as immutable events
+- **Session Organization**: Organize by actor and session
+- **Context Preservation**: Maintain immediate context within sessions
+- **Structured Storage**: Support structured storage of interaction data
+
+### Long-Term Memory Features
+- **Insight Extraction**: Automatically extract insights, preferences, and knowledge
+- **Asynchronous Processing**: Extract memories asynchronously using memory strategies
+- **Cross-Session Persistence**: Retain information across multiple sessions
+- **Semantic Search**: Search memories by meaning and context
+
+### Memory Strategies
+Define the intelligence layer that transforms raw events into meaningful memories:
+
+| Strategy | Description |
+|----------|-------------|
+| **Semantic** | Extract meaningful facts and information |
+| **Summary** | Generate conversation summaries |
+| **User Preference** | Extract and store user preferences |
+| **Custom** | Define custom extraction logic |
+
+### Advanced Features
+- **Branching**: Create alternative conversation paths from specific points
+- **Checkpointing**: Save and mark specific states for later reference
+- **Memory Consolidation**: Merge related memories without duplicates
+- **Audit Trail**: Immutable audit trail for all memory operations
+
+## Use Cases
+
+### Conversational Agents
+Enable chatbots to:
+- Remember previous issues and preferences
+- Provide relevant assistance based on history
+- Create personalized customer experiences
+- Maintain context across session breaks
+
+### Task-Oriented Agents
+Support workflows like:
+- Track multi-step business process status
+- Maintain workflow progress across sessions
+- Remember task context for resumption
+- Store intermediate results
+
+### Multi-Agent Systems
+Allow agent teams to:
+- Share memory for synchronized operations
+- Coordinate inventory levels and logistics
+- Maintain shared context
+- Optimize collaborative workflows
+
+### Autonomous Agents
+Enable agents to:
+- Plan routes based on past experiences
+- Learn from previous interactions
+- Improve decision-making over time
+- Build persistent knowledge bases
+
+## Quick Start
+
+### Create Memory Resource
+
+```bash
+aws bedrock-agentcore-control create-memory \
+  --memory-name my-agent-memory \
+  --memory-strategies '[{"strategyName": "SEMANTIC", "configuration": {}}]' \
+  --region us-west-2
+```
+
+### Using Memory with SDK
+
+```python
+from bedrock_agentcore.memory import MemoryClient
+
+# Initialize memory client
+memory = MemoryClient(memory_id="my-agent-memory")
+
+# Add short-term memory event
+memory.add_event(
+    session_id="session-123",
+    actor_id="user-456",
+    event_type="message",
+    content={"role": "user", "message": "Book a flight to Seattle"}
+)
+
+# Retrieve conversation history
+history = memory.get_session_events(session_id="session-123")
+
+# Search long-term memories
+memories = memory.search_memories(
+    query="user flight preferences",
+    limit=5
+)
+```
+
+### Store and Retrieve Memories
+
+```python
+# Store long-term memory
+memory.store_memory(
+    memory_type="user_preference",
+    content={"preference": "window_seat", "context": "flights"}
+)
+
+# Retrieve relevant memories
+relevant = memory.search_memories(
+    query="seating preferences for flights",
+    actor_id="user-456"
+)
+```
+
+## Common Operations
+
+### List Memories
+
+```bash
+aws bedrock-agentcore-control list-memories \
+  --region us-west-2
+```
+
+### Get Memory Details
+
+```bash
+aws bedrock-agentcore-control get-memory \
+  --memory-id <MEMORY_ID> \
+  --region us-west-2
+```
+
+### Update Memory Configuration
+
+```bash
+aws bedrock-agentcore-control update-memory \
+  --memory-id <MEMORY_ID> \
+  --memory-strategies '[{"strategyName": "SEMANTIC"}, {"strategyName": "USER_PREFERENCE"}]' \
+  --region us-west-2
+```
+
+### Delete Memory
+
+```bash
+aws bedrock-agentcore-control delete-memory \
+  --memory-id <MEMORY_ID> \
+  --region us-west-2
+```
+
+## Memory Strategies Configuration
+
+### Built-in Strategies
+
+```bash
+# Use semantic strategy
+aws bedrock-agentcore-control create-memory \
+  --memory-name semantic-memory \
+  --memory-strategies '[{
+    "strategyName": "SEMANTIC",
+    "configuration": {}
+  }]'
+```
+
+### Custom Strategies
+
+```bash
+# Create custom strategy with specific model
+aws bedrock-agentcore-control create-memory \
+  --memory-name custom-memory \
+  --memory-strategies '[{
+    "strategyName": "CUSTOM",
+    "configuration": {
+      "modelId": "anthropic.claude-3-sonnet",
+      "extractionPrompt": "Extract key user preferences from this conversation"
+    }
+  }]'
+```
+
+## Best Practices
+
+### Memory Architecture
+- Design memory architecture intentionally
+- Choose appropriate strategies for use case
+- Implement proper retention policies
+- Consider memory costs and storage
+
+### Performance
+- Use appropriate time-to-live settings
+- Extract only relevant information
+- Implement rhythm of memory operations
+- Monitor memory search latency
+
+### Security
+- Implement proper access controls
+- Encrypt sensitive memories
+- Audit memory access
+- Follow data privacy regulations (GDPR, HIPAA)
+
+### Operations
+- Monitor memory usage and costs
+- Set up alerts for memory failures
+- Implement backup strategies
+- Test memory operations regularly
+
+## Troubleshooting
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Memory not found | Incorrect memory ID | Verify memory ID with list command |
+| Search returns empty | No matching memories | Check query and memory content |
+| Slow memory retrieval | Large memory size | Implement pagination and filters |
+| Strategy extraction fails | Invalid configuration | Check strategy configuration |
+
+## Related Services
+
+- **[Gateway Service](../gateway/README.md)**: Expose APIs as tools for agents
+- **[Runtime Service](../runtime/README.md)**: Execute agents that generate conversation data
+- **[Identity Service](../identity/README.md)**: Secure access to conversation data
+- **[Observability Service](../observability/README.md)**: Monitor memory operations
+
+## References
+
+- [AWS Memory Documentation](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/memory.html)
+- [Memory Types](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/memory-types.html)
+- [Memory Strategies](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/memory-strategies.html)
+- [Building Context-Aware Agents Blog](https://aws.amazon.com/blogs/machine-learning/amazon-bedrock-agentcore-memory-building-context-aware-agents/)
+- [Long-Term Memory Deep Dive](https://aws.amazon.com/blogs/machine-learning/building-smarter-ai-agents-agentcore-long-term-memory-deep-dive/)