@nebulaos/aws-knowledge-base-skill

AWS Knowledge Base skill for NebulaOS agents. Retrieves from an Amazon Bedrock Knowledge Base configured in NebulaOS Cloud — your documents, your vector store, your AWS account.

Use this instead of @nebulaos/rag-openai-skill when data residency or compliance requires that documents never leave AWS.

Features

• 🔍 Retrieval from Amazon Bedrock Knowledge Bases
• 🔐 AWS credentials stored as workspace variables, never in the agent code
• 🎯 Automatic tool registration
• 🧭 Metadata filtering and search-strategy control
• 📎 Source document name on every result

Installation

npm install @nebulaos/aws-knowledge-base-skill

Quick Start

1. Store your AWS credentials as workspace variables

In the NebulaOS dashboard, under Variables, create:

| Name | Type | |---|---| | AWS_ACCESS_KEY_ID | variable | | AWS_SECRET_ACCESS_KEY | secret |

2. Create a connection in NebulaOS Cloud

1. Navigate to /ai-features/aws-knowledge-base
2. Click "New Connection"
3. Configure:
   • Connection name: e.g., "Clinical Protocols KB"
   • Knowledge Base ID (e.g. ABCD1234EF) and AWS region
   • Credentials: pick the two variables you created above
   • Search settings (maxResults, minScore, searchType)
4. Save and copy the Connection ID

3. Use in your agent

import { Agent, InMemory } from "@nebulaos/core";
import { OpenAI } from "@nebulaos/openai";
import { AwsKnowledgeBaseSkill } from "@nebulaos/aws-knowledge-base-skill";

const agent = new Agent({
  id: "protocol-agent",
  name: "Protocol Agent",
  model: new OpenAI({ model: "gpt-4" }),
  memory: new InMemory(),
  instructions: "You are a clinical protocol assistant.",

  skills: [
    new AwsKnowledgeBaseSkill({
      connectionId: "conn-xyz789",
    })
  ]
});

const result = await agent.execute("What is the protocol for acute chest pain?");
console.log(result.content);

Configuration

AwsKnowledgeBaseSkillConfig

| Option | Type | Default | Description | |---|---|---|---| | connectionId | string | — | Required. Connection ID from NebulaOS Cloud | | apiKey | string | from client | Deprecated — obtained automatically from the NebulaClient | | apiEndpoint | string | from client | NebulaOS Cloud URL | | maxResults | number | connection default | 1–100 (Bedrock's numberOfResults range) | | minScore | number | connection default | Score floor, applied after retrieval — see below | | searchType | "HYBRID" \| "SEMANTIC" | connection default | Search strategy override | | filter | object | connection default | Bedrock RetrievalFilter | | timeout | number | 30000 | Request timeout in ms |

Anything you leave unset falls through to the connection's stored default, so the usual setup is to configure defaults once in the dashboard and pass only connectionId here.

Metadata filtering

Scope retrieval with any Bedrock RetrievalFilter:

new AwsKnowledgeBaseSkill({
  connectionId: "conn-xyz789",
  filter: {
    andAll: [
      { equals: { key: "specialty", value: "cardiology" } },
      { greaterThanOrEquals: { key: "year", value: 2024 } },
    ],
  },
});

The filter keys must exist as attributes in your data source's .metadata.json files.

About minScore

Bedrock has no score threshold of its own — the platform filters after retrieval. Two consequences:

1. Under HYBRID search the scores are rank-fusion values, not 0–1 similarities. A threshold tuned for cosine similarity will silently discard every result.
2. The response includes totalBeforeFilter, so you can tell "the knowledge base had nothing" apart from "my threshold ate everything".

Start with no minScore and raise it only after inspecting real scores in the dashboard's Query Tester.

About searchType

HYBRID only works when the knowledge base is backed by an OpenSearch Serverless vector store with a filterable text field. Every other vector store supports SEMANTIC only and rejects HYBRID with a validation error. Leaving it unset lets Bedrock choose, which is the safe default.

Required IAM policy

The credentials behind the connection need exactly one action — nothing more:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "bedrock:Retrieve",
      "Resource": "arn:aws:bedrock:<region>:<account-id>:knowledge-base/<kb-id>"
    }
  ]
}

License

PROPRIETARY — StaryaAI