add Guides pages and update screenshots #250
Conversation
- Create new "Guides"/tutorial pages (e.g., DevMode, agent logging) - Update storage API screenshots to include added object storage option - Add screenshot for creating a new object storage bucket - Fix internal link from "Agent Data Handling" to "Agent Streaming"
WalkthroughThis update introduces several new and revised documentation guides for cloud storage and agent observability features. It adds comprehensive guides for object storage, key-value storage, vector DB, agent logging, telemetry, tracing, AI Gateway, and DevMode. Some outdated metadata files are deleted, and meta.json files are updated to reflect the new documentation structure. Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant CloudConsole
participant SDK
participant StorageService
User->>CloudConsole: Click "Create Storage"
CloudConsole->>User: Show storage type options
User->>CloudConsole: Select "Key Value Store" or "Vector Database" or "Object Storage"
CloudConsole->>StorageService: Create storage instance (selected type)
StorageService-->>CloudConsole: Confirm creation
CloudConsole-->>User: Show new storage instance
User->>SDK: Use storage API (get/set/put/search)
SDK->>StorageService: Perform storage operation
StorageService-->>SDK: Return result
SDK-->>User: Provide operation outcome
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~15 minutes Suggested reviewers
Poem
Note ⚡️ Unit Test Generation is now available in beta!Learn more here, or try it out under "Finishing Touches" below. ✨ Finishing Touches🧪 Generate unit tests
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 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 | Preview URL | Updated (UTC) |
|---|---|---|---|---|
| ✅ Deployment successful! View logs |
docs | 6f63dd8 | Commit Preview URL Branch Preview URL |
Jul 29 2025, 06:00 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: 8
🧹 Nitpick comments (11)
content/Cloud/vector-memory.mdx (1)
40-41: UI label wording – please confirm.The instruction now tells users to choose “Vector Database” after clicking Create Storage. In the UI mock-ups the option is often labelled “Vector DB”. Ensure the wording matches the actual button label to avoid user confusion.
content/Cloud/key-value-memory.mdx (1)
41-42: Consistency with UI text.Similarly, confirm the console option is literally “Key Value Store” in production; if it’s “Key-Value Store” or “Key Value”, a mismatch will mislead readers.
content/Cloud/object-storage.mdx (2)
21-26: Clarify units for “Size” column“Size” alone is ambiguous (bytes? MB? GiB?). Explicitly stating the unit—e.g., “Size (bytes)” or “Size (GiB)”—pre-empts confusion.
27-30: Consider an accessibility-first alt textBoth images have generic alt text. Including purpose-driven descriptions (“Screenshot of Object Store table displaying bucket list”) improves screen-reader experience.
content/Guides/agent-tracing.mdx (1)
162-169: Timestamp attribute: prefer OT semantic conventionsInstead of a custom
timestampattribute, rely onadd_event()’s built-in timestamp argument or use thetime_unix_nanoproperty for better tooling compatibility.content/Guides/agent-logging.mdx (1)
150-153: Typo in example—missing variable
erroris passed but not defined in the snippet. Either rename toe(from catch block) or declare it for consistency.content/Guides/devmode.mdx (1)
8-8: “Exact same” is wordyReplace with “identical” or simply “the same” for conciseness.
content/Guides/ai-gateway.mdx (1)
30-38: Show explicit error handlingIncluding a minimal try/except with logging demonstrates recommended production practice, aligning with the logging & tracing guides referenced elsewhere.
content/Guides/vector-db.mdx (1)
146-151: Nit: bullet list parameters out of sync with codeThe code shows
similarity,limit, andmetadata, but the list omitstopK(if supported) and the order differs. Keep docs & code aligned for scan-reading.content/Guides/key-value.mdx (1)
174-181: Hyphenate compound adjective
Rate limiting counters→Rate-limiting countersfor correct compound-adjective usage.content/Guides/object-storage.mdx (1)
274-277: Clarify permanent-URL guidance“Never: Create permanent public URLs for sensitive data” could be misread as advice to create them. Reword for clarity.
-**Never**: Create permanent public URLs for sensitive data +**Avoid permanent public URLs** for sensitive data
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (18)
public/images/agent-logs-filter-dark.pngis excluded by!**/*.pngpublic/images/agent-logs-filter-light.pngis excluded by!**/*.pngpublic/images/aigateway-filters-dark.pngis excluded by!**/*.pngpublic/images/aigateway-filters-light.pngis excluded by!**/*.pngpublic/images/devmode-interface-dark.pngis excluded by!**/*.pngpublic/images/devmode-interface-light.pngis excluded by!**/*.pngpublic/images/devmode-logs-dark.pngis excluded by!**/*.pngpublic/images/devmode-logs-light.pngis excluded by!**/*.pngpublic/images/devmode-sessions-dark.pngis excluded by!**/*.pngpublic/images/devmode-sessions-light.pngis excluded by!**/*.pngpublic/images/keyvalue-new-dark.pngis excluded by!**/*.pngpublic/images/keyvalue-new-light.pngis excluded by!**/*.pngpublic/images/object-store-dark.pngis excluded by!**/*.pngpublic/images/object-store-light.pngis excluded by!**/*.pngpublic/images/object-store-new-dark.pngis excluded by!**/*.pngpublic/images/object-store-new-light.pngis excluded by!**/*.pngpublic/images/vector-new-dark.pngis excluded by!**/*.pngpublic/images/vector-new-light.pngis excluded by!**/*.png
📒 Files selected for processing (21)
content/Cloud/key-value-memory.mdx(1 hunks)content/Cloud/meta.json(1 hunks)content/Cloud/object-storage.mdx(1 hunks)content/Cloud/vector-memory.mdx(1 hunks)content/Guides/.agent-logging.mdx(0 hunks)content/Guides/.agent-telemetry.mdx(0 hunks)content/Guides/.agent-tracing.mdx(0 hunks)content/Guides/.ai-gateway.mdx(0 hunks)content/Guides/.devmode.mdx(0 hunks)content/Guides/.key-value.mdx(0 hunks)content/Guides/.vector-db.mdx(0 hunks)content/Guides/agent-data-handling.mdx(1 hunks)content/Guides/agent-logging.mdx(1 hunks)content/Guides/agent-telemetry.mdx(1 hunks)content/Guides/agent-tracing.mdx(1 hunks)content/Guides/ai-gateway.mdx(1 hunks)content/Guides/devmode.mdx(1 hunks)content/Guides/key-value.mdx(1 hunks)content/Guides/meta.json(1 hunks)content/Guides/object-storage.mdx(1 hunks)content/Guides/vector-db.mdx(1 hunks)
💤 Files with no reviewable changes (7)
- content/Guides/.agent-telemetry.mdx
- content/Guides/.agent-tracing.mdx
- content/Guides/.key-value.mdx
- content/Guides/.ai-gateway.mdx
- content/Guides/.devmode.mdx
- content/Guides/.agent-logging.mdx
- content/Guides/.vector-db.mdx
🧰 Additional context used
🧠 Learnings (10)
📓 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 : Use the storage APIs for persisting data
content/Guides/agent-data-handling.mdx (4)
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/agentuity.mdc:0-0
Timestamp: 2025-07-23T12:40:26.540Z
Learning: Applies to agent-docs/**/agentuity.yaml : Do not suggest edits to the Agentuity AI Configuration file (agentuity.yaml)
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: #195
File: agent-docs/src/agents/doc-processing/docs-processor.ts:7-15
Timestamp: 2025-06-18T04:07:57.583Z
Learning: In the agent-docs project, the ChunkMetadata type requires title and description fields to be mandatory strings rather than optional, indicating that the system ensures these fields are always populated during document processing.
content/Guides/meta.json (2)
Learnt from: CR
PR: agentuity/docs#0
File: agent-docs/.cursor/rules/agentuity.mdc:0-0
Timestamp: 2025-07-23T12:40:26.540Z
Learning: Applies to agent-docs/**/agentuity.yaml : Do not suggest edits to the Agentuity AI Configuration file (agentuity.yaml)
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
content/Guides/agent-tracing.mdx (5)
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: 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 : All code should be in Typescript format
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 : Leverage the provided logger for consistent logging
content/Guides/agent-logging.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 : Leverage the provided logger for consistent logging
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 : Use the provided logger from the AgentContext interface such as ctx.logger.info("my message: %s", "hello")
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/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/agentuity.mdc:0-0
Timestamp: 2025-07-23T12:40:26.540Z
Learning: Applies to agent-docs/**/agentuity.yaml : Do not suggest edits to the Agentuity AI Configuration file (agentuity.yaml)
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
Learnt from: afterrburn
PR: #198
File: agent-docs/src/agents/doc-qa/index.ts:9-50
Timestamp: 2025-06-20T13:09:14.197Z
Learning: In the agent-docs codebase, the user prefers to let exceptions throw from Agent functions rather than adding local try-catch blocks, allowing errors to be handled at a higher level in the application.
content/Guides/devmode.mdx (6)
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/agentuity.mdc:0-0
Timestamp: 2025-07-23T12:40:26.540Z
Learning: Applies to agent-docs/**/agentuity.yaml : Do not suggest edits to the Agentuity AI Configuration file (agentuity.yaml)
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 : All code should be in Typescript format
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 : Prefer loading types from the node modules package @agentuity/sdk in the node_modules folder
content/Guides/vector-db.mdx (2)
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: afterrburn
PR: #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.
content/Guides/object-storage.mdx (1)
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
content/Guides/key-value.mdx (1)
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
content/Guides/agent-telemetry.mdx (7)
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/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/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/agentuity.mdc:0-0
Timestamp: 2025-07-23T12:40:26.540Z
Learning: Applies to agent-docs/**/agentuity.yaml : Do not suggest edits to the Agentuity AI Configuration file (agentuity.yaml)
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
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 : Leverage the provided logger for consistent logging
🪛 LanguageTool
content/Guides/agent-tracing.mdx
[style] ~6-~6: Consider a different adjective to strengthen your wording.
Context: ...your agents --- Agent tracing provides deep visibility into your agent's execution ...
(DEEP_PROFOUND)
[style] ~87-~87: This phrase is redundant. Consider writing “moments” or “times”.
Context: ... parameters) Events mark specific moments in time with additional context (milestones, st...
(MOMENT_IN_TIME)
content/Guides/devmode.mdx
[style] ~8-~8: ‘exact same’ might be wordy. Consider a shorter alternative.
Context: ...ying them to the cloud. It provides the exact same interface and capabilities you'll have ...
(EN_WORDINESS_PREMIUM_EXACT_SAME)
content/Guides/key-value.mdx
[uncategorized] ~180-~180: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ...hours - API cache: 5-60 minutes - Rate limiting counters: Until period reset ### Dat...
(EN_COMPOUND_ADJECTIVE_INTERNAL)
⏰ 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 (7)
content/Cloud/meta.json (1)
9-9: Verify that the new slug actually resolves.The
"object-storage"page is now referenced in the Cloud section. Please double-check thatcontent/Cloud/object-storage.mdxships in the same PR and that the deployed site’s routing recognises the/Cloud/object-storagepath; otherwise the sidebar link will 404.content/Guides/agent-data-handling.mdx (1)
164-164: Link path casing may break on case-sensitive hosts.The link was changed to
/Guides/agent-streaming(capital “G”). All other internal links appear to use lower-case paths (e.g./guides/...). If the static-site host is case-sensitive, this may 404. Consider reverting to lower-case or standardising across the repo.content/Guides/meta.json (2)
7-9: Nice addition – guides surface clearly.Adding “devmode”, “agent-logging”, and “agent-telemetry” improves discoverability. No issues spotted.
14-14: Cross-section consistency check.“object-storage” is added here as well as in
content/Cloud/meta.json. Good to see parity; please ensure both pages share the same slug and metadata (title, description) for coherent navigation.content/Guides/agent-tracing.mdx (1)
99-106: Attribute value may violate OT spec
request.trigger()might return an object; span attributes must be primitive (string, bool, int, double). Convert to a string or split into multiple attributes.content/Guides/agent-telemetry.mdx (1)
64-72: Verify SDK doc link paths
/SDKs/javascriptand/SDKs/pythonmay not exist under the current docs routing (most SDK pages live under/SDK/javascriptor/Guides/SDKs/...). Broken internal links hurt navigation.Run a link checker or manually confirm the paths and adjust if necessary (e.g.
/SDK/javascript).content/Guides/key-value.mdx (1)
12-15: Broken cross-link target
/Cloud/vector-memoryappears to refer to the Console page, while analogous links in the new guides point to other Guides. If the intent is to jump to the new Vector-DB guide, change to/Guides/vector-db; otherwise clarify “(Cloud Console)” so readers know it’s a UI page.
|
|
||
| Search operations find semantically similar documents based on a text query. You can control the number of results, similarity threshold, and filter by metadata. | ||
|
|
||
| <CodeExample> | ||
| ```javascript | ||
| // JavaScript/TypeScript | ||
| // Basic semantic search | ||
| const results = await context.vector.search('knowledge-base', { | ||
| query: 'What is an agent platform?', | ||
| limit: 5, | ||
| similarity: 0.7, | ||
| metadata: { category: 'platform' } | ||
| }); | ||
|
|
||
| // Process results | ||
| results.forEach(result => { | ||
| console.log(`Found: ${result.metadata.source}`); | ||
| console.log(`Similarity: ${1 - result.distance}`); | ||
| }); | ||
| ``` | ||
|
|
||
| ```python | ||
| # Python | ||
| # Semantic search with parameters | ||
| results = await context.vector.search( | ||
| "knowledge-base", | ||
| query="What is an agent platform?", | ||
| limit=5, | ||
| similarity=0.7, | ||
| metadata={"category": "platform"} | ||
| ) | ||
|
|
||
| # Process results | ||
| for result in results: | ||
| similarity_score = 1.0 - result.distance | ||
| print(f"Found: {result.metadata['source']}") | ||
| print(f"Similarity: {similarity_score}") | ||
| ``` | ||
| </CodeExample> | ||
|
|
||
| **Search Parameters:** | ||
| - `query` (required): Text query to search for | ||
| - `limit` (optional): Maximum number of results to return | ||
| - `similarity` (optional): Minimum similarity threshold (0.0-1.0) | ||
| - `metadata` (optional): Filter results by metadata key-value pairs | ||
|
|
There was a problem hiding this comment.
🛠️ Refactor suggestion
Document the “non-empty query” requirement
The Vector Search backend rejects an empty string. This is a common pit-fall surfaced in earlier incidents (see retrieved learnings). Add an explicit note so users don’t trip on silent 400s.
-### Searching Vector Storage
+### Searching Vector Storage
+
+> **Important:** `query` must be a **non-empty string**.
+> Use a single space `" "` when you need metadata-only filtering without affecting similarity ranking.📝 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.
| Search operations find semantically similar documents based on a text query. You can control the number of results, similarity threshold, and filter by metadata. | |
| <CodeExample> | |
| ```javascript | |
| // JavaScript/TypeScript | |
| // Basic semantic search | |
| const results = await context.vector.search('knowledge-base', { | |
| query: 'What is an agent platform?', | |
| limit: 5, | |
| similarity: 0.7, | |
| metadata: { category: 'platform' } | |
| }); | |
| // Process results | |
| results.forEach(result => { | |
| console.log(`Found: ${result.metadata.source}`); | |
| console.log(`Similarity: ${1 - result.distance}`); | |
| }); | |
| ``` | |
| ```python | |
| # Python | |
| # Semantic search with parameters | |
| results = await context.vector.search( | |
| "knowledge-base", | |
| query="What is an agent platform?", | |
| limit=5, | |
| similarity=0.7, | |
| metadata={"category": "platform"} | |
| ) | |
| # Process results | |
| for result in results: | |
| similarity_score = 1.0 - result.distance | |
| print(f"Found: {result.metadata['source']}") | |
| print(f"Similarity: {similarity_score}") | |
| ``` | |
| </CodeExample> | |
| **Search Parameters:** | |
| - `query` (required): Text query to search for | |
| - `limit` (optional): Maximum number of results to return | |
| - `similarity` (optional): Minimum similarity threshold (0.0-1.0) | |
| - `metadata` (optional): Filter results by metadata key-value pairs | |
| ### Searching Vector Storage | |
| > **Important:** `query` must be a **non-empty string**. | |
| > Use a single space `" "` when you need metadata-only filtering without affecting similarity ranking. | |
| Search operations find semantically similar documents based on a text query. You can control the number of results, similarity threshold, and filter by metadata. | |
| <CodeExample> |
🤖 Prompt for AI Agents
In content/Guides/vector-db.mdx between lines 106 and 151, add a clear note
stating that the 'query' parameter for vector search must be a non-empty string
because the backend rejects empty queries and returns a 400 error. This note
should be placed near the search parameters section to warn users explicitly and
help prevent silent failures when an empty query is provided.
- Fix inconsistent error variable names in logging examples - Add missing Python imports for code examples - Correct loopback address in DevMode guide (0.0.0.1 to 127.0.0.1) - Replace TODO comment (Object Storage) with actual screenshot - Remove manual `span.end()` calls in tracing examples
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (4)
content/Guides/agent-tracing.mdx (2)
30-54: Explicitly mark successful spans withSpanStatusCode.OKThe happy-path in this snippet returns without ever calling
span.setStatus({ code: SpanStatusCode.OK }). Although the OpenTelemetry spec treats an unspecified status as UNSET, many back-ends interpret this as “unknown”. Explicitly marking success keeps dashboards consistent with the error path shown later in the doc.// Perform work const result = await processData(); + // Mark span as successful + span.setStatus({ code: SpanStatusCode.OK }); + // Add events to mark important moments span.addEvent('data-processed', { itemCount: result.length });
200-205: Avoid storing PII in trace attributesAttributes like
userId,requestId, orresourceIdcan be classified as personally-identifiable or sensitive business data once exported to external APM systems. Consider:
- Hashing / anonymising user identifiers.
- Adding a short disclaimer in the guide about sensitive attributes.
content/Guides/devmode.mdx (2)
8-8: Tighten wording – replace “exact same”Minor style nit: “exact same” is considered wordy. “identical” or simply “the same” reads cleaner.
- It provides the exact same interface and capabilities you'll have in production. + It provides the same interface and capabilities you'll have in production.
24-31: Clarify port exposure & conflictsThe example fixes the loopback address (👍) but developers running multiple agents may still collide on the hard-coded
3500port. Adding a short note that--port <number>can override the default would help avoid confusion.No code change required—just a one-line doc hint under the CLI snippet.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (5)
content/Guides/agent-logging.mdx(1 hunks)content/Guides/agent-tracing.mdx(1 hunks)content/Guides/ai-gateway.mdx(1 hunks)content/Guides/devmode.mdx(1 hunks)content/Guides/object-storage.mdx(1 hunks)
✅ Files skipped from review due to trivial changes (1)
- content/Guides/object-storage.mdx
🚧 Files skipped from review as they are similar to previous changes (2)
- content/Guides/ai-gateway.mdx
- content/Guides/agent-logging.mdx
🧰 Additional context used
🧠 Learnings (3)
📓 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 : Use the storage APIs for persisting data
content/Guides/agent-tracing.mdx (4)
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: 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 : All code should be in Typescript format
content/Guides/devmode.mdx (6)
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/agentuity.mdc:0-0
Timestamp: 2025-07-23T12:40:26.540Z
Learning: Applies to agent-docs/**/agentuity.yaml : Do not suggest edits to the Agentuity AI Configuration file (agentuity.yaml)
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 : All code should be in Typescript format
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 : Prefer loading types from the node modules package @agentuity/sdk in the node_modules folder
🪛 LanguageTool
content/Guides/agent-tracing.mdx
[style] ~6-~6: Consider a different adjective to strengthen your wording.
Context: ...your agents --- Agent tracing provides deep visibility into your agent's execution ...
(DEEP_PROFOUND)
[style] ~85-~85: This phrase is redundant. Consider writing “moments” or “times”.
Context: ... parameters) Events mark specific moments in time with additional context (milestones, st...
(MOMENT_IN_TIME)
content/Guides/devmode.mdx
[style] ~8-~8: ‘exact same’ might be wordy. Consider a shorter alternative.
Context: ...ying them to the cloud. It provides the exact same interface and capabilities you'll have ...
(EN_WORDINESS_PREMIUM_EXACT_SAME)
⏰ 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/Guides/agent-tracing.mdx (1)
52-53: Previous “double-end span” issue resolved – LGTMThe earlier manual
span.end()call has been removed, avoiding double-ending warnings in many OTEL SDKs. 👍
Summary by CodeRabbit