{"id":45157425,"url":"https://github.com/couchbase-examples/aws-bedrock-agents-scripts","last_synced_at":"2026-02-20T05:02:42.993Z","repository":{"id":283422475,"uuid":"951710445","full_name":"couchbase-examples/aws-bedrock-agents-scripts","owner":"couchbase-examples","description":null,"archived":false,"fork":false,"pushed_at":"2025-04-06T21:52:25.000Z","size":29,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-06T22:27:45.350Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/couchbase-examples.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-20T05:50:45.000Z","updated_at":"2025-04-06T21:52:28.000Z","dependencies_parsed_at":"2025-03-20T07:20:11.939Z","dependency_job_id":"1b803d0b-8312-4ad9-9762-7f37304505ff","html_url":"https://github.com/couchbase-examples/aws-bedrock-agents-scripts","commit_stats":null,"previous_names":["couchbase-examples/aws-bedrock-agents-scripts"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/couchbase-examples/aws-bedrock-agents-scripts","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbase-examples%2Faws-bedrock-agents-scripts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbase-examples%2Faws-bedrock-agents-scripts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbase-examples%2Faws-bedrock-agents-scripts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbase-examples%2Faws-bedrock-agents-scripts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/couchbase-examples","download_url":"https://codeload.github.com/couchbase-examples/aws-bedrock-agents-scripts/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbase-examples%2Faws-bedrock-agents-scripts/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29641929,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-20T03:21:14.183Z","status":"ssl_error","status_checked_at":"2026-02-20T03:18:24.455Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-20T05:02:38.948Z","updated_at":"2026-02-20T05:02:42.988Z","avatar_url":"https://github.com/couchbase-examples.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AWS Bedrock Agents Framework\n\nThis repository contains a framework for creating and managing agents using AWS Bedrock, implementing two different execution approaches: Lambda-based execution and Custom Control execution.\n\n## Overview\n\nThis framework provides a complete solution for:\n\n1. Setting up Couchbase as a vector database\n2. Creating and populating vector embeddings using AWS Bedrock\n3. Creating specialized AI agents with different function capabilities\n4. Implementing and comparing two execution models:\n   - Lambda-based function execution\n   - Custom Control (RETURN_CONTROL) based execution\n\n## Prerequisites\n\n- AWS Account with Bedrock access enabled\n- Couchbase Server cluster (either self-hosted or on cloud)\n- Python 3.9+\n- AWS CLI configured with appropriate permissions\n\n## Environment Setup\n\nCreate a `.env` file in the root directory with the following variables:\n\n```\n# AWS Configuration\nAWS_REGION=us-east-1\nAWS_ACCESS_KEY_ID=your_access_key\nAWS_SECRET_ACCESS_KEY=your_secret_key\nAWS_ACCOUNT_ID=your_account_id\n\n# Couchbase Configuration\nCB_HOST=couchbase://localhost\nCB_USERNAME=Administrator\nCB_PASSWORD=password\nCB_BUCKET_NAME=vector-search-testing\nSCOPE_NAME=shared\nCOLLECTION_NAME=bedrock\nINDEX_NAME=vector_search_bedrock\n\n# Execution Approach (custom_control or lambda)\nAPPROACH=custom_control\n```\n\n## Installation\n\n1. Clone the repository:\n```bash\ngit clone https://github.com/yourusername/aws-bedrock-agents-scripts.git\ncd aws-bedrock-agents-scripts\n```\n\n2. Create a virtual environment and install dependencies:\n```bash\npython -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\npip install -r requirements.txt\n```\n\n## Project Structure\n\n```\n.\n├── main.py                     # Main script with setup and execution logic\n├── utils.py                    # Shared utility functions\n├── age_lambda.py               # Lambda-based agent execution\n├── age_custom_control.py       # Custom Control based agent execution\n├── lambda_functions/           # Lambda function code\n│   ├── bedrock_agent_researcher.py # Researcher agent Lambda\n│   ├── bedrock_agent_writer.py     # Writer agent Lambda\n│   ├── deploy.py               # Script to deploy Lambda functions\n│   └── requirements.txt        # Lambda function dependencies\n├── lambda_demo/                # Demo code for testing Lambda deployments\n├── documents.json              # Sample documents for agent knowledge\n└── aws_index.json              # Couchbase vector search index definition\n```\n\n## Core Components\n\n### 1. Vector Store Setup\n\nThe framework sets up Couchbase as a vector store:\n- Creates/verifies Couchbase bucket, scope, and collection\n- Sets up search indexes for vector similarity search\n- Loads documents from `documents.json` and embeds them using Bedrock's embedding model\n\n### 2. Agent Implementation\n\nTwo specialized agents are implemented:\n\n**Researcher Agent**:\n- Searches through documents using semantic similarity\n- Provides relevant document excerpts\n- Answers questions based on document content\n\n**Writer Agent**:\n- Formats research findings in a user-friendly way\n- Creates clear summaries\n- Organizes information logically\n- Highlights key insights\n\n### 3. Execution Approaches\n\n**Lambda Approach**:\n- Creates Lambda functions for each agent's capabilities\n- Sets up Lambda execution permissions\n- Delegates function execution to AWS Lambda functions\n\n**Custom Control Approach**:\n- Uses the RETURN_CONTROL mechanism to handle function execution locally\n- Processes agent responses and function calls within the application\n\n## Usage\n\nRun the main script to set up and test both agents:\n\n```bash\npython main.py\n```\n\nTo specify which approach to use, set the `APPROACH` environment variable:\n\n```bash\n# For Lambda approach\nexport APPROACH=lambda\npython main.py\n\n# For Custom Control approach\nexport APPROACH=custom_control\npython main.py\n```\n\n## Lambda Functions\n\nThe Lambda functions implement:\n\n1. **Researcher Lambda (`bedrock_agent_researcher.py`)**:\n   - Connects to Couchbase\n   - Performs similarity searches using vector embeddings\n   - Returns relevant document excerpts\n\n2. **Writer Lambda (`bedrock_agent_writer.py`)**:\n   - Takes content and formatting instructions\n   - Uses Bedrock models to format content\n   - Returns formatted content\n\n### Deploying Lambda Functions\n\nLambda functions are automatically deployed when using the Lambda approach:\n\n```bash\npython lambda_functions/deploy.py\n```\n\n## Advanced Configuration\n\n### Modifying Agent Instructions\n\nAgent instructions and function definitions can be modified in `main.py`:\n\n```python\nresearcher_instructions = \"\"\"\nYou are a Research Assistant that helps users find relevant information in documents.\n...\n\"\"\"\n\nresearcher_functions = [{\n    \"name\": \"search_documents\",\n    \"description\": \"Search for relevant documents using semantic similarity\",\n    ...\n}]\n```\n\n### Adding New Documents\n\nAdd new documents to the `documents.json` file:\n\n```json\n{\n  \"documents\": [\n    {\n      \"text\": \"Your document content here\",\n      \"metadata_field1\": \"value1\",\n      \"metadata_field2\": \"value2\"\n    }\n  ]\n}\n```\n\n## Best Practices\n\n1. **Error Handling**: Both approaches implement robust error handling and retries for AWS service calls\n2. **Debugging**: Enable trace for better visibility into agent execution flow\n3. **Performance Optimization**: Lambda functions include optimization techniques for deployment size and execution speed\n4. **Security**: IAM roles are configured with minimum required permissions\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Lambda Deployment Failures**:\n   - Ensure AWS credentials have appropriate permissions\n   - Check Lambda limits in your AWS account\n   - Verify network connectivity to AWS services\n\n2. **Vector Search Issues**:\n   - Verify Couchbase Search service is enabled\n   - Check index definition in `aws_index.json`\n   - Ensure documents have been properly embedded\n\n3. **Agent Execution Errors**:\n   - Examine logs for specific error messages\n   - Verify agent instructions and function schemas match\n   - Check agent preparation status using AWS console\n\n## License\n\nMIT License\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcouchbase-examples%2Faws-bedrock-agents-scripts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcouchbase-examples%2Faws-bedrock-agents-scripts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcouchbase-examples%2Faws-bedrock-agents-scripts/lists"}