Skip to content

README.md

Latest commit

 

History

History
741 lines (612 loc) · 23 KB

README.md

File metadata and controls

741 lines (612 loc) · 23 KB

my_aws_tools

Author: r3-yamauchi
Version: 1.0.10 Type: tool

English | Japanese

Ask DeepWiki

Fork Status

This repository is a personal fork of the AWS Tools plugin (release 0.0.15) under the terms of the Apache License 2.0.

Overview

This tool plugin provides a set of tools based on several AWS services, letting you leverage AWS capabilities directly inside Dify applications. It adds custom tools not included in the original AWS Tools plugin, removes a few tools that are less frequently used and harder for me to maintain, and adds custom parameters plus Japanese translations for each tool.

Included tools:

  • Apply Guardrail
  • Bedrock Retrieve
  • Bedrock Retrieve and Generate
  • Bedrock KB List
  • Bedrock KB Data Sources
  • Bedrock KB Sync
  • SNS Publish
  • SQS Send Message
  • Step Functions Start Execution
  • Lambda Invoker
  • Lambda YAML to JSON
  • Nova Canvas
  • Nova Reel
  • Extract Frame
  • S3 Operator
  • S3 File Uploader
  • S3 File Download
  • S3 List Buckets
  • S3 Create Bucket
  • S3 List Objects
  • CloudFront Create Invalidation
  • DynamoDB Manager
  • CloudWatch Logs Describe Streams
  • CloudWatch Logs Filter Events
  • CloudWatch Logs Get Events
  • CloudWatch Logs Insight
  • Agentcore Code Interpreter
  • Agentcore Code Interpreter Files
  • Agentcore Memory
  • Agentcore Memory Search
  • Agentcore Memory Search Advanced
  • Agentcore Memory Backup
  • Agentcore Memory Merge/Split
  • Agentcore Memory Manager
  • Agentcore Memory Query
  • Agentcore Memory Statistics
  • Agentcore Memory Template
  • Agentcore Event Manager
  • Agentcore Runtime
  • Agentcore Observability
  • Get Credentials
  • STS AssumeRole

The source code of this plugin is available in the GitHub repository.

License and Credits

This project is distributed under the Apache License 2.0. See LICENSE for the full text, and NOTICE for credit requirements when redistributing derivatives. NOTICE specifies that this implementation is derived from https://github.com/langgenius/dify-official-plugins/tree/main/tools/aws.

Feature Overview by Tool

Amazon Bedrock Suite

  • Bedrock Retrieve: Calls the bedrock-agent-runtime Retrieve API directly to run semantic or HYBRID search against a specified Knowledge Base.
{
  "knowledge_base_id": "ABCDEFG8H9",
  "query": "Latest product roadmap",
  "search_type": "HYBRID",
  "max_results": 5,
  "guardrail_id": "ab1cd2e3f45g"
}
  • Bedrock Retrieve and Generate: Calls retrieve_and_generate. Passing knowledge_base_configuration or external_sources_configuration in JSON performs retrieval and generation together. Provide session_configuration and session_id to let Bedrock retain conversation state.
{
  "result_type": "JSON",
  "input": "Please summarize the incident response procedures",
  "type": "Knowledge Base",
  "knowledge_base_configuration": {
    "knowledgeBaseId": "ABCDEFG8H9",
    "modelArn":"arn:aws:bedrock:us-west-2::foundation-model/anthropic.claude-3-5-sonnet-20240620-v1:0",
    "retrievalConfiguration": {
      "vectorSearchConfiguration": {"numberOfResults": 3}
    }
  }
}
  • Apply Guardrail: Calls apply_guardrail.

Apply Guardrail Sample Request (multiple texts)

{
  "guardrail_id": "ab1cd2e3f45g",
  "guardrail_version": "1",
  "source": "INPUT",
  "content": [
    { "text": { "text": "User input text 1" } },
    { "text": { "text": "User input text 2" } }
  ]
}

Apply Guardrail Sample Request (image + text)

{
  "guardrail_id": "ab1cd2e3f45g",
  "guardrail_version": "2",
  "source": "OUTPUT",
  "content": [
    {
      "image": {
        "format": "png",
        "source": { "s3Uri": "s3://bucket/path/image.png" }
      }
    },
    { "text": { "text": "Response generated by the LLM" } }
  ]
}
  • Nova Canvas – Invokes Nova Canvas v1 for TEXT_IMAGE, COLOR_GUIDED, IMAGE_VARIATION, INPAINTING, OUTPAINTING, and BACKGROUND_REMOVAL tasks. Input images are fetched from S3 and outputs are uploaded back while also streamed to Dify as PNG blobs.
{
  "task": "TEXT_IMAGE",
  "prompt": "A lighthouse during a storm",
  "output_s3_uri": "s3://my-bucket/outputs/canvas.png"
}
  • Nova Reel – Uses Nova Reel v1 to create videos from text or from a seed image. Results are saved as MP4 files in the specified S3 path, and synchronous mode polls until completion to return the binary.
{
  "mode": "TEXT_TO_VIDEO",
  "prompt": "A drone flyover of snowy mountains",
  "output_s3_uri": "s3://my-bucket/outputs/reel.mp4",
  "wait_for_completion": true
}

Audio & Media Processing

  • Extract Frame – Downloads GIF animations and extracts evenly spaced PNG frames. Users choose the number of frames (from two for first/last to any higher count), and each frame is returned as binary output.
{
  "gif_url": "https://example.com/anim.gif",
  "frame_count": 4
}
  • Lambda YAML to JSON – Calls a Lambda function synchronously with YAML text in the request body and returns the JSON body only when the Lambda responds with statusCode 200.
lambda_name: yaml-to-json
yaml_content: |
  key: value
  list:
    - a
    - b
  • Bedrock KB List – Calls list_knowledge_bases to enumerate available knowledge bases, returning summaries (status, creation date, vector store) and pagination tokens for downstream filtering.
{
  "max_results": 20
}
  • Bedrock KB Data Sources – Invokes list_data_sources for a given knowledge base, returning connector information, synchronization state, and pagination tokens so you can select the correct source before running ingestion jobs.
{
  "knowledge_base_id": "ABCDEFG8H9",
  "max_results": 10
}
  • Bedrock KB Sync – Calls StartIngestionJob for a given knowledge base/data source pair so you can synchronize documents on demand, optionally setting a client token or deletion policy.
{
  "knowledge_base_id": "ABCDEFG8H9",
  "data_source_id": "ds-001",
  "client_token": "sync-20250227"
}

Storage & Database Operations

  • CloudFront Create Invalidation – Submits create_invalidation for a distribution. Accepts either paths (e.g., ["/*"] or ["/index.html", "/css/*"]) or an invalidation_batch JSON, and optional caller_reference; defaults invalidate all paths.
{
  "distribution_id": "D123456"
}
{
  "distribution_id": "D123456",
  "paths": ["/index.html", "/css/*"]
}
{
  "distribution_id": "D123456",
  "caller_reference": "my-ref-1",
  "invalidation_batch": {
    "Paths": {
      "Items": ["/*"]
    }
  }
}
  • S3 File Uploader – Uploads a workflow file to the specified bucket/key and can return a presigned URL.
{
  "bucket_name": "my-bucket",
  "object_key": "uploads/example.txt",
  "file": "{{file}}",
  "return_presigned_url": true
}
  • S3 Operator (write) – Reads or writes text content to s3:// URIs; this example writes JSON text.
{
  "operation": "write",
  "s3_uri": "s3://my-bucket/config.json",
  "text": "{\"env\":\"prod\"}"
}
  • S3 File Download – Fetches objects from S3; returns a presigned URL or streams binary (use presign_only / download_mode).
{
  "bucket_name": "my-bucket",
  "object_key": "reports/latest.pdf",
  "presign_only": true,
  "expires_in": 600
}
  • DynamoDB Manager – Creates PAY_PER_REQUEST tables and supports put_item / get_item / delete_item with JSON item_data.
{
  "operation": "put_item",
  "table_name": "users",
  "partition_key_name": "user_id",
  "item_data": {
    "user_id": "u-1",
    "name": "Alice"
  }
}

CloudWatch Logs

  • CloudWatch Logs Describe Streams: Searches and lists log streams within a specified CloudWatch Logs log group. Supports prefix filtering and sort order specification to streamline subsequent log event searches.
{
  "log_group_name": "/aws/lambda/my-function",
  "log_stream_name_prefix": "2025/01/04",
  "order_by": "LastEventTime",
  "descending": true,
  "max_items": 20
}
  • CloudWatch Logs Filter Events: Searches and retrieves log events from CloudWatch Logs using time ranges and filter patterns. Enables cross-stream searches across multiple log streams and filtering by specific string patterns.
{
  "log_group_name": "/aws/lambda/my-function",
  "log_stream_names": "2025/01/04/[$LATEST]abc123,2025/01/04/[$LATEST]def456",
  "start_time": "1h",
  "filter_pattern": "ERROR",
  "max_events": 500
}
  • CloudWatch Logs Get Events: Retrieves all log events from a specified CloudWatch Logs log stream. Supports bidirectional pagination for efficient processing of large log datasets.
{
  "log_group_name": "/aws/lambda/my-function",
  "log_stream_name": "2025/01/04/[$LATEST]abc123",
  "start_time": "2025-01-04T00:00:00Z",
  "end_time": "2025-01-04T23:59:59Z",
  "start_from_head": true,
  "max_events": 10000
}
  • CloudWatch Logs Insight: Executes advanced log analysis, aggregation, and visualization using CloudWatch Logs Insights' powerful query language. Enables cross-log-group analysis and statistical processing across multiple log groups.
{
  "log_group_names": "/aws/lambda/function1,/aws/lambda/function2",
  "query_string": "fields @timestamp, @message | filter @message like /ERROR/ | stats count() by bin(5m) | sort @timestamp desc",
  "start_time": "1d",
  "max_results": 1000
}

Messaging

  • SNS Publish – Publishes to an SNS topic ARN with optional subject and MessageAttributes.
{
  "topic_arn": "arn:aws:sns:us-east-1:111122223333:alerts",
  "message": "Deployed v1.2.3",
  "subject": "Deploy notice"
}
  • SQS Send Message – Sends to an SQS queue URL with optional delay and MessageAttributes.
{
  "queue_url": "https://sqs.us-east-1.amazonaws.com/111122223333/tasks",
  "message_body": "{\"job_id\":123}",
  "delay_seconds": 5
}

Amazon Bedrock AgentCore Integrations

  • AgentCore Runtime: Launches, invokes, and checks the status of Runtime agents. Supports both synchronous and asynchronous invocation modes, enabling session management and retrieval of execution results.
{
  "operation": "invoke",
  "agent_id": "agent-abc123",
  "input_text": "Please execute data analysis",
  "session_id": "session-001",
  "enable_trace": true,
  "end_session": false
}
  • AgentCore Memory Manager: Manages the lifecycle of Memory resources. Enables listing, retrieving detailed information, creating, and deleting Memory resources, with filtering and sorting capabilities.
{
  "operation": "list",
  "max_results": 50,
  "filter_name_prefix": "prod-",
  "sort_by": "createdAt",
  "sort_order": "desc"
}
{
  "operation": "create",
  "memory_name": "customer-support-memory",
  "description": "Memory for customer support",
  "tags": {
    "Environment": "production",
    "Team": "support"
  }
}
  • AgentCore Event Manager: Provides detailed management of Memory events. Enables listing, retrieving details, deleting (individual/batch), and exporting (JSON, CSV) events, with support for filtering by time range, Actor ID, and Session ID.
{
  "operation": "list",
  "memory_id": "mem-abc123",
  "start_time": "2025-01-01T00:00:00Z",
  "end_time": "2025-01-31T23:59:59Z",
  "filter_actor_id": "user001",
  "max_results": 100
}
{
  "operation": "export",
  "memory_id": "mem-abc123",
  "format": "csv",
  "output_location": "s3://my-bucket/exports/events.csv",
  "start_time": "1w"
}
  • AgentCore Memory Statistics: Analyzes Memory usage. Retrieves statistical information for Memory resources, event count aggregation by Actor, event count aggregation by Session, and time-series event count trends.
{
  "operation": "memory_stats",
  "memory_id": "mem-abc123"
}
{
  "operation": "actor_stats",
  "memory_id": "mem-abc123",
  "start_time": "7d",
  "top_n": 10
}
{
  "operation": "timeline",
  "memory_id": "mem-abc123",
  "start_time": "2025-01-01T00:00:00Z",
  "end_time": "2025-01-31T23:59:59Z",
  "interval": "1h"
}
  • AgentCore Observability: Provides integrated access to AgentCore Observability data. Enables session/trace/span metrics, log retrieval from CloudWatch Logs, X-Ray trace data retrieval, performance analysis, and bottleneck identification.
{
  "operation": "get_session_metrics",
  "session_id": "session-abc123",
  "metric_types": "duration,token_count,error_rate"
}
{
  "operation": "get_logs",
  "log_group_name": "/aws/bedrock/agentcore",
  "start_time": "1h",
  "filter_pattern": "ERROR",
  "max_events": 100
}
{
  "operation": "analyze_performance",
  "trace_id": "trace-abc123",
  "include_bottlenecks": true
}
  • AgentCore Memory Backup: Provides complete backup and restore functionality for Memory resources. Can be used for disaster recovery and data migration between environments. Backups are stored in S3 with optional compression and encryption.
{
  "operation": "backup",
  "memory_id": "mem-abc123",
  "backup_location": "s3://my-backup-bucket/backups/",
  "include_events": true,
  "include_strategies": true,
  "compression": "gzip",
  "encryption": true
}
{
  "operation": "restore",
  "backup_location": "s3://my-backup-bucket/backups/mem-abc123-20250115.json.gz",
  "target_memory_id": "mem-new123",
  "conflict_resolution": "skip"
}
  • AgentCore Memory Merge/Split: Provides merge, split, and event copy functionality for Memory resources. Enables consolidating multiple Memory resources, splitting a single Memory by Actor or Session, and copying only events that match specific conditions.
{
  "operation": "merge",
  "source_memory_ids": "mem-abc123,mem-def456,mem-ghi789",
  "target_memory_id": "mem-merged",
  "merge_conflict_resolution": "keep_latest",
  "deduplicate": true,
  "merge_strategies": true
}
{
  "operation": "split",
  "source_memory_id": "mem-abc123",
  "split_by": "actor_id",
  "target_memory_prefix": "memory-actor-",
  "create_index": true
}
  • AgentCore Memory Query: Searches Memory by constructing complex search conditions. Enables combining multiple conditions (AND/OR/NOT), regular expression search, similarity search (vector search), and saving and reusing queries.
{
  "operation": "search",
  "memory_id": "mem-abc123",
  "query": {
    "and": [
      {"field": "actor_id", "operator": "equals", "value": "user001"},
      {"field": "timestamp", "operator": "greater_than", "value": "2025-01-01T00:00:00Z"}
    ]
  },
  "max_results": 50
}
{
  "operation": "similarity_search",
  "memory_id": "mem-abc123",
  "query_text": "Investigate the cause of the error",
  "top_k": 10,
  "similarity_threshold": 0.7
}
  • AgentCore Memory Template: Provides templating for Memory configurations. Enables creating Memory configuration templates, creating Memory from templates, sharing and importing templates, and version control.
{
  "operation": "create_template",
  "template_name": "customer-support-template",
  "description": "Standard template for customer support",
  "memory_config": {
    "retention_days": 90,
    "max_events": 10000,
    "enable_search": true
  },
  "tags": {
    "Type": "support",
    "Version": "1.0"
  }
}
{
  "operation": "create_from_template",
  "template_id": "template-abc123",
  "memory_name": "support-team-a-memory",
  "override_config": {
    "retention_days": 180
  }
}
  • AgentCore Code Interpreter Files: Manages Code Interpreter files. Enables file upload (local/Base64), retrieving files from execution results, listing files (with filtering and sorting), and deleting files (single/batch), with file size limit (100MB) and security checks implemented.
{
  "operation": "upload",
  "session_id": "session-abc123",
  "file_path": "/path/to/data.csv",
  "file_name": "data.csv",
  "description": "Data for analysis"
}
{
  "operation": "list",
  "session_id": "session-abc123",
  "filter_extension": ".csv",
  "sort_by": "upload_time",
  "sort_order": "desc"
}
  • AgentCore Memory Search Advanced: Extends Memory Search functionality. Enables adding filter conditions (time range, Actor ID, Session ID, Namespace), specifying sort order (relevance, timestamp), pagination (max 100 items/page), highlight feature (customizable), and context extraction.
{
  "memory_id": "mem-abc123",
  "query": "Error handling",
  "filter_actor_id": "user001",
  "filter_start_time": "2025-01-01T00:00:00Z",
  "filter_end_time": "2025-01-31T23:59:59Z",
  "sort_by": "relevance",
  "page_size": 50,
  "enable_highlight": true,
  "context_size": 100
}
  • Agentcore Code Interpreter – Creates/uses an interpreter session to run shell commands or code.
{
  "operation": "execute",
  "code": "print(1+1)",
  "language": "python"
}
  • AgentCore Memory Search – Calls retrieve_memories for a memory/namespace with top_k limit.
{
  "memory_id": "mem-abc",
  "namespace": "default",
  "query": "error logs",
  "top_k": 5
}
  • AgentCore Memory – Creates memories and records/retrieves turns; supply operation=record or retrieve.
{
  "operation": "record",
  "memory_id": "mem-123",
  "actor_id": "user",
  "role": "user",
  "content": "Hello!"
}

Other Notes

  • Lambda YAML to JSON – Lightweight wrapper for reusing your Lambda workloads from workflows.

  • Lambda Invoker – Calls any Lambda function name or ARN with a JSON payload, optional qualifier, per-call credentials, and tail logs for quick serverless utilities.

{
  "lambda_name": "my-function",
  "payload_json": {"action": "ping"},
  "invocation_type": "RequestResponse",
  "include_logs": true
}
  • Step Functions Start Execution – Starts a state machine by ARN, passing execution input, optional name, trace header, and tags so agents can fan out or orchestrate long-running jobs.
{
  "state_machine_arn": "arn:aws:states:us-east-1:111122223333:stateMachine:MyFlow",
  "input_json": {"task": "sync"},
  "name": "run-001"
}
  • Get Credentials: Retrieves AWS credentials from boto3.Session. Returns access key, secret key, and session token in JSON format using the specified profile and region. If profile_name or region_name is not specified, it uses the AWS Credential Provider Chain (environment variables, ~/.aws/credentials, IAM roles, etc.) to obtain default credentials. When running on EC2 instances or ECS tasks, it can automatically retrieve temporary credentials from instance profiles or task roles.
{
  "profile_name": "development",
  "region_name": "ap-northeast-1"
}
{}

(Retrieve default credentials without parameters)

  • STS AssumeRole: Uses AWS STS to assume an IAM role and retrieve temporary credentials. Use this for cross-account access or privilege escalation. Supports advanced configurations such as MFA authentication, external ID, and session policies. The retrieved credentials are returned in a format compatible with the Get Credentials tool.
{
  "role_arn": "arn:aws:iam::123456789012:role/MyRole",
  "role_session_name": "DifySession",
  "duration_seconds": 3600
}
{
  "role_arn": "arn:aws:iam::123456789012:role/CrossAccountRole",
  "role_session_name": "CrossAccountSession",
  "external_id": "unique-external-id-123",
  "serial_number": "arn:aws:iam::123456789012:mfa/user",
  "token_code": "123456"
}

Privacy Policy

The plugin is designed to interact with AWS services (such as Bedrock, Lambda, S3, and DynamoDB) on your behalf. It does not collect analytics or telemetry beyond what is required to fulfill the tool invocations you issue.

Data Collection

  • User-supplied inputs. Text prompts, speech/audio URLs, translation requests, Lambda payloads, and other parameters that you pass to the tools are sent to the corresponding AWS service only for the purpose of executing that tool invocation.
  • Configuration metadata. Optional AWS credentials (access key, secret key, region) may be provided either at the provider level or per tool. These values stay within the plugin runtime and are forwarded solely to AWS SDK clients to authenticate requests.
  • Generated outputs. Responses received from AWS (e.g., Bedrock retrieve results or other tool outputs) are returned directly to Dify and are not stored elsewhere by this plugin.
  • The plugin does not collect personally identifiable information unless included in the data that you explicitly send to the tools.

Data Usage

  • Inputs are transmitted to AWS services strictly to execute the selected tool (e.g., running Transcribe, retrieving from Bedrock KB, generating Nova images/videos, reranking documents).
  • Outputs from AWS are returned to the Dify workflow or agent as-is. No secondary processing or analysis is performed beyond light formatting necessary for the Dify UI.
  • The plugin does not sell, share, or reuse your data for any other purpose. Data is not used for model training by this plugin.

Data Storage

  • By default, the plugin does not store any user inputs or outputs on its own disk.
  • Temporary files (e.g., downloaded GIFs for frame extraction) are written to local storage only for the duration of the request and deleted immediately after completion.
  • Any persistent storage happens only when you instruct a tool to do so (e.g., writing a file to S3 or DynamoDB via the respective tools). In such cases the data resides in your AWS account under the resources you control.

Third-party Services

  • The plugin communicates exclusively with AWS services using the official AWS SDK (boto3) and, for browser automation, the Bedrock AgentCore Browser service plus Playwright. No other third-party APIs are contacted.
  • When using OpenSearch, SageMaker, Bedrock, Lambda, Transcribe, Comprehend, S3, or DynamoDB tools, the data is transmitted directly to those AWS endpoints over HTTPS.
  • Browser tooling stores connection metadata (WebSocket URLs, headers) in AWS Systems Manager Parameter Store in your account so that sessions can be reused. These parameters contain no additional user data beyond what is required to connect.

Security

  • All network calls to AWS services use HTTPS, and AWS credentials are loaded into boto3 clients only when needed. If you provide credentials via the provider settings, they remain in memory within the plugin runtime and are not persisted.
  • Parameter Store entries created for AgentCore Browser sessions are stored in your AWS account and inherit the IAM policies you configure.
  • The browser tool caches Playwright sessions in memory only for the life of the plugin process and cleans up resources when sessions are closed.
  • Temporary files for media processing are stored under the plugin workspace with restrictive permissions and are deleted after each request.
  • It is your responsibility to secure your AWS resources (IAM policies, S3 bucket ACLs, DynamoDB tables, etc.). The plugin will operate with whatever permissions the provided credentials allow.