Add JavaScript SDK API reference with vector storage get method documentation #249
Conversation
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
…entation - Create comprehensive API reference for JavaScript SDK - Add missing get() method documentation for vector storage - Include method signature, parameters, return value, and usage examples - Document how to retrieve full document content after vector search operations Co-Authored-By: jwalkow@agentuity.com <jwalkow@agentuity.com>
🤖 Devin AI EngineerI'll be helping with this pull request! Here's what you should know: ✅ I will automatically:
Note: I can only respond to comments from users who have write access to this repository. ⚙️ Control Options:
|
WalkthroughA new, detailed API reference document for the Agentuity JavaScript SDK has been added. It describes the SDK's core interfaces, including agent context, key-value storage, vector storage, request and response objects, and TypeScript types for vector operations, along with usage examples and interface specifications. Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant AgentContext
participant KVStorage
participant VectorStorage
User->>AgentContext: Access SDK interfaces
AgentContext->>KVStorage: get/set/delete key-value
AgentContext->>VectorStorage: upsert/get/search/delete vectors
User->>AgentContext: Make request/response via AgentRequest/AgentResponse
Estimated code review effort🎯 2 (Simple) | ⏱️ ~8 minutes Possibly related PRs
Suggested reviewers
Poem
📜 Recent review detailsConfiguration used: CodeRabbit UI 📒 Files selected for processing (1)
🧰 Additional context used🧠 Learnings (2)📓 Common learningssource.config.ts (5)Learnt from: CR Learnt from: CR Learnt from: CR Learnt from: CR Learnt from: CR ⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
🔇 Additional comments (3)
✨ Finishing Touches
🧪 Generate unit tests
🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
Deploying with
|
| Status | Name | Latest Commit | Updated (UTC) |
|---|---|---|---|
| ❌ Deployment failed View logs |
docs | fb2e52d | Jul 28 2025, 03:09 PM |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
content/docs/SDKs/javascript/api-reference.mdx (2)
92-99: Example silently relies on implicit array → rest conversion
upsertis documented as accepting...documents(rest parameter) yet the example passes a single object, not an array.
Readers may be confused about whether multiple documents must be wrapped in an array.Consider showing an explicit spread example or adding a note:
await context.vector.upsert('my-docs', { key: 'doc-1', document: '...', metadata: { category: 'example' } }, { key: 'doc-2', document: '...', metadata: { category: 'example' } } );
245-251:Jsontype is referenced but never defined in this pageAll method signatures use the opaque
Jsonalias. Either:
- Add a short blurb defining
type Json = unknown; // SDK internal JSON-serialisable value, or- Link to the existing definition in the global types section of the docs.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
content/docs/SDKs/javascript/api-reference.mdx(1 hunks)
🧰 Additional context used
🧠 Learnings (2)
📓 Common learnings
Learnt from: CR
PR: agentuity/docs#0
File: agent-docs/.cursor/rules/sdk.mdc:0-0
Timestamp: 2025-07-23T12:40:34.834Z
Learning: Applies to agent-docs/src/agents/**/*.ts : Import types from '@agentuity/sdk'
Learnt from: CR
PR: agentuity/docs#0
File: agent-docs/.cursor/rules/agent.mdc:0-0
Timestamp: 2025-07-23T12:40:22.412Z
Learning: Applies to agent-docs/**/src/agents/**/index.ts : Prefer loading types from the node modules package `@agentuity/sdk` in the node_modules folder
Learnt from: CR
PR: agentuity/docs#0
File: agent-docs/.cursor/rules/sdk.mdc:0-0
Timestamp: 2025-07-23T12:40:34.834Z
Learning: Applies to agent-docs/src/agents/**/*.ts : Use the storage APIs for persisting data
Learnt from: CR
PR: agentuity/docs#0
File: agent-docs/.cursor/rules/sdk.mdc:0-0
Timestamp: 2025-07-23T12:40:34.834Z
Learning: Applies to agent-docs/src/agents/**/*.ts : Use TypeScript for better type safety and IDE support
Learnt from: CR
PR: agentuity/docs#0
File: agent-docs/.cursor/rules/agent.mdc:0-0
Timestamp: 2025-07-23T12:40:22.412Z
Learning: Applies to agent-docs/**/src/agents/**/index.ts : Prefer naming the default function Agent or the name of the Agent based on the context of the Agent description
Learnt from: CR
PR: agentuity/docs#0
File: agent-docs/.cursor/rules/sdk.mdc:0-0
Timestamp: 2025-07-23T12:40:34.834Z
Learning: Applies to agent-docs/src/agents/**/*.ts : Consider agent communication for complex workflows
Learnt from: afterrburn
PR: agentuity/docs#208
File: agent-docs/src/agents/doc-qa/retriever.ts:46-51
Timestamp: 2025-06-28T15:55:43.334Z
Learning: In Agentuity vector search API, the query parameter cannot be an empty string as it would throw an error. When performing metadata-only searches (like retrieving all chunks for a specific document path), a single space ' ' can be used as a workaround since the API requires a non-empty query string.
Learnt from: CR
PR: agentuity/docs#0
File: agent-docs/.cursor/rules/agent.mdc:0-0
Timestamp: 2025-07-23T12:40:22.412Z
Learning: Applies to agent-docs/**/src/agents/**/index.ts : All code should be in Typescript format
content/docs/SDKs/javascript/api-reference.mdx (8)
Learnt from: CR
PR: agentuity/docs#0
File: agent-docs/.cursor/rules/sdk.mdc:0-0
Timestamp: 2025-07-23T12:40:34.834Z
Learning: Applies to agent-docs/src/agents/**/*.ts : Import types from '@agentuity/sdk'
Learnt from: CR
PR: agentuity/docs#0
File: agent-docs/.cursor/rules/agent.mdc:0-0
Timestamp: 2025-07-23T12:40:22.412Z
Learning: Applies to agent-docs//src/agents//index.ts : Prefer loading types from the node modules package @agentuity/sdk in the node_modules folder
Learnt from: CR
PR: agentuity/docs#0
File: agent-docs/.cursor/rules/sdk.mdc:0-0
Timestamp: 2025-07-23T12:40:34.834Z
Learning: Applies to agent-docs/src/agents/**/*.ts : Use the storage APIs for persisting data
Learnt from: CR
PR: agentuity/docs#0
File: agent-docs/.cursor/rules/agent.mdc:0-0
Timestamp: 2025-07-23T12:40:22.412Z
Learning: Applies to agent-docs//src/agents//index.ts : Prefer naming the default function Agent or the name of the Agent based on the context of the Agent description
Learnt from: CR
PR: agentuity/docs#0
File: agent-docs/.cursor/rules/sdk.mdc:0-0
Timestamp: 2025-07-23T12:40:34.834Z
Learning: Applies to agent-docs/src/agents/**/*.ts : Use TypeScript for better type safety and IDE support
Learnt from: CR
PR: agentuity/docs#0
File: agent-docs/.cursor/rules/agent.mdc:0-0
Timestamp: 2025-07-23T12:40:22.412Z
Learning: Applies to agent-docs//src/agents//index.ts : The file should export a default function
Learnt from: CR
PR: agentuity/docs#0
File: agent-docs/.cursor/rules/sdk.mdc:0-0
Timestamp: 2025-07-23T12:40:34.834Z
Learning: Applies to agent-docs/src/agents/**/*.ts : Consider agent communication for complex workflows
Learnt from: CR
PR: agentuity/docs#0
File: agent-docs/.cursor/rules/agent.mdc:0-0
Timestamp: 2025-07-23T12:40:22.412Z
Learning: Applies to agent-docs//src/agents//index.ts : All code should be in Typescript format
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Workers Builds: docs
🔇 Additional comments (1)
content/docs/SDKs/javascript/api-reference.mdx (1)
101-110: Verifyvector.get()exists in the SDKI wasn’t able to locate a
VectorStorageinterface or anyget(name, key)method in the TypeScript/JavaScript sources. Before shipping these docs:
- Confirm that
VectorStorage.get(name, key)is implemented and exported in the published JavaScript SDK (npm package).- If it’s not yet released, either update this section to match the existing retrieval API or implement/release the missing
get()method.
| #### delete(name, ...ids) | ||
|
|
||
| Delete vectors from the vector storage. | ||
|
|
||
| **Parameters:** | ||
| - `name: string` - The name of the vector storage | ||
| - `ids: string[]` - Array of vector IDs to delete | ||
|
|
||
| **Returns:** `Promise<number>` - Number of vectors that were deleted |
There was a problem hiding this comment.
Parameter description for vector.delete() contradicts the signature
The signature is shown as delete(name, ...ids) (rest parameters), yet the parameter list describes a single argument ids: string[].
Either change the bullet to reflect a rest-parameter or adjust the signature to accept an array, but they must match.
- - `ids: string[]` - Array of vector IDs to delete
+ - `...ids: string[]` – One or more vector IDs to delete📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| #### delete(name, ...ids) | |
| Delete vectors from the vector storage. | |
| **Parameters:** | |
| - `name: string` - The name of the vector storage | |
| - `ids: string[]` - Array of vector IDs to delete | |
| **Returns:** `Promise<number>` - Number of vectors that were deleted | |
| #### delete(name, ...ids) | |
| Delete vectors from the vector storage. | |
| **Parameters:** | |
| - `name: string` - The name of the vector storage | |
| - `...ids: string[]` – One or more vector IDs to delete | |
| **Returns:** `Promise<number>` - Number of vectors that were deleted |
🤖 Prompt for AI Agents
In content/docs/SDKs/javascript/api-reference.mdx around lines 148 to 156, the
parameter description for the delete method conflicts with its signature: the
signature uses rest parameters (...ids) but the description lists a single array
parameter (ids: string[]). To fix this, update the parameter description to
match the rest parameter style by describing ids as multiple string arguments
instead of a single array, or alternatively, change the method signature to
accept a single array parameter if that is the intended usage. Ensure both the
signature and parameter description are consistent.
- Move mdxOptions from defineDocs to defineConfig as per fumadocs API - Separate global configuration from collection definition - Resolves TypeScript compilation error in CI build Co-Authored-By: jwalkow@agentuity.com <jwalkow@agentuity.com>
|
Closing due to inactivity for more than 30 days. Configure here. |
Add JavaScript SDK API reference with vector storage get method documentation
Summary
This PR addresses the missing
getmethod documentation for vector storage in the JavaScript SDK. Based on the Slack conversation where Pedro demonstrated working code usingctx.vector.get(), I created a comprehensive JavaScript SDK API reference documentation file that includes:get()methodThe
getmethod allows developers to retrieve full document content after performing vector searches, which is essential for RAG (Retrieval-Augmented Generation) workflows.Review & Testing Checklist for Human
getmethod actually exists - Test thatctx.vector.get(name, key)works in a real agent (HIGH PRIORITY - I found this method was missing from the VectorStorage interface in the SDK code)Recommended test plan: Create a simple agent that uses vector.search() followed by vector.get() calls as shown in the documentation examples, and verify the complete workflow works as documented.
Diagram
%%{ init : { "theme" : "default" }}%% graph TD SlackConv["Slack Conversation<br/>(Pedro's working code)"]:::context ApiRef["content/docs/SDKs/javascript/<br/>api-reference.mdx"]:::major-edit VectorTS["sdk-js/src/apis/vector.ts<br/>(VectorAPI implementation)"]:::context TypesTS["sdk-js/src/types.ts<br/>(VectorStorage interface)"]:::context DocsIndex["content/docs/SDKs/index.mdx<br/>(links to JS SDK)"]:::context SlackConv -->|"get method missing from docs"| ApiRef VectorTS -->|"examined for method signatures"| ApiRef TypesTS -->|"checked interface definition"| ApiRef DocsIndex -->|"references /docs/SDKs/javascript"| ApiRef subgraph Legend L1[Major Edit]:::major-edit L2[Minor Edit]:::minor-edit L3[Context/No Edit]:::context end classDef major-edit fill:#90EE90 classDef minor-edit fill:#ADD8E6 classDef context fill:#FFFFFFNotes
getmethod is not defined in the VectorStorage interface in the SDK source code, despite Pedro's working example. This needs verification before merging.Summary by CodeRabbit