From 5735c5ba0d8ace4e3c8a681790104a25dd7c7730 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Mon, 28 Jul 2025 14:58:12 +0000 Subject: [PATCH 1/2] Add JavaScript SDK API reference with vector storage get method documentation - 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 --- .../docs/SDKs/javascript/api-reference.mdx | 279 ++++++++++++++++++ 1 file changed, 279 insertions(+) create mode 100644 content/docs/SDKs/javascript/api-reference.mdx diff --git a/content/docs/SDKs/javascript/api-reference.mdx b/content/docs/SDKs/javascript/api-reference.mdx new file mode 100644 index 00000000..ae57db6b --- /dev/null +++ b/content/docs/SDKs/javascript/api-reference.mdx @@ -0,0 +1,279 @@ +--- +title: JavaScript SDK API Reference +description: Complete API reference for the Agentuity JavaScript SDK +--- + +# JavaScript SDK API Reference + +The Agentuity JavaScript SDK provides a comprehensive set of APIs for building AI agents that can process diverse inputs, communicate with each other, and integrate with external services. + +## Agent Context + +The `AgentContext` object provides access to platform services and is available as the third parameter in all agent handler functions. + +### Properties + +- `sdkVersion: string` - The version of the Agentuity SDK +- `devmode: boolean` - Returns true if the agent is running in development mode +- `runId: string` - Unique identifier for the current execution +- `orgId: string` - Organization identifier +- `deploymentId: string` - Deployment identifier +- `projectId: string` - Project identifier +- `agent: AgentConfig` - Agent configuration +- `logger: Logger` - Logging interface +- `tracer: Tracer` - OpenTelemetry tracer +- `agents: ServerAgent[]` - List of all agents in the project +- `kv: KeyValueStorage` - Key-value storage interface +- `vector: VectorStorage` - Vector storage interface + +### Methods + +#### getAgent(params) + +Get a handle to a remote agent that you can invoke. + +**Parameters:** +- `params: GetAgentRequestParams` - Agent identification parameters + +**Returns:** `Promise` + +## Key-Value Storage + +The key-value storage API provides persistent storage with GZIP compression and TTL support. + +### Methods + +#### get(key, defaultValue?) + +Retrieve a value from key-value storage. + +**Parameters:** +- `key: string` - The key to retrieve +- `defaultValue?: Json` - Optional default value if key doesn't exist + +**Returns:** `Promise` + +#### set(key, value, ttl?) + +Store a value in key-value storage. + +**Parameters:** +- `key: string` - The key to store +- `value: Json` - The value to store +- `ttl?: number` - Optional time-to-live in seconds + +**Returns:** `Promise` + +#### delete(key) + +Delete a value from key-value storage. + +**Parameters:** +- `key: string` - The key to delete + +**Returns:** `Promise` + +## Vector Storage + +The vector storage API provides semantic search capabilities with embedding operations. + +### Methods + +#### upsert(name, ...documents) + +Insert or update vectors in the vector storage. + +**Parameters:** +- `name: string` - The name of the vector storage +- `documents: VectorUpsertParams[]` - The documents to upsert + +**Returns:** `Promise` - Array of vector IDs that were upserted + +**Example:** +```javascript +const ids = await context.vector.upsert('my-docs', { + key: 'doc-1', + document: 'This is a sample document', + metadata: { category: 'example' } +}); +``` + +#### get(name, key) + +Retrieve a specific vector by its key from the vector storage. + +**Parameters:** +- `name: string` - The name of the vector storage +- `key: string` - The key of the vector to retrieve + +**Returns:** `Promise` - The vector data including document content, or null if not found + +**Example:** +```javascript +// First, search for relevant vectors +const searchResults = await context.vector.search('my-docs', { + query: 'sample query', + limit: 5 +}); + +// Then retrieve the full document content for each result +const documents = await Promise.all( + searchResults.map(async (result) => { + const vector = await context.vector.get('my-docs', result.key); + return vector ? vector.document : null; + }) +); +``` + +#### search(name, params) + +Search for vectors in the vector storage using semantic similarity. + +**Parameters:** +- `name: string` - The name of the vector storage +- `params: VectorSearchParams` - Search parameters including query, limit, and filters + +**Returns:** `Promise` - Array of search results with similarity scores + +**Example:** +```javascript +const results = await context.vector.search('my-docs', { + query: 'artificial intelligence', + limit: 10, + similarity: 0.7, + metadata: { category: 'tech' } +}); +``` + +#### 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 of vectors that were deleted + +**Example:** +```javascript +const deletedCount = await context.vector.delete('my-docs', 'doc-1', 'doc-2'); +``` + +## Agent Request + +The `AgentRequest` object encapsulates incoming data and metadata for agent processing. + +### Properties + +- `trigger: string` - The trigger type of the request (webhook, cron, email, etc.) + +### Methods + +#### metadata(key, defaultValue?) + +Get metadata from the request. + +**Parameters:** +- `key: string` - The metadata key +- `defaultValue?: Json` - Optional default value + +**Returns:** `Json` + +#### json() + +Get the request payload as a JSON object. + +**Returns:** `Json` + +#### text() + +Get the request payload as a string. + +**Returns:** `string` + +#### binary() + +Get the request payload as an ArrayBuffer. + +**Returns:** `ArrayBuffer` + +## Agent Response + +The `AgentResponse` object provides methods for constructing various response types. + +### Methods + +#### json(data, metadata?) + +Return a JSON response. + +**Parameters:** +- `data: Json` - The response data +- `metadata?: Record` - Optional response metadata + +**Returns:** `AgentResponseType` + +#### text(data, metadata?) + +Return a text response. + +**Parameters:** +- `data: string` - The response text +- `metadata?: Record` - Optional response metadata + +**Returns:** `AgentResponseType` + +#### redirect(agent, payload?, contentType?, metadata?) + +Redirect the request to another agent. + +**Parameters:** +- `agent: GetAgentRequestParams` - Target agent identification +- `payload?: Json | ArrayBuffer | string` - Optional payload to pass +- `contentType?: string` - Optional content type +- `metadata?: Record` - Optional metadata + +**Returns:** `AgentRedirectResponse` + +## Types + +### VectorUpsertParams + +Parameters for upserting vectors. + +```typescript +interface VectorUpsertParams { + key: string; + document: string; + metadata?: Record; + embedding?: number[]; +} +``` + +### VectorSearchParams + +Parameters for vector search operations. + +```typescript +interface VectorSearchParams { + query: string; + limit?: number; + similarity?: number; + metadata?: Record; +} +``` + +### VectorSearchResult + +Result from vector search operations. + +```typescript +interface VectorSearchResult { + id: string; + key: string; + similarity: number; + metadata?: Record; + document?: string; +} +``` From fb2e52d81809b968bc30f471607f2b2baee17b03 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Mon, 28 Jul 2025 15:07:29 +0000 Subject: [PATCH 2/2] Fix fumadocs configuration to use defineConfig for MDX options - 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 --- source.config.ts | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/source.config.ts b/source.config.ts index d9c403eb..1e123d05 100644 --- a/source.config.ts +++ b/source.config.ts @@ -1,9 +1,8 @@ -import { defineDocs } from "fumadocs-mdx/config"; +import { defineConfig, defineDocs } from "fumadocs-mdx/config"; import { transformerTwoslash } from "fumadocs-twoslash"; import { rehypeCodeDefaultOptions } from "fumadocs-core/mdx-plugins"; -export const { docs, meta } = defineDocs({ - dir: "content/docs", +export default defineConfig({ mdxOptions: { rehypeCodeOptions: { themes: { @@ -17,3 +16,7 @@ export const { docs, meta } = defineDocs({ }, }, }); + +export const { docs, meta } = defineDocs({ + dir: "content/docs", +});