diff --git a/api/src/main/java/org/apache/flink/agents/api/resource/ResourceName.java b/api/src/main/java/org/apache/flink/agents/api/resource/ResourceName.java index e4002be7c..0d6ee413e 100644 --- a/api/src/main/java/org/apache/flink/agents/api/resource/ResourceName.java +++ b/api/src/main/java/org/apache/flink/agents/api/resource/ResourceName.java @@ -59,6 +59,12 @@ public static final class ChatModel { public static final String AZURE_SETUP = "org.apache.flink.agents.integrations.chatmodels.azureai.AzureAIChatModelSetup"; + // Bedrock + public static final String BEDROCK_CONNECTION = + "org.apache.flink.agents.integrations.chatmodels.bedrock.BedrockChatModelConnection"; + public static final String BEDROCK_SETUP = + "org.apache.flink.agents.integrations.chatmodels.bedrock.BedrockChatModelSetup"; + // Ollama public static final String OLLAMA_CONNECTION = "org.apache.flink.agents.integrations.chatmodels.ollama.OllamaChatModelConnection"; @@ -131,6 +137,12 @@ public static final class EmbeddingModel { public static final String OLLAMA_SETUP = "org.apache.flink.agents.integrations.embeddingmodels.ollama.OllamaEmbeddingModelSetup"; + // Bedrock + public static final String BEDROCK_CONNECTION = + "org.apache.flink.agents.integrations.embeddingmodels.bedrock.BedrockEmbeddingModelConnection"; + public static final String BEDROCK_SETUP = + "org.apache.flink.agents.integrations.embeddingmodels.bedrock.BedrockEmbeddingModelSetup"; + // Python Wrapper public static final String PYTHON_WRAPPER_CONNECTION = "org.apache.flink.agents.api.embedding.model.python.PythonEmbeddingModelConnection"; @@ -171,6 +183,14 @@ public static final class VectorStore { public static final String ELASTICSEARCH_VECTOR_STORE = "org.apache.flink.agents.integrations.vectorstores.elasticsearch.ElasticsearchVectorStore"; + // Amazon OpenSearch (Serverless or Service domains) + public static final String OPENSEARCH_VECTOR_STORE = + "org.apache.flink.agents.integrations.vectorstores.opensearch.OpenSearchVectorStore"; + + // Amazon S3 Vectors + public static final String S3_VECTORS_VECTOR_STORE = + "org.apache.flink.agents.integrations.vectorstores.s3vectors.S3VectorsVectorStore"; + // Python Wrapper public static final String PYTHON_WRAPPER_VECTOR_STORE = "org.apache.flink.agents.api.vectorstores.python.PythonVectorStore"; diff --git a/docs/content/docs/development/chat_models.md b/docs/content/docs/development/chat_models.md index 99ac9d7e5..1a735c3e8 100644 --- a/docs/content/docs/development/chat_models.md +++ b/docs/content/docs/development/chat_models.md @@ -961,6 +961,103 @@ Some popular options include: Model availability and specifications may change. Always check the official DashScope documentation for the latest information before implementing in production. {{< /hint >}} +### Amazon Bedrock + +Amazon Bedrock provides access to a wide range of foundation models from leading AI providers through a unified API. The Flink Agents Bedrock integration uses the [Converse API](https://docs.aws.amazon.com/bedrock/latest/userguide/conversation-inference.html), which provides a consistent interface across all supported models with native tool calling support. Authentication is handled via SigV4 using the AWS default credentials chain — no API keys required. + +{{< hint info >}} +Amazon Bedrock is only supported in Java currently. To use Amazon Bedrock from Python agents, see [Using Cross-Language Providers](#using-cross-language-providers). +{{< /hint >}} + +#### Prerequisites + +1. An AWS account with [Amazon Bedrock model access](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access.html) enabled for the models you plan to use +2. IAM credentials configured via any method supported by the [AWS Default Credentials Provider](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/credentials-chain.html) (environment variables, `~/.aws/credentials`, IAM role, etc.) + +#### BedrockChatModelConnection Parameters + +{{< tabs "BedrockChatModelConnection Parameters" >}} + +{{< tab "Java" >}} + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `region` | String | `"us-east-1"` | AWS region for the Bedrock service | +| `model` | String | None | Default model ID (can be overridden per setup) | +| `max_retries` | int | `5` | Maximum number of API retry attempts (retries on throttling, 429, 503) | + +{{< /tab >}} + +{{< /tabs >}} + +#### BedrockChatModelSetup Parameters + +{{< tabs "BedrockChatModelSetup Parameters" >}} + +{{< tab "Java" >}} + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `connection` | String | Required | Reference to connection method name | +| `model` | String | Required | Bedrock model ID (e.g. `"us.anthropic.claude-sonnet-4-20250514-v1:0"`) | +| `prompt` | Prompt \| String | None | Prompt template or reference to prompt resource | +| `tools` | List | None | List of tool names available to the model | +| `temperature` | double | `0.1` | Sampling temperature (0.0 to 1.0) | +| `max_tokens` | int | None | Maximum number of tokens to generate | + +{{< /tab >}} + +{{< /tabs >}} + +#### Usage Example + +{{< tabs "Amazon Bedrock Usage Example" >}} + +{{< tab "Java" >}} +```java +public class MyAgent extends Agent { + @ChatModelConnection + public static ResourceDescriptor bedrockConnection() { + return ResourceDescriptor.Builder.newBuilder(ResourceName.ChatModel.BEDROCK_CONNECTION) + .addInitialArgument("region", "us-east-1") + .build(); + } + + @ChatModelSetup + public static ResourceDescriptor bedrockChatModel() { + return ResourceDescriptor.Builder.newBuilder(ResourceName.ChatModel.BEDROCK_SETUP) + .addInitialArgument("connection", "bedrockConnection") + .addInitialArgument("model", "us.anthropic.claude-sonnet-4-20250514-v1:0") + .addInitialArgument("temperature", 0.1d) + .addInitialArgument("max_tokens", 4096) + .build(); + } + + ... +} +``` +{{< /tab >}} + +{{< /tabs >}} + +#### Available Models + +Amazon Bedrock supports models from multiple providers through a single API. Visit the [Amazon Bedrock Model IDs documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/models-supported.html) for the complete and up-to-date list of available models. + +Some popular options include: +- **Claude** (Anthropic): `us.anthropic.claude-sonnet-4-6`, `us.anthropic.claude-opus-4-7`, `us.anthropic.claude-opus-4-6-v1` +- **Llama** (Meta): `us.meta.llama4-scout-17b-16e-instruct-v1:0` +- **Mistral**: `mistral.mistral-large-2402-v1:0` +- **Amazon Nova**: `us.amazon.nova-pro-v1:0`, `us.amazon.nova-lite-v1:0` + +{{< hint warning >}} +Model availability varies by AWS region and requires explicit model access enablement in the Bedrock console. Always check the [Amazon Bedrock documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/models-regions.html) for regional availability before implementing in production. +{{< /hint >}} + +{{< hint warning >}} +**Current limitations:** The integration uses text content blocks only. Extended thinking / reasoning content blocks (e.g. Claude extended thinking), citation blocks, and image / document content blocks are not yet supported. +{{< /hint >}} + ## Using Cross-Language Providers Flink Agents supports cross-language chat model integration, allowing you to use chat models implemented in one language (Java or Python) from agents written in the other language. This is particularly useful when a chat model provider is only available in one language (e.g., Tongyi is currently Python-only). diff --git a/docs/content/docs/development/embedding_models.md b/docs/content/docs/development/embedding_models.md index c23b796dc..6032cdc7c 100644 --- a/docs/content/docs/development/embedding_models.md +++ b/docs/content/docs/development/embedding_models.md @@ -464,6 +464,99 @@ Some popular options include: Model availability and specifications may change. Always check the official DashScope documentation for the latest information before implementing in production. {{< /hint >}} +### Amazon Bedrock + +Amazon Bedrock provides embedding capabilities through the Amazon Titan Text Embeddings V2 model via the [InvokeModel API](https://docs.aws.amazon.com/bedrock/latest/userguide/titan-embedding-models.html). The integration supports configurable output dimensions (256, 512, or 1024) and parallelizes batch embedding via a configurable thread pool, since the Titan V2 model processes one text per API call. Authentication is handled via SigV4 using the AWS default credentials chain. + +{{< hint info >}} +Amazon Bedrock embedding models are only supported in Java currently. To use Amazon Bedrock embeddings from Python agents, see [Using Cross-Language Providers](#using-cross-language-providers). +{{< /hint >}} + +#### Prerequisites + +1. An AWS account with [Amazon Bedrock model access](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access.html) enabled for Amazon Titan Text Embeddings V2 +2. IAM credentials configured via any method supported by the [AWS Default Credentials Provider](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/credentials-chain.html) + +#### BedrockEmbeddingModelConnection Parameters + +{{< tabs "BedrockEmbeddingModelConnection Parameters" >}} + +{{< tab "Java" >}} + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `region` | String | `"us-east-1"` | AWS region for the Bedrock service | +| `model` | String | `"amazon.titan-embed-text-v2:0"` | Default embedding model ID | +| `embed_concurrency` | int | `4` | Thread pool size for parallel batch embedding | +| `max_retries` | int | `5` | Maximum number of API retry attempts (retries on throttling, 429, 503) | + +{{< /tab >}} + +{{< /tabs >}} + +#### BedrockEmbeddingModelSetup Parameters + +{{< tabs "BedrockEmbeddingModelSetup Parameters" >}} + +{{< tab "Java" >}} + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `connection` | String | Required | Reference to connection method name | +| `model` | String | None | Override the default embedding model from the connection | +| `dimensions` | int | None | Output embedding dimensions: 256, 512, or 1024 | + +{{< /tab >}} + +{{< /tabs >}} + +#### Usage Example + +{{< tabs "Amazon Bedrock Embedding Usage Example" >}} + +{{< tab "Java" >}} +```java +public class MyAgent extends Agent { + + @EmbeddingModelConnection + public static ResourceDescriptor bedrockEmbeddingConnection() { + return ResourceDescriptor.Builder.newBuilder(ResourceName.EmbeddingModel.BEDROCK_CONNECTION) + .addInitialArgument("region", "us-east-1") + .addInitialArgument("embed_concurrency", 8) + .build(); + } + + @EmbeddingModelSetup + public static ResourceDescriptor bedrockEmbedding() { + return ResourceDescriptor.Builder.newBuilder(ResourceName.EmbeddingModel.BEDROCK_SETUP) + .addInitialArgument("connection", "bedrockEmbeddingConnection") + .addInitialArgument("model", "amazon.titan-embed-text-v2:0") + .addInitialArgument("dimensions", 1024) + .build(); + } + + ... +} +``` +{{< /tab >}} + +{{< /tabs >}} + +#### Available Models + +The Bedrock embedding integration currently supports: +- **Amazon Titan Text Embeddings V2** (`amazon.titan-embed-text-v2:0`) — supports 256, 512, or 1024 dimensions + +{{< hint info >}} +The integration always requests **normalized** embeddings (unit vectors), which makes cosine similarity equivalent to dot product. If you need raw, un-normalized vectors, use a custom provider. +{{< /hint >}} + +Visit the [Amazon Bedrock Embedding Models documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/titan-embedding-models.html) for the latest information. + +{{< hint warning >}} +Model availability varies by AWS region and requires explicit model access enablement in the Bedrock console. Always check the [Amazon Bedrock documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/models-regions.html) for regional availability before implementing in production. +{{< /hint >}} + ## Using Cross-Language Providers Flink Agents supports cross-language embedding model integration, allowing you to use embedding models implemented in one language (Java or Python) from agents written in the other language. This is particularly useful when an embedding model provider is only available in one language (e.g., OpenAI embedding is currently Python-only). diff --git a/docs/content/docs/development/vector_stores.md b/docs/content/docs/development/vector_stores.md index decc9c0d0..9d4832b4f 100644 --- a/docs/content/docs/development/vector_stores.md +++ b/docs/content/docs/development/vector_stores.md @@ -642,6 +642,204 @@ public static ResourceDescriptor vectorStore() { {{< /tabs >}} +### Amazon OpenSearch + +[Amazon OpenSearch](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/) is a managed vector search service available in two flavors: OpenSearch Service (provisioned domains) and OpenSearch Serverless (AOSS). The Flink Agents integration supports both via a single `service_type` parameter, with IAM (SigV4) or basic authentication. + +{{< hint info >}} +Amazon OpenSearch is only supported in Java currently. To use Amazon OpenSearch from Python agents, see [Using Cross-Language Providers](#using-cross-language-providers). +{{< /hint >}} + +{{< hint info >}} +Amazon OpenSearch implements `CollectionManageableVectorStore`, enabling [Long-Term Memory]({{< ref "docs/development/memory/long_term_memory" >}}) support. Collections map to OpenSearch indices, with collection metadata stored in a dedicated `flink_agents_collection_metadata` index. +{{< /hint >}} + +#### Prerequisites + +1. Either an [OpenSearch Service](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/) provisioned domain with KNN enabled (version 2.x+), or an [OpenSearch Serverless](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/serverless.html) collection of type `VECTORSEARCH` +2. For IAM auth: IAM credentials configured via the [AWS Default Credentials Provider](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/credentials-chain.html) with appropriate access policies (or a Serverless data-access policy) +3. For basic auth (Service domains only): username and password for the OpenSearch domain + +#### OpenSearchVectorStore Parameters + +{{< tabs "OpenSearchVectorStore Parameters" >}} + +{{< tab "Java" >}} + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `embedding_model` | String | Required | Reference to embedding model resource name | +| `endpoint` | String | Required | OpenSearch endpoint URL (e.g. `https://my-domain.us-east-1.es.amazonaws.com` for a domain, or the `*.aoss.amazonaws.com` endpoint for Serverless) | +| `index` | String | Required | Default index name for document operations | +| `service_type` | String | `"serverless"` | OpenSearch flavor: `"serverless"` (AOSS) or `"domain"` (OpenSearch Service) | +| `auth` | String | `"iam"` | Authentication method: `"iam"` (SigV4) or `"basic"`. Basic auth is supported on Service domains only | +| `username` | String | None | Username for basic authentication (required if `auth=basic`) | +| `password` | String | None | Password for basic authentication (required if `auth=basic`) | +| `vector_field` | String | `"embedding"` | Name of the KNN vector field in the index | +| `content_field` | String | `"content"` | Name of the text content field in the index | +| `region` | String | `"us-east-1"` | AWS region | +| `dims` | int | `1024` | Vector dimensionality used when this integration creates an index | +| `max_bulk_mb` | int | `5` | Maximum bulk payload size in MB | + +{{< /tab >}} + +{{< /tabs >}} + +#### Usage Example + +{{< tabs "Amazon OpenSearch Usage Example" >}} + +{{< tab "Java" >}} + +For an OpenSearch Serverless (AOSS) collection with IAM auth (the default): + +```java +public class MyAgent extends Agent { + + @EmbeddingModelConnection + public static ResourceDescriptor bedrockEmbeddingConnection() { + return ResourceDescriptor.Builder.newBuilder(ResourceName.EmbeddingModel.BEDROCK_CONNECTION) + .addInitialArgument("region", "us-east-1") + .build(); + } + + @EmbeddingModelSetup + public static ResourceDescriptor bedrockEmbedding() { + return ResourceDescriptor.Builder.newBuilder(ResourceName.EmbeddingModel.BEDROCK_SETUP) + .addInitialArgument("connection", "bedrockEmbeddingConnection") + .addInitialArgument("dimensions", 1024) + .build(); + } + + @VectorStore + public static ResourceDescriptor opensearchStore() { + return ResourceDescriptor.Builder.newBuilder(ResourceName.VectorStore.OPENSEARCH_VECTOR_STORE) + .addInitialArgument("embedding_model", "bedrockEmbedding") + .addInitialArgument("endpoint", "https://abc123.us-east-1.aoss.amazonaws.com") + .addInitialArgument("index", "my-vectors") + // service_type defaults to "serverless"; auth defaults to "iam" + .addInitialArgument("dims", 1024) + .build(); + } + + ... +} +``` + +For an OpenSearch Service provisioned domain with IAM auth: + +```java +@VectorStore +public static ResourceDescriptor opensearchDomainStore() { + return ResourceDescriptor.Builder.newBuilder(ResourceName.VectorStore.OPENSEARCH_VECTOR_STORE) + .addInitialArgument("embedding_model", "bedrockEmbedding") + .addInitialArgument("endpoint", "https://my-domain.us-east-1.es.amazonaws.com") + .addInitialArgument("index", "my-vectors") + .addInitialArgument("service_type", "domain") + .addInitialArgument("auth", "iam") + .addInitialArgument("dims", 1024) + .build(); +} +``` + +For an OpenSearch Service domain with basic auth: + +```java +@VectorStore +public static ResourceDescriptor opensearchDomainBasicAuth() { + return ResourceDescriptor.Builder.newBuilder(ResourceName.VectorStore.OPENSEARCH_VECTOR_STORE) + .addInitialArgument("embedding_model", "bedrockEmbedding") + .addInitialArgument("endpoint", "https://my-domain.us-east-1.es.amazonaws.com") + .addInitialArgument("index", "my-vectors") + .addInitialArgument("service_type", "domain") + .addInitialArgument("auth", "basic") + .addInitialArgument("username", "admin") + .addInitialArgument("password", "your-password") + .addInitialArgument("dims", 1024) + .build(); +} +``` + +{{< /tab >}} + +{{< /tabs >}} + +### Amazon S3 Vectors + +[Amazon S3 Vectors](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-vectors.html) is a purpose-built vector storage service from Amazon S3 that provides native support for storing and querying vector embeddings with sub-second query performance. It uses the S3 Vectors SDK for PutVectors, QueryVectors, GetVectors, and DeleteVectors operations. + +{{< hint info >}} +Amazon S3 Vectors is only supported in Java currently. To use Amazon S3 Vectors from Python agents, see [Using Cross-Language Providers](#using-cross-language-providers). +{{< /hint >}} + +{{< hint warning >}} +Amazon S3 Vectors does **not** implement `CollectionManageableVectorStore`, so it does not support [Long-Term Memory]({{< ref "docs/development/memory/long_term_memory" >}}) features. It also does not support `size()` or get-all operations — explicit document IDs are required for `get()` and `delete()`. +{{< /hint >}} + +#### Prerequisites + +1. An [S3 Vectors vector bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-vectors-buckets.html) and vector index created in your AWS account +2. IAM credentials configured via the [AWS Default Credentials Provider](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/credentials-chain.html) with appropriate S3 Vectors permissions + +#### S3VectorsVectorStore Parameters + +{{< tabs "S3VectorsVectorStore Parameters" >}} + +{{< tab "Java" >}} + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `embedding_model` | String | Required | Reference to embedding model resource name | +| `vector_bucket` | String | Required | S3 Vectors bucket name | +| `vector_index` | String | Required | S3 Vectors index name within the bucket | +| `region` | String | `"us-east-1"` | AWS region | + +{{< /tab >}} + +{{< /tabs >}} + +#### Usage Example + +{{< tabs "Amazon S3 Vectors Usage Example" >}} + +{{< tab "Java" >}} + +```java +public class MyAgent extends Agent { + + @EmbeddingModelConnection + public static ResourceDescriptor bedrockEmbeddingConnection() { + return ResourceDescriptor.Builder.newBuilder(ResourceName.EmbeddingModel.BEDROCK_CONNECTION) + .addInitialArgument("region", "us-east-1") + .build(); + } + + @EmbeddingModelSetup + public static ResourceDescriptor bedrockEmbedding() { + return ResourceDescriptor.Builder.newBuilder(ResourceName.EmbeddingModel.BEDROCK_SETUP) + .addInitialArgument("connection", "bedrockEmbeddingConnection") + .addInitialArgument("dimensions", 1024) + .build(); + } + + @VectorStore + public static ResourceDescriptor s3VectorsStore() { + return ResourceDescriptor.Builder.newBuilder(ResourceName.VectorStore.S3_VECTORS_VECTOR_STORE) + .addInitialArgument("embedding_model", "bedrockEmbedding") + .addInitialArgument("vector_bucket", "my-vector-bucket") + .addInitialArgument("vector_index", "my-index") + .addInitialArgument("region", "us-east-1") + .build(); + } + + ... +} +``` + +{{< /tab >}} + +{{< /tabs >}} + ## Using Cross-Language Providers Flink Agents supports cross-language vector store integration, allowing you to use vector stores implemented in one language (Java or Python) from agents written in the other language. This is particularly useful when a vector store provider is only available in one language (e.g., Elasticsearch is currently Java-only, Chroma is currently Python-only). diff --git a/python/flink_agents/api/resource.py b/python/flink_agents/api/resource.py index f8d7741a0..f481edcf1 100644 --- a/python/flink_agents/api/resource.py +++ b/python/flink_agents/api/resource.py @@ -276,6 +276,10 @@ class Java: AZURE_CONNECTION = "org.apache.flink.agents.integrations.chatmodels.azureai.AzureAIChatModelConnection" AZURE_SETUP = "org.apache.flink.agents.integrations.chatmodels.azureai.AzureAIChatModelSetup" + # Bedrock + BEDROCK_CONNECTION = "org.apache.flink.agents.integrations.chatmodels.bedrock.BedrockChatModelConnection" + BEDROCK_SETUP = "org.apache.flink.agents.integrations.chatmodels.bedrock.BedrockChatModelSetup" + # Ollama OLLAMA_CONNECTION = "org.apache.flink.agents.integrations.chatmodels.ollama.OllamaChatModelConnection" OLLAMA_SETUP = "org.apache.flink.agents.integrations.chatmodels.ollama.OllamaChatModelSetup" @@ -313,6 +317,10 @@ class Java: OLLAMA_CONNECTION = "org.apache.flink.agents.integrations.embeddingmodels.ollama.OllamaEmbeddingModelConnection" OLLAMA_SETUP = "org.apache.flink.agents.integrations.embeddingmodels.ollama.OllamaEmbeddingModelSetup" + # Bedrock + BEDROCK_CONNECTION = "org.apache.flink.agents.integrations.embeddingmodels.bedrock.BedrockEmbeddingModelConnection" + BEDROCK_SETUP = "org.apache.flink.agents.integrations.embeddingmodels.bedrock.BedrockEmbeddingModelSetup" + class VectorStore: """VectorStore resource names.""" @@ -331,5 +339,11 @@ class Java: # Elasticsearch ELASTICSEARCH_VECTOR_STORE = "org.apache.flink.agents.integrations.vectorstores.elasticsearch.ElasticsearchVectorStore" + # Amazon OpenSearch (Serverless or Service domains) + OPENSEARCH_VECTOR_STORE = "org.apache.flink.agents.integrations.vectorstores.opensearch.OpenSearchVectorStore" + + # Amazon S3 Vectors + S3_VECTORS_VECTOR_STORE = "org.apache.flink.agents.integrations.vectorstores.s3vectors.S3VectorsVectorStore" + # MCP resource names MCP_SERVER = "flink_agents.integrations.mcp.mcp.MCPServer"