bedrock-agentcore-starter-toolkit 0.1.1__tar.gz → 0.1.3__tar.gz

bedrock_agentcore_starter_toolkit-0.1.3/.github/workflows/integration_testing.yml

@@ -0,0 +1,86 @@
+name: Secure Integration test
+
+on:
+  push:
+    branches: [ main ]
+    tags:
+      - 'v*'
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  authorization-check:
+    permissions: read-all
+    runs-on: ubuntu-latest
+    outputs:
+      approval-env: ${{ steps.collab-check.outputs.result }}
+    steps:
+      - name: Collaborator Check
+        uses: actions/github-script@v7
+        id: collab-check
+        with:
+          result-encoding: string
+          script: |
+            try {
+              let username;
+              if (context.payload.pull_request) {
+                username = context.payload.pull_request.user.login;
+              } else {
+                // For non-PRs (eg. merge), check the actor (person who merged)
+                username = context.actor;
+                console.log(`No pull request context found, checking permissions for actor: ${username}`);
+              }
+
+              const permissionResponse = await github.rest.repos.getCollaboratorPermissionLevel({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                username: username,
+              });
+              const permission = permissionResponse.data.permission;
+              const hasWriteAccess = ['write', 'admin'].includes(permission);
+              if (!hasWriteAccess) {
+                console.log(`User ${username} does not have write access to the repository (permission: ${permission})`);
+                return "manual-approval"
+              } else {
+                console.log(`Verifed ${username} has write access. Auto Approving PR Checks.`)
+                return "auto-approve"
+              }
+            } catch (error) {
+              console.log(`${username} does not have write access. Requiring Manual Approval to run PR Checks.`)
+              return "manual-approval"
+            }
+  check-access-and-checkout:
+    runs-on: ubuntu-latest
+    needs: authorization-check
+    environment: ${{ needs.authorization-check.outputs.approval-env }}
+    permissions:
+      id-token: write
+      pull-requests: read
+      contents: read
+    steps:
+      - name: Configure Credentials
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+         role-to-assume: ${{ secrets.AGENTCORE_INTEG_TEST_ROLE }}
+         aws-region: us-west-2
+         mask-aws-account-id: true
+      - name: Checkout head commit
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.sha }} # Pull the commit from the forked repo
+          persist-credentials: false  # Don't persist credentials for subsequent actions
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+      - name: Install dependencies
+        run: |
+          pip install -e .
+          pip install --no-cache-dir pytest click
+      - name: Run integration tests
+        env:
+          AWS_REGION: us-west-2
+          AGENTCORE_TEST_ROLE: AgentExecutionRole
+        id: tests
+        run: |
+          pytest tests_integ/cli -s --log-cli-level=INFO

{bedrock_agentcore_starter_toolkit-0.1.1 → bedrock_agentcore_starter_toolkit-0.1.3}/CHANGELOG.md

@@ -1,6 +1,41 @@
 # Changelog
 
-## [0.1.1] - 2025-01-22
+## [0.1.3] - 2025-08-01
+
+### BREAKING CHANGES
+- **CodeBuild is now the default launch method** - The `--codebuild` flag is no longer needed
+  - To use local Docker builds, you must now explicitly use `--local-build` flag
+  - This change improves the default user experience by building ARM64 containers in the cloud without requiring local Docker
+
+### Added
+- **Streaming invoke support re-enabled** - Restored streaming functionality for real-time agent responses
+- **Extended request timeout** - Increased invoke request timeout from default to 900 seconds (15 minutes) to support long-running agent operations
+
+### Changed
+- **Default launch behavior** - CodeBuild is now the default (`use_codebuild=True`)
+  - Users no longer need Docker installed locally for standard deployments
+  - Automatic ARM64 container builds in AWS CodeBuild
+  - Use `agentcore launch` for cloud builds (default)
+  - Use `agentcore launch --local-build` for local Docker builds
+
+### Improved
+- **Enhanced CLI help text** - Clearer descriptions guide users toward recommended options
+- **Better error messages** - Actionable recommendations for common issues
+- **Conflict handling** - Enhanced exception messages now suggest using `--auto-update-on-conflict` flag
+
+
+## [0.1.2] - 2025-07-23
+
+### Fixed
+- **S3 bucket creation in us-east-1 region** - Fixed CodeBuild S3 bucket creation failure
+  - Removed unsupported `LocationConstraint` parameter for us-east-1 region
+  - us-east-1 is the default S3 region and does not accept LocationConstraint
+  - CodeBuild feature now works correctly in all AWS regions including IAD
+
+### Dependencies
+- Updated to use bedrock-agentcore SDK v0.1.1
+
+## [0.1.1] - 2025-07-22
 
 ### Added
 - **Multi-platform Docker build support via AWS CodeBuild** (#1)
@@ -20,6 +55,12 @@
   - Informative error messages for common IAM scenarios
   - Eliminates need for manual IAM role creation before deployment
 
+- **Auto-update on conflict for agent deployments** (#3)
+  - New `--auto-update-on-conflict` flag for `agentcore launch` command
+  - Automatically updates existing agents instead of failing with conflict errors
+  - Available in both CLI and notebook interfaces
+  - Streamlines iterative development and deployment workflows
+
 ### Changed
 - Enhanced `agentcore launch` command to support both local Docker and CodeBuild workflows
 - Improved error handling patterns throughout the codebase
@@ -35,7 +76,7 @@
 - Improved build reliability and monitoring capabilities
 - Better user experience with one-command ARM64 deployment
 
-## [0.1.0] - 2025-01-16
+## [0.1.0] - 2025-07-16
 
 ### Added
 - Initial release of Bedrock AgentCore Starter Toolkit

{bedrock_agentcore_starter_toolkit-0.1.1 → bedrock_agentcore_starter_toolkit-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bedrock-agentcore-starter-toolkit
-Version: 0.1.1
+Version: 0.1.3
 Summary: A starter toolkit for using Bedrock AgentCore
 Project-URL: Homepage, https://github.com/aws/bedrock-agentcore-starter-toolkit
 Project-URL: Bug Tracker, https://github.com/aws/bedrock-agentcore-starter-toolkit/issues
@@ -21,7 +21,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
-Requires-Dist: bedrock-agentcore>=0.1.0
+Requires-Dist: bedrock-agentcore>=0.1.1
 Requires-Dist: boto3>=1.39.7
 Requires-Dist: botocore>=1.39.7
 Requires-Dist: docstring-parser<1.0,>=0.15

{bedrock_agentcore_starter_toolkit-0.1.1 → bedrock_agentcore_starter_toolkit-0.1.3}/documentation/docs/user-guide/runtime/overview.md

@@ -1,88 +1,73 @@
 # AgentCore Runtime SDK Overview
 
-The Amazon Bedrock AgentCore Runtime SDK transforms your Python functions into production-ready AI agents that can be deployed, scaled, and managed in the cloud. At its core, the SDK provides `BedrockAgentCoreApp` - a powerful HTTP service wrapper that handles all the complexity of agent deployment while letting you focus on your agent's logic.
+The Amazon Bedrock AgentCore Runtime SDK transforms your Python functions into production-ready AI agents with built-in HTTP service wrapper, session management, and complete deployment workflows.
 
-## What is the AgentCore Runtime SDK?
-
-The Runtime SDK is a comprehensive Python framework that bridges the gap between your AI agent code and Amazon Bedrock AgentCore's managed infrastructure. It provides HTTP service wrapper, decorator-based programming, session management, authentication integration, streaming support, async task management, and complete local development tools.
-
-## Core SDK Components
-
-### BedrockAgentCoreApp: The Foundation
-
-`BedrockAgentCoreApp` extends Starlette to provide an agent-optimized web server with built-in endpoints:
-
-- **`/invocations`** - Main endpoint for processing agent requests
-- **`/ping`** - Health check endpoint with status reporting
-- **Built-in logging** - Request tracking with correlation IDs
-- **Error handling** - Automatic error formatting and status codes
-- **Concurrency control** - Request limiting and thread pool management
+## Quick Start
 
 ```python
 from bedrock_agentcore import BedrockAgentCoreApp
 
-# Initialize with optional debug mode
-app = BedrockAgentCoreApp(debug=True)
-```
+app = BedrockAgentCoreApp()
 
-### Core Decorators
+@app.entrypoint
+def my_agent(payload):
+    return {"result": f"Hello {payload.get('name', 'World')}!"}
 
-The SDK uses a decorator-based approach that makes agent development intuitive:
+if __name__ == "__main__":
+    app.run()
+```
 
-#### @app.entrypoint - Main Agent Function
+```bash
+# Configure and deploy your agent
+agentcore configure --entrypoint my_agent.py
+agentcore launch
+agentcore invoke '{"name": "Alice"}'
+```
 
-The fundamental decorator that registers your primary agent logic:
+## What is the AgentCore Runtime SDK?
 
-```python
-@app.entrypoint
-def invoke(payload):
-    """Process requests synchronously"""
-    user_message = payload.get("prompt", "Hello")
-    # Your agent logic here
-    return {"result": "Response"}
+The Runtime SDK is a comprehensive Python framework that bridges the gap between your AI agent code and Amazon Bedrock AgentCore's managed infrastructure. It provides HTTP service wrapper, decorator-based programming, session management, authentication integration, streaming support, async task management, and complete local development tools.
 
-# Async version for streaming
-@app.entrypoint
-async def invoke_async(payload):
-    """Process requests asynchronously with streaming"""
-    user_message = payload.get("prompt", "Hello")
-    # Can yield for streaming responses
-    yield {"chunk": "Partial response"}
-```
+## Core Components
 
-#### @app.ping - Custom Health Checks
+**BedrockAgentCoreApp** - HTTP service wrapper with:
+- `/invocations` endpoint for agent logic
+- `/ping` endpoint for health checks
+- Built-in logging, error handling, and session management
 
-Override default health status logic:
+**Key Decorators:**
+- `@app.entrypoint` - Define your agent's main logic
+- `@app.ping` - Custom health checks
+- `@app.async_task` - Background processing
 
-```python
-from bedrock_agentcore.runtime.models import PingStatus
+## Deployment Modes
 
-@app.ping
-def custom_health():
-    """Custom health logic"""
-    if system_busy():
-        return PingStatus.HEALTHY_BUSY
-    return PingStatus.HEALTHY
+### 🚀 Cloud Build (RECOMMENDED)
+```bash
+agentcore configure --entrypoint my_agent.py
+agentcore launch                    # Uses CodeBuild - no Docker needed
 ```
+- **No Docker required** - builds in the cloud
+- **Production-ready** - standardized ARM64 containers
+- **Works everywhere** - SageMaker Notebooks, Cloud9, laptops
 
-#### @app.async_task - Background Processing
-
-Automatically track long-running operations:
+### 💻 Local Development
+```bash
+agentcore launch --local           # Build and run locally
+```
+- **Fast iteration** - immediate feedback and debugging
+- **Requires:** Docker, Finch, or Podman
 
-```python
-@app.async_task
-async def background_processing():
-    """Automatically tracked async task"""
-    await asyncio.sleep(30)  # Status becomes HEALTHY_BUSY
-    return "completed"       # Status returns to HEALTHY
+### 🔧 Hybrid Build
+```bash
+agentcore launch --local-build     # Build locally, deploy to cloud
 ```
+- **Custom builds** with cloud deployment
+- **Requires:** Docker, Finch, or Podman
 
 ## Agent Development Patterns
 
 ### Synchronous Agents
-
-Perfect for quick, deterministic responses:
-
 ```python
 from bedrock_agentcore import BedrockAgentCoreApp
 
@@ -90,23 +75,13 @@ app = BedrockAgentCoreApp()
 
 @app.entrypoint
 def simple_agent(payload):
-    """Basic request-response agent"""
     prompt = payload.get("prompt", "")
-
-    # Simple processing logic
     if "weather" in prompt.lower():
         return {"result": "It's sunny today!"}
-
     return {"result": f"You said: {prompt}"}
-
-if __name__ == "__main__":
-    app.run()
 ```
 
 ### Streaming Agents
-
-For real-time, dynamic responses that build over time:
-
 ```python
 from strands import Agent
 from bedrock_agentcore import BedrockAgentCoreApp
@@ -138,12 +113,11 @@ if __name__ == "__main__":
 - **Real-time Processing**: Immediate response chunks as they're available
 
 ### Framework Integration
-
 The SDK works seamlessly with popular AI frameworks:
 
 **Strands Integration:**
 ```python
-from strands import Agent, tool
+from strands import Agent
 from bedrock_agentcore import BedrockAgentCoreApp
 
 agent = Agent(tools=[your_tools])
@@ -151,11 +125,9 @@ app = BedrockAgentCoreApp()
 
 @app.entrypoint
 def strands_agent(payload):
-    """Strands-powered agent"""
     result = agent(payload.get("prompt"))
     return {"result": result.message}
 ```
-
 **Custom Framework Integration:**
 ```python
 @app.entrypoint
@@ -170,7 +142,10 @@ async def custom_framework_agent(payload):
 
 ## Session Management
 
-The SDK provides built-in session handling for stateful conversations with automatic session creation and management, 15-minute timeout, cross-invocation context persistence, and complete session isolation for security:
+Built-in session handling with automatic creation, 15-minute timeout, and cross-invocation persistence:
+
+```python
+from bedrock_agentcore.runtime.context import RequestContext
 
 ```python
 from bedrock_agentcore.runtime.context import RequestContext
@@ -189,12 +164,15 @@ def session_aware_agent(payload, context: RequestContext):
 ```
 
 ```bash
+# CLI session management
 # Using AgentCore CLI with session management
 agentcore invoke '{"prompt": "Hello, remember this conversation"}' --session-id "conversation-123"
+
 agentcore invoke '{"prompt": "What did I say earlier?"}' --session-id "conversation-123"
 ```
 
-## Authentication and Authorization
+## Authentication & Authorization
+
 
 The SDK integrates with AgentCore's identity services providing automatic AWS credential validation (IAM SigV4) by default or JWT Bearer tokens for OAuth-compatible authentication:
 
@@ -206,62 +184,88 @@ agentcore configure --entrypoint my_agent.py \
 
 ## Asynchronous Processing
 
-For long-running operations, the SDK provides comprehensive async support with automatic task tracking that transitions agent status to HEALTHY_BUSY during processing, or fine-grained manual control:
+AgentCore Runtime supports asynchronous processing for long-running tasks. Your agent can start background work and immediately respond to users, with automatic health status management.
+
+### Key Features
 
+**Automatic Status Management:**
+- Agent status changes to "HealthyBusy" during background processing
+- Returns to "Healthy" when tasks complete
+- Sessions automatically terminate after 15 minutes of inactivity
+
+**Three Processing Approaches:**
+
+1. **Async Task Decorator (Recommended)**
 ```python
-# Automatic task tracking
 @app.async_task
-async def long_running_task():
-    """Automatically tracked - agent status becomes BUSY"""
-    await process_large_dataset()
-    return "completed"
+async def background_work():
+    await process_data()  # Status becomes "HealthyBusy"
+    return "done"
 
 @app.entrypoint
-async def start_processing(payload):
-    """Start background task"""
-    asyncio.create_task(long_running_task())
-    return {"status": "Processing started in background"}
+async def handler(event):
+    asyncio.create_task(background_work())
+    return {"status": "started"}
+```
 
-# Manual task management
+2. **Manual Task Management**
+```python
 @app.entrypoint
-def manual_task_control(payload):
-    """Manual async task management"""
-    task_id = app.add_async_task("data_processing", {"batch_size": 1000})
+def handler(event):
+    task_id = app.add_async_task("data_processing", {"batch": 100})
 
     def background_work():
-        time.sleep(60)
+        time.sleep(30)
         app.complete_async_task(task_id)
 
     threading.Thread(target=background_work, daemon=True).start()
-    return {"task_id": task_id, "status": "started"}
+    return {"task_id": task_id}
 ```
 
-## Local Development
+3. **Custom Ping Handler**
+```python
+@app.ping
+def custom_status():
+    if processing_data or system_busy():
+        return PingStatus.HEALTHY_BUSY
+    return PingStatus.HEALTHY
+```
 
-The SDK provides a complete local development environment with debug mode for additional capabilities and comprehensive logging with automatic request correlation:
+**Common Use Cases:**
+- Data processing that takes minutes or hours
+- File uploads and conversions
+- External API calls with retries
+- Batch operations and reports
 
-```python
-# Development server with debug mode
-app = BedrockAgentCoreApp(debug=True)
+See the [Async Processing Guide](async.md) for detailed examples and testing strategies.
 
-if __name__ == "__main__":
-    app.run()  # Default port 8080, auto-detects Docker vs local
+## Local Development
 
-# Custom logging
-import logging
-logger = logging.getLogger("my_agent")
+### Debug Mode
+```python
+app = BedrockAgentCoreApp(debug=True)  # Enhanced logging
 
-@app.entrypoint
-def my_agent(payload):
-    logger.info("Processing request: %s", payload)
-    # Your logic here
+if __name__ == "__main__":
+    app.run()  # Auto-detects Docker vs local
 ```
 
+### Complete Development Workflow
 ```bash
-# Configure and test locally using AgentCore CLI
-agentcore configure --entrypoint my_agent.py --name my-agent
+# 1. Configure
+agentcore configure --entrypoint my_agent.py
+
+# 2. Develop locally
 agentcore launch --local
-agentcore invoke '{"prompt": "Hello world"}'
-agentcore invoke '{"prompt": "Remember this"}' --session-id "test-session"
-agentcore invoke '{"prompt": "Hello"}' --bearer-token "your-jwt-token"
+
+# 3. Test
+agentcore invoke '{"prompt": "Hello"}'
+agentcore invoke '{"prompt": "Remember this"}' --session-id "test"
+
+# 4. Deploy to cloud
+agentcore launch
+
+# 5. Monitor
+agentcore status
 ```
+
+The AgentCore Runtime SDK provides everything needed to build, test, and deploy production-ready AI agents with minimal setup and maximum flexibility.