# I tested the new OpenSearch Agent Toolkit skill. Here's what it actually does. > Source: > Published: 2026-07-17 05:50:22+00:00 AWS [announced](https://aws.amazon.com/about-aws/whats-new/2026/07/amazon-opensearch-service-agent/) the `amazon-opensearch-service` skill for the Agent Toolkit for AWS on July 15, 2026. The marketing says it lets AI coding agents "build, manage, and query OpenSearch directly from natural language." I installed it and ran it through a real task: building a RAG search backend on Amazon OpenSearch Serverless NextGen from scratch. Here's what the skill actually does, where it saved me time, and the one area where skipping it entirely would have been faster. The skill is not a chatbot wrapper over AWS APIs. It's a **structured knowledge package** that loads into your coding agent's context when you ask an OpenSearch-related question. Think of it as a senior engineer's notebook: sizing formulas, engine selection logic, migration checklists, query DSL recipes. It covers both managed Amazon OpenSearch Service domains and OpenSearch Serverless collections ([full source on GitHub](https://github.com/aws/agent-toolkit-for-aws/tree/main/skills/specialized-skills/analytics-skills/amazon-opensearch-service)). It routes every request to one of five capabilities: | Capability | What it knows | |---|---| | Migration | Schema translation from Solr/ES, compatibility assessment, cutover planning | | Provisioning | Instance sizing math, shard calculations, storage tier selection, policy setup | | Search | k-NN engine selection (FAISS vs Lucene), hybrid search patterns, Amazon Bedrock connectors | | Log analytics | PPL queries, Ingestion pipelines, anomaly detection, dashboard patterns | | Trace analytics | OpenTelemetry spans, service maps, Data Prepper configuration | The provisioning capability works for both managed domains (instance families, JVM heap, OR1 trade-offs) and Serverless (collection groups, OCU limits, NextGen vs Classic). The search capability includes sizing math that differs between deployments: shard count formulas for managed domains, OCU memory rules for Serverless. See the [official documentation](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/amazon-opensearch-service-skill.html) for the full capability description. The skill comes as part of the [ aws-data-analytics plugin](https://github.com/aws/agent-toolkit-for-aws/tree/main/plugins/aws-data-analytics), which bundles 8 skills covering the full data lifecycle: | # | Skill | What it does | |---|---|---| | 1 | `creating-data-lake-table` | Managed Iceberg tables on Amazon S3 Tables | | 2 | `ingesting-into-data-lake` | Import from S3, JDBC, Snowflake, BigQuery, DynamoDB | | 3 | `querying-data-lake` | Athena SQL across default and federated catalogs | | 4 | `finding-data-lake-assets` | Resolve data references by name, keyword, column | | 5 | `exploring-data-catalog` | AWS Glue Data Catalog inventory and audit | | 6 | `storing-and-querying-vectors` | Amazon S3 Vectors for semantic search and RAG | | 7 | `connecting-to-data-source` | AWS Glue connections to JDBC, Redshift, Snowflake | | 8 | `amazon-opensearch-service` | Migration, provisioning, search, logs, traces | Note skill #6: the plugin includes an Amazon S3 Vectors skill too. It covers vector bucket creation, index setup, and query patterns for RAG workloads. Install in one step (full setup guide in the [Agent Toolkit docs](https://docs.aws.amazon.com/agent-toolkit/latest/userguide/quick-start.html)): ``` # Claude Code /plugin install aws-data-analytics@claude-plugins-official /reload-plugins # Codex codex plugin marketplace add aws/agent-toolkit-for-aws # Kiro — MCP config + skills # Add to ~/.kiro/settings/mcp.json: { "mcpServers": { "aws-mcp": { "command": "uvx", "args": ["mcp-proxy-for-aws@1.6.3", "https://aws-mcp.us-east-1.api.aws/mcp", "--metadata", "AWS_REGION=eu-central-1"] } } } # Then install skills: npx skills add aws/agent-toolkit-for-aws/skills # Or let AWS CLI detect your agent and configure everything: aws configure agent-toolkit ``` I asked my agent: *"Create an OpenSearch Serverless vector search collection with scale-to-zero, set up a hybrid search index for 1024-dimension Amazon Titan Embeddings G2, ingest 5 sample documents, and run a query."* Here's what happened step by step. The skill detected capability: **provisioning**, and recommended a NextGen collection group with zero minimum OCUs. It produced the correct sequence: ``` # 1. Collection group (NextGen, scale-to-zero) aws opensearchserverless create-collection-group \ --name agent-toolkit-demo \ --generation NEXTGEN \ --standby-replicas ENABLED \ --capacity-limits '{ "maxIndexingCapacityInOCU": 8, "maxSearchCapacityInOCU": 8, "minIndexingCapacityInOCU": 0, "minSearchCapacityInOCU": 0 }' # 2. Three mandatory policies (encryption, network, data access) # 3. Collection in the group aws opensearchserverless create-collection \ --name agent-demo \ --type VECTORSEARCH \ --collection-group-name agent-toolkit-demo ``` **What it got right:** The full policy chain (encryption → network → data access → collection), the NextGen generation flag, the `VECTORSEARCH` type, and the scale-to-zero capacity limits. Without the skill, agents often create Classic collections (no scale-to-zero) or forget the encryption policy (which silently blocks collection creation). **What it didn't do:** Create the collection for me. The skill produces the commands and explains the sequence, but execution still requires you (or the agent via the MCP Server's `call_aws` tool) to run them. It took about 4 minutes for the collection to become ACTIVE. When I asked for a hybrid search index, the skill detected capability: **search** and recommended this mapping: ``` index_body = { "settings": { "index": {"knn": True, "knn.algo_param.ef_search": 512} }, "mappings": { "properties": { "title": {"type": "text"}, "content": {"type": "text"}, "category": {"type": "keyword"}, "embedding": { "type": "knn_vector", "dimension": 1024, "method": { "engine": "faiss", "name": "hnsw", "space_type": "l2", "parameters": {"ef_construction": 512, "m": 16} } } } } } ``` **This fails on NextGen Serverless** with `illegal_argument_exception: Field parameter 'engine' is not supported` . NextGen collections use their own managed vector acceleration (automatically enabled at collection creation as `ServerlessVectorAcceleration: ENABLED` ). You can't specify the engine. The correct mapping for NextGen: ``` index_body = { "settings": {"index": {"knn": True}}, "mappings": { "properties": { "title": {"type": "text"}, "content": {"type": "text"}, "category": {"type": "keyword"}, "embedding": { "type": "knn_vector", "dimension": 1024, "space_type": "cosinesimil" } } } } ``` **This is the skill's biggest gap right now.** It knows about Classic Serverless and managed domains (where FAISS/Lucene engine selection matters), but NextGen's simplified vector API isn't in the reference files yet. The skill was released the same week as the NextGen announcement, so this is likely a timing issue. The skill warned about two Serverless limitations: ``` # The skill correctly omitted the 'id' parameter client.index(index="articles", body={ "title": "Building RAG applications that actually work", "content": "The retrieval step matters more than the generation step...", "category": "ai", "embedding": embedding # 1024d from Titan G2 }) ``` On Classic Serverless, documents took 30-60 seconds to become searchable. On NextGen, **my documents were searchable in 2 seconds**. This is a massive improvement that AWS hasn't highlighted enough. The decoupled compute-storage architecture of NextGen means writes commit to the shared storage layer instantly and become queryable almost immediately. Vector search, keyword search, and filtered search all returned correct results. The skill produced working query DSL for each mode. For hybrid search (BM25 + vector), the skill noted that OpenSearch Serverless requires a **search pipeline with a normalization processor** for native hybrid queries, or you can implement client-side Reciprocal Rank Fusion (RRF). It recommended client-side RRF for simplicity: ``` python def hybrid_search(query_text, k=3): query_embedding = generate_embedding(query_text) # Vector results vec = client.search(index="articles", body={ "size": k, "query": {"knn": {"embedding": {"vector": query_embedding, "k": k}}} })["hits"]["hits"] # BM25 results kw = client.search(index="articles", body={ "size": k, "query": {"multi_match": {"query": query_text, "fields": ["title^2", "content"]}} })["hits"]["hits"] # Reciprocal Rank Fusion rrf_k, scores, docs = 60, {}, {} for rank, hit in enumerate(vec): scores[hit["_id"]] = scores.get(hit["_id"], 0) + 1.0 / (rrf_k + rank + 1) docs[hit["_id"]] = hit for rank, hit in enumerate(kw): scores[hit["_id"]] = scores.get(hit["_id"], 0) + 1.0 / (rrf_k + rank + 1) docs[hit["_id"]] = hit return sorted(scores.items(), key=lambda x: x[1], reverse=True)[:k] ``` **Policy sequencing.** Three policies must exist before the collection. The skill knows the order and the exact permission set (including `aoss:DeleteIndex` , which you'll hit a 403 without during development). **Serverless-specific warnings.** No custom IDs, auth service name `"aoss"` , and the collection group requirement for NextGen. Each of these cost me 5-10 minutes to debug in my first attempt without the skill. **NextGen awareness.** The skill knew about collection groups, the `--generation NEXTGEN` flag, and scale-to-zero capacity limits. This is May 2026 knowledge that most agents don't have in their training data. **Engine selection for NextGen.** The skill recommended `"engine": "faiss"` which fails on NextGen with `illegal_argument_exception` . NextGen manages vector acceleration internally, you just specify `dimension` and `space_type` . This is the skill's biggest gap: the most recommended deployment target rejects the skill's default mapping. **Write latency expectations.** The skill warned about "30-60 second eventual consistency" which is true for Classic but wrong for NextGen (2 seconds in my test). NextGen's decoupled architecture makes writes visible almost immediately. The skill covers both Serverless and managed domains. I tested two questions against my existing managed domain (t3.small, single-node, OpenSearch 2.19). **Simple question: "Is my domain healthy? Should I upgrade?"** The skill detected capability: **provisioning** and produced a checklist: This was useful. The skill read the domain configuration and produced actionable recommendations, not generic advice. **Harder question: "I want to add vector search to this domain for a RAG use case with 500K documents. What do I need to change?"** The skill detected capability: **search** and routed to the vector/k-NN reference. It recommended: `m=16` , `ef_construction=256` for 500K vectors at 1024 dimensions.The skill then produced the correct index mapping (with `"engine": "faiss"` , which is valid for managed domains, just not for NextGen) and a Bedrock connector configuration for embedding generation at ingestion time. **Verdict on managed domain coverage:** the skill is more helpful for managed domains than for NextGen Serverless, because managed domains have more knobs to tune (instance types, shard math, JVM heap, storage sizing). The provisioning reference files were clearly written with managed domains as the primary target. I installed the `aws-cdk` and `aws-cloudformation` skills alongside the OpenSearch skill to test IaC output. Here's what each provides: `aws-cdk` `aws-cloudformation` `amazon-opensearch-service` In practice, your agent combines knowledge from multiple skills: the OpenSearch skill provides the *what* (r7g.large, 3 shards, FAISS HNSW, ef_construction=256), and the CDK skill provides the *how* (construct patterns, proper scoping, safe refactoring). But there's no pre-built bridge between them. You still ask "now write that as CDK" as a separate step. **Terraform is not covered at all.** No skill in the Agent Toolkit produces HCL. For Terraform users, the OpenSearch skill's sizing recommendations are still valuable, but you translate to HCL using the agent's general training data. **Writing the application code.** The skill produces query DSL snippets and CLI commands, but it doesn't generate a complete Python application. You still write the Bedrock embedding calls, the opensearch-py client setup, the ingestion loop, and the search logic yourself. **Cost estimation.** The skill explicitly refuses to produce dollar figures. If you ask "how much will this cost?", it points you to the AWS Pricing Calculator and stops. This is by design: pricing changes monthly and account-specific discounts make generic estimates misleading. **Choosing between OpenSearch and alternatives.** The skill is scoped to OpenSearch. It won't tell you "actually, Amazon S3 Vectors would be 15x cheaper for your workload." That's your architecture decision. NextGen Serverless scales to zero after 10 minutes of inactivity. The first request after idle takes 10-30 seconds while compute provisions. For agentic workloads (burst of queries, then hours idle), this is the right trade-off: pay nothing during idle, accept the wake-up penalty. For workloads where cold starts are unacceptable: | Alternative | Cold start | Idle cost | Hybrid search | |---|---|---|---| NextGen with min 1 OCU | None | ~$175/month | Yes | Managed domain (t3.medium) | None | ~$53/month | Yes | S3 Vectors | None (always ready) | ~$0 | No (vector + filter only) | S3 Vectors deserves a separate mention: for pure vector retrieval without BM25 or complex filters, it's both faster (89ms p50 in my tests vs 109ms for the managed domain) and cheaper ($11/month for 10M vectors vs $175+ for Serverless). No cold start, no policies to configure. The `aws-data-analytics` plugin includes a `storing-and-querying-vectors` skill for S3 Vectors too, covering bucket creation, index setup, and query patterns. The trade-off: no hybrid search, 100 results max per query, flat metadata only (2 KB filterable). The combination that makes the most sense for production: **S3 Vectors for the primary vector store** (cheap, fast, scales to billions) **+ a small OpenSearch domain for the hybrid re-ranking step** when you need keyword precision on top of semantic recall. The full sequence from zero to working RAG search on NextGen Serverless: ``` # Prerequisites pip install opensearch-py boto3 requests-aws4auth # 1. Collection group (NextGen, scale-to-zero) aws opensearchserverless create-collection-group \ --name my-rag-demo --generation NEXTGEN \ --standby-replicas ENABLED \ --capacity-limits '{"maxIndexingCapacityInOCU":8,"maxSearchCapacityInOCU":8, "minIndexingCapacityInOCU":0,"minSearchCapacityInOCU":0}' # 2. Policies (all three required before collection) aws opensearchserverless create-security-policy --name my-enc --type encryption \ --policy '{"Rules":[{"ResourceType":"collection","Resource":["collection/my-rag"]}],"AWSOwnedKey":true}' aws opensearchserverless create-security-policy --name my-net --type network \ --policy '[{"Rules":[{"ResourceType":"collection","Resource":["collection/my-rag"]}, {"ResourceType":"dashboard","Resource":["collection/my-rag"]}],"AllowFromPublic":true}]' aws opensearchserverless create-access-policy --name my-access --type data \ --policy '[{"Rules":[ {"ResourceType":"collection","Resource":["collection/my-rag"], "Permission":["aoss:*"]}, {"ResourceType":"index","Resource":["index/my-rag/*"], "Permission":["aoss:*"]}], "Principal":["arn:aws:iam::YOUR_ACCOUNT:role/YOUR_ROLE"]}]' # 3. Collection aws opensearchserverless create-collection \ --name my-rag --type VECTORSEARCH \ --collection-group-name my-rag-demo # 4. Wait for ACTIVE (~4 minutes), then create index + ingest via Python ``` **Yes, if** you're working with OpenSearch regularly and want your agent to produce correct configurations on the first try. The policy sequencing, engine selection, and Serverless-specific gotchas alone save 30+ minutes of debugging per project. **No, if** you're doing pure vector search without hybrid/BM25 needs. In that case, Amazon S3 Vectors is simpler, cheaper, faster, and has its own lightweight skill (`storing-and-querying-vectors` ) that covers the basics. The broader pattern: **Agent Toolkit skills are most valuable where the service has high configuration complexity.** OpenSearch has dozens of knobs (instance types, shard counts, engines, storage tiers, three policy types, collection groups). The OpenSearch skill reflects that complexity with 5 capabilities and a library of reference files. The S3 Vectors skill is simpler because the service is simpler. NextGen scales to zero, so leaving it idle costs only storage. To fully remove: ``` aws opensearchserverless delete-collection --id YOUR_COLLECTION_ID aws opensearchserverless delete-collection-group --id YOUR_GROUP_ID aws opensearchserverless delete-security-policy --name my-enc --type encryption aws opensearchserverless delete-security-policy --name my-net --type network aws opensearchserverless delete-access-policy --name my-access --type data ``` **Links:** *Tested July 2026 in eu-central-1 with OpenSearch Serverless NextGen, Amazon Titan Embeddings G2, and the Agent Toolkit for AWS (aws-data-analytics plugin). Cold-start measurement based on AWS documentation (10-30 seconds from zero). S3 Vectors latency measured from Python client in the same region.*