Update Guides and API reference pages #280
Conversation
- Add `vector.get()` usage to API reference, examples in Guides - Fix code formatting for Vector DB guide - Clean up Guides headings - Fix Python agent communication examples (should use `get_agent`)
WalkthroughReorganized and clarified multiple guides and SDK docs: standardized payload/content-type handling, added ObjectStorePutParams and Vector Storage get-by-key, migrated many Python request/response helpers to async, updated agent communication/resolution and numerous code examples to use ctx and new parameter shapes. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
actor User
participant "Agent A" as A
participant Resolver
participant "Agent B" as B
participant Auth as "AuthZ Token"
User->>A: Request
A->>Resolver: getAgent(id | name | projectId)
Resolver-->>A: AgentRef (B)
note over A,Resolver: Resolution modes: Agent ID / Agent Name / Project ID
A->>Auth: request one-time cross-project/org token
Auth-->>A: token
A->>B: handoff/invoke { data, contentType } (+ token if cross-org)
B-->>A: Result
A-->>User: Response
sequenceDiagram
autonumber
participant App
participant Vectors
App->>Vectors: get(name, key)
alt Found
Vectors-->>App: VectorSearchResult
else Not found
Vectors-->>App: null
end
sequenceDiagram
autonumber
participant Handler
participant "Object Store" as Store
note over Handler: Build ObjectStorePutParams (content_type, cache_control, metadata...)
Handler->>Store: put(bucket, key, data, params)
Store-->>Handler: OK
sequenceDiagram
autonumber
participant Client
participant "Python Agent" as PyAgent
Client->>PyAgent: Request
PyAgent->>PyAgent: await request.data.json()/text()/binary()
PyAgent-->>Client: await response.markdown()/data()/png()/mp3()/mp4()...
Estimated code review effort🎯 4 (Complex) | ⏱️ ~75 minutes Possibly related PRs
Suggested reviewers
Pre-merge checks (3 passed)✅ Passed checks (3 passed)
Poem
Tip 👮 Agentic pre-merge checks are now available in preview!Pro plan users can now enable pre-merge checks in their settings to enforce checklists before merging PRs.
Please see the documentation for more information. Example: reviews:
pre_merge_checks:
custom_checks:
- name: "Undocumented Breaking Changes"
mode: "warning"
instructions: |
Pass/fail criteria: All breaking changes to public APIs, CLI flags, environment variables, configuration keys, database schemas, or HTTP/GraphQL endpoints must be documented in the "Breaking Change" section of the PR description and in CHANGELOG.md. Exclude purely internal or private changes (e.g., code not exported from package entry points or explicitly marked as internal).Please share your feedback with us on this Discord post. ✨ 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. Comment |
Deploying with
|
| Status | Name | Latest Commit | Preview URL | Updated (UTC) |
|---|---|---|---|---|
| ✅ Deployment successful! View logs |
docs | 67c33ae | Commit Preview URL Branch Preview URL |
Sep 11 2025, 02:06 AM |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (7)
content/Guides/agent-data-handling.mdx (2)
41-52: Fix Python example indentation (syntax error risk).The
if/elif/elseblock is mis-indented underasync def run(...).Apply:
-async def run(request: AgentRequest, response: AgentResponse, context: AgentContext): - contentType = request.data.contentType - if contentType == 'text/plain': - text = await request.data.text() - # do something with the text - elif contentType == 'application/json': - json = await request.data.json() - # do something with the json - else: - # do something with the data - pass +async def run(request: AgentRequest, response: AgentResponse, context: AgentContext): + contentType = request.data.contentType + if contentType == 'text/plain': + text = await request.data.text() + # do something with the text + elif contentType == 'application/json': + json = await request.data.json() + # do something with the json + else: + # do something with the data + pass
205-226: Align Email API with JS reference (properties vs. methods).This section lists Email “properties” (e.g.,
subject,attachments) but the JS API reference defines methods (subject(),attachments(), etc.). Also, each attachment exposesdata()(async) rather than adatafield.Update bullets to method form and correct attachment access:
-You must await the `email` method to get the email object. The email object will be a `Email` object. The Email object has the following properties: +You must await the `email` method to get the email object. The Email object exposes the following methods: -- `date`: The date of the email. -- `messageId`: The message ID of the email. -- `fromEmail`: The sender of the email. -- `fromName`: The sender name (if provided). -- `subject`: The subject of the email. -- `attachments`: The attachments of the email as an array of `Attachment` objects. -- `headers`: The headers of the email as an array of `Header` objects. -- `text`: The text body of the email. -- `html`: The HTML body of the email. +- `date(): Date | null` +- `messageId(): string | null` +- `fromEmail(): string | null` +- `fromName(): string | null` +- `subject(): string | null` +- `attachments(): IncomingEmailAttachment[]` +- `headers(): Headers` +- `text(): string | null` +- `html(): string | null` -The `Attachment` object has the following properties: +IncomingEmailAttachment has: -- `filename`: The filename of the attachment. -- `contentDisposition`: The content disposition of the attachment which is either `inline` or `attachment`. Defaults to `attachment`. -- `data`: The `DataType` of the attachment. +- `filename: string` +- `contentDisposition: 'inline' | 'attachment'` +- `data(): Promise<Data>` // uses streaming for large attachmentscontent/Guides/agent-streaming.mdx (1)
69-79: Python example: await request text.
request.data.textshould be awaited as a method.-{"role": "user", "content": request.data.text or "Why is the sky blue?"}, +{"role": "user", "content": (await request.data.text()) or "Why is the sky blue?"},content/Guides/agent-tracing.mdx (1)
99-105: Userequest.trigger(property) instead of a function in JS.The JS API defines
get trigger(): string; callingrequest.trigger()can confuse readers.- parentSpan.setAttribute('trigger', request.trigger()); + parentSpan.setAttribute('trigger', request.trigger);content/SDKs/python/api-reference.mdx (2)
612-666: Fix invalid Python placeholder in bytes example.
bytes([/* image bytes */])is not valid Python. Use a real bytes literal or a comment:-image_data = bytes([/* image bytes */]) +image_data = b"\x00\x01..." # example bytes
1023-1071: Make request data examples async and consistent
Incontent/SDKs/python/api-reference.mdxat lines 1052–1054 and 1069–1071, update the text and binary examples to mirror the JSON example:- text = request.data.text + text = await request.data.text() - binary_data = request.binary() + binary_data = await request.data.binary()Would you like me to sweep the repo for any remaining
request.text()/request.binary()vsrequest.data.*()inconsistencies?content/Guides/vector-db.mdx (1)
69-93: JS upsert example passes multiple objects instead of an array.The SDK expects an array of documents. Fix to avoid copy/paste errors:
-const ids = await context.vector.upsert( - 'knowledge-base', - { - key: 'doc-1', - document: 'Agentuity is an agent-native cloud platform', - metadata: { category: 'platform', source: 'docs' } - }, - { - key: 'doc-2', - document: 'Vector storage enables semantic search capabilities', - metadata: { category: 'features', source: 'docs' } - } -); +const ids = await context.vector.upsert( + 'knowledge-base', + [ + { + key: 'doc-1', + document: 'Agentuity is an agent-native cloud platform', + metadata: { category: 'platform', source: 'docs' } + }, + { + key: 'doc-2', + document: 'Vector storage enables semantic search capabilities', + metadata: { category: 'features', source: 'docs' } + } + ] +);
🧹 Nitpick comments (7)
content/Guides/agent-data-handling.mdx (1)
60-61: Typo: duplicate word.“You use use” → “You can use”.
-You use use the `text` method on the `Data` object to get the raw text data. +You can use the `text` method on the `Data` object to get the raw text data.content/SDKs/javascript/api-reference.mdx (2)
273-301: VectorStorage.get docs: looks good; tighten wording and note similarity field.Minor grammar and clarity edits; also clarify whether
similarityis present for direct gets.-`get(name: string, key: string): Promise<VectorSearchResult | null>` +`get(name: string, key: string): Promise<VectorSearchResult | null>` -Retrieves a specific vector from the vector storage using its key. +Retrieves a vector by its key without performing a similarity search. -Returns a Promise that resolves to a `VectorSearchResult` object if found, or `null` if the key doesn't exist. +Returns a Promise that resolves to a `VectorSearchResult` if found, or `null` if the key doesn't exist. Note: the `similarity` field may be undefined for direct key lookups.
281-283: Grammar nit: parallel style for parameter bullets.Add periods for consistency and fix article usage.
-- `name`: The name of the vector storage -- `key`: The unique key of the vector to retrieve +- `name`: The name of the vector storage. +- `key`: The unique key of the vector to retrieve.content/Guides/key-value.mdx (1)
190-197: Hyphenate compound adjective.Minor copy tweak for clarity:
-- **Rate limiting counters**: Until period reset +- **Rate-limiting counters**: Until period resetcontent/Guides/agent-communication.mdx (3)
8-8: Alt text nit.Add missing space for accessibility/readability:
-<Image src="/images/agent-to-agent.png" alt="Agent-to-AgentCommunication" width={640} height={640} /> +<Image src="/images/agent-to-agent.png" alt="Agent-to-Agent Communication" width={640} height={640} />
47-55: Use “hand off” (verb) vs “handoff” (noun).Where used as a verb, prefer “hand off”:
-Agents can handoff a request +Agents can hand off a requestAlso applies to: 73-86
118-123: Cross-language consistency: payload shape.JS uses
{ data, contentType }while Python infers type from raw payload. This is good, but add a one-line note calling out the difference to avoid confusion for readers jumping between tabs.Also applies to: 128-133
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (9)
content/Guides/agent-communication.mdx(8 hunks)content/Guides/agent-data-handling.mdx(1 hunks)content/Guides/agent-streaming.mdx(1 hunks)content/Guides/agent-tracing.mdx(1 hunks)content/Guides/ai-gateway.mdx(1 hunks)content/Guides/key-value.mdx(6 hunks)content/Guides/vector-db.mdx(7 hunks)content/SDKs/javascript/api-reference.mdx(1 hunks)content/SDKs/python/api-reference.mdx(2 hunks)
🧰 Additional context used
🧠 Learnings (2)
📚 Learning: 2025-07-23T12:40:34.834Z
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
Applied to files:
content/Guides/key-value.mdx
📚 Learning: 2025-07-23T12:40:34.834Z
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
Applied to files:
content/Guides/agent-communication.mdx
🪛 LanguageTool
content/SDKs/javascript/api-reference.mdx
[grammar] ~281-~281: There might be a mistake here.
Context: ...- name: The name of the vector storage - key: The unique key of the vector to retrie...
(QB_NEW_EN)
content/SDKs/python/api-reference.mdx
[grammar] ~504-~504: There might be a mistake here.
Context: ...- name: The name of the vector storage - key: The unique key of the vector to retrie...
(QB_NEW_EN)
content/Guides/vector-db.mdx
[grammar] ~12-~12: There might be a mistake here.
Context: ... search, embeddings, similarity matching - **[Key-Value Storage](/Cloud/key-value-memo...
(QB_NEW_EN)
[grammar] ~13-~13: There might be a mistake here.
Context: ...st lookups, simple data, temporary state - Object Storage...
(QB_NEW_EN)
[grammar] ~69-~69: There might be a mistake here.
Context: ...odeExample js={`// JavaScript/TypeScript // Upsert documents with text (automatic...
(QB_NEW_EN)
[grammar] ~125-~125: There might be a mistake here.
Context: ...odeExample js={`// JavaScript/TypeScript // Basic semantic search const results =...
(QB_NEW_EN)
[grammar] ~137-~137: There might be a mistake here.
Context: ...(`Similarity: ${result.similarity}`); });} py={# Python # Semantic search wi...
(QB_NEW_EN)
[grammar] ~138-~138: There might be a mistake here.
Context: ...sult.similarity}`); });} py={# Python # Semantic search with parameters results ...
(QB_NEW_EN)
[grammar] ~167-~167: There might be a mistake here.
Context: ...odeExample js={`// JavaScript/TypeScript // Direct lookup by key const vector = a...
(QB_NEW_EN)
[grammar] ~168-~168: There might be a mistake here.
Context: ...cript/TypeScript // Direct lookup by key const vector = await context.vector.get(...
(QB_NEW_EN)
[grammar] ~171-~171: There might be a mistake here.
Context: ...nowledge-base', 'doc-1'); if (vector) { console.log(`Found: ${vector.id}`); ...
(QB_NEW_EN)
[grammar] ~174-~174: There might be a mistake here.
Context: ...nsole.log('Metadata:', vector.metadata); } else { console.log('Vector not found...
(QB_NEW_EN)
[grammar] ~175-~175: There might be a mistake here.
Context: ...('Metadata:', vector.metadata); } else { console.log('Vector not found'); } // C...
(QB_NEW_EN)
[grammar] ~182-~182: There might be a mistake here.
Context: ...t.vector.get('products', 'product-123'); if (existing) { // Update with merged ...
(QB_NEW_EN)
[grammar] ~183-~183: There might be a mistake here.
Context: ...oducts', 'product-123'); if (existing) { // Update with merged metadata await c...
(QB_NEW_EN)
[grammar] ~193-~193: There might be a mistake here.
Context: ...wait context.vector.search('products', { query: 'office chair', limit: 5 }); /...
(QB_NEW_EN)
[grammar] ~195-~195: There might be a mistake here.
Context: ...', { query: 'office chair', limit: 5 }); // Get complete details for the top...
(QB_NEW_EN)
[grammar] ~198-~198: There might be a mistake here.
Context: ... Get complete details for the top result if (searchResults[0]) { const fullDeta...
(QB_NEW_EN)
[grammar] ~199-~199: There might be a mistake here.
Context: ...r the top result if (searchResults[0]) { const fullDetails = await context.vector...
(QB_NEW_EN)
[grammar] ~201-~201: There might be a mistake here.
Context: ...Full metadata:', fullDetails?.metadata); }} py={# Python # Direct lookup by key...
(QB_NEW_EN)
[grammar] ~202-~202: There might be a mistake here.
Context: ...ullDetails?.metadata); }} py={# Python # Direct lookup by key vector = await cont...
(QB_NEW_EN)
[grammar] ~203-~203: There might be a mistake here.
Context: ...}} py={# Python # Direct lookup by key vector = await context.vector.get("knowl...
(QB_NEW_EN)
[grammar] ~206-~206: There might be a mistake here.
Context: ...t("knowledge-base", "doc-1") if vector: print(f"Found: {vector.id}") print(f...
(QB_NEW_EN)
[grammar] ~209-~209: There might be a mistake here.
Context: ... print(f"Metadata: {vector.metadata}") else: print("Vector not found") # C...
(QB_NEW_EN)
[grammar] ~210-~210: There might be a mistake here.
Context: ...nt(f"Metadata: {vector.metadata}") else: print("Vector not found") # Common use ...
(QB_NEW_EN)
[grammar] ~216-~216: There might be a mistake here.
Context: ...xt.vector.get("products", "product-123") if existing: # Update with merged me...
(QB_NEW_EN)
[grammar] ~217-~217: There might be a mistake here.
Context: ...("products", "product-123") if existing: # Update with merged metadata await ...
(QB_NEW_EN)
[grammar] ~226-~226: There might be a mistake here.
Context: ...h_results = await context.vector.search( "products", query="office chair", ...
(QB_NEW_EN)
[grammar] ~233-~233: There might be a mistake here.
Context: ...ls for the top result if search_results: full_details = await context.vector.get(...
(QB_NEW_EN)
[grammar] ~238-~238: There might be a mistake here.
Context: ...)} /> **When to use getvssearch:** - Use get` when you know the exact key (l...
(QB_NEW_EN)
[grammar] ~248-~248: There might be a mistake here.
Context: ...odeExample js={`// JavaScript/TypeScript // Delete single vector const deletedCou...
(QB_NEW_EN)
[grammar] ~249-~249: There might be a mistake here.
Context: ...cript/TypeScript // Delete single vector const deletedCount = await context.vecto...
(QB_NEW_EN)
[grammar] ~252-~252: There might be a mistake here.
Context: ...', 'doc-1'); // Delete multiple vectors const bulkDeleteCount = await context.ve...
(QB_NEW_EN)
[grammar] ~253-~253: There might be a mistake here.
Context: ...leteCount = await context.vector.delete( 'knowledge-base', 'doc-1', 'doc-2', '...
(QB_NEW_EN)
[grammar] ~255-~255: There might be a mistake here.
Context: ...edge-base', 'doc-1', 'doc-2', 'doc-3' );} py={# Python # Delete single vecto...
(QB_NEW_EN)
[grammar] ~256-~256: There might be a mistake here.
Context: ...-1', 'doc-2', 'doc-3' );} py={# Python # Delete single vector count = await conte...
(QB_NEW_EN)
[grammar] ~257-~257: There might be a mistake here.
Context: ...;} py={# Python # Delete single vector count = await context.vector.delete("kno...
(QB_NEW_EN)
content/Guides/key-value.mdx
[grammar] ~41-~41: There might be a mistake here.
Context: ...entHandler = async (req, resp, ctx) => { // Buckets are auto-created if they don'...
(QB_NEW_EN)
[grammar] ~48-~48: There might be a mistake here.
Context: ...esp.json({ message: 'Session stored' }); }; export default handler;} py={# Pyt...
(QB_NEW_EN)
[grammar] ~75-~75: There might be a mistake here.
Context: ...tion: <CodeExample js={`// Simple store await ctx.kv.set('cache', 'api-response'...
(QB_NEW_EN)
[grammar] ~78-~78: There might be a mistake here.
Context: ...nse', responseData); // Store an object await ctx.kv.set('user-prefs', userId, {...
(QB_NEW_EN)
[grammar] ~79-~79: There might be a mistake here.
Context: ...await ctx.kv.set('user-prefs', userId, { language: 'en', timezone: 'UTC' }); /...
(QB_NEW_EN)
[grammar] ~81-~81: There might be a mistake here.
Context: ...d, { language: 'en', timezone: 'UTC' }); // Store with TTL (expires after 1 ...
(QB_NEW_EN)
[grammar] ~84-~84: There might be a mistake here.
Context: ...// Store with TTL (expires after 1 hour) await ctx.kv.set('sessions', sessionId, ...
(QB_NEW_EN)
[grammar] ~85-~85: There might be a mistake here.
Context: ....set('sessions', sessionId, userData, { ttl: 3600, // seconds contentType: 'a...
(QB_NEW_EN)
[grammar] ~87-~87: There might be a mistake here.
Context: ...econds contentType: 'application/json' }); // Store feature flags (no TTL - pe...
(QB_NEW_EN)
[grammar] ~90-~90: There might be a mistake here.
Context: ...ature flags (no TTL - persistent config) await ctx.kv.set('feature-flags', 'beta-...
(QB_NEW_EN)
[grammar] ~91-~91: There might be a mistake here.
Context: ....set('feature-flags', 'beta-features', { darkMode: true, aiAssistant: false, ...
(QB_NEW_EN)
[grammar] ~94-~94: There might be a mistake here.
Context: ...aiAssistant: false, newDashboard: true });} py={# Simple store await context....
(QB_NEW_EN)
[grammar] ~95-~95: There might be a mistake here.
Context: ...ashboard: true });} py={# Simple store await context.kv.set("cache", "api-respo...
(QB_NEW_EN)
[grammar] ~99-~99: There might be a mistake here.
Context: ... context.kv.set("user-prefs", user_id, { "language": "en", "timezone": "UTC" ...
(QB_NEW_EN)
[grammar] ~101-~101: There might be a mistake here.
Context: ... "language": "en", "timezone": "UTC" }) # Store with TTL (expires after 1 ho...
(QB_NEW_EN)
[grammar] ~104-~104: There might be a mistake here.
Context: ... # Store with TTL (expires after 1 hour) await context.kv.set("sessions", session...
(QB_NEW_EN)
[grammar] ~105-~105: There might be a mistake here.
Context: ...set("sessions", session_id, user_data, { "ttl": 3600 # seconds }) # Store featu...
(QB_NEW_EN)
[grammar] ~106-~106: There might be a mistake here.
Context: ... user_data, { "ttl": 3600 # seconds }) # Store feature flags (no TTL - pers...
(QB_NEW_EN)
[grammar] ~109-~109: There might be a mistake here.
Context: ...ature flags (no TTL - persistent config) await context.kv.set("feature-flags", "b...
(QB_NEW_EN)
[grammar] ~110-~110: There might be a mistake here.
Context: ....set("feature-flags", "beta-features", { "darkMode": True, "aiAssistant": Fal...
(QB_NEW_EN)
[grammar] ~113-~113: There might be a mistake here.
Context: ...istant": False, "newDashboard": True })`} /> ### Retrieving Data Retrieve s...
(QB_NEW_EN)
[grammar] ~120-~120: There might be a mistake here.
Context: ...ation: <CodeExample js={`// Get a value const result = await ctx.kv.get('user-pr...
(QB_NEW_EN)
[grammar] ~133-~133: There might be a mistake here.
Context: ...() : defaultConfig;} py={# Get a value result = await context.kv.get("user-pref...
(QB_NEW_EN)
[grammar] ~192-~192: There might be a mistake here.
Context: ...temporary data to prevent storage bloat: - Session data: 24-48 hours - **API cach...
(QB_NEW_EN)
[grammar] ~193-~193: There might be a mistake here.
Context: ...e bloat: - Session data: 24-48 hours - API cache: 5-60 minutes - **Rate limit...
(QB_NEW_EN)
[grammar] ~194-~194: There might be a mistake here.
Context: ...4-48 hours - API cache: 5-60 minutes - Rate limiting counters: Until period r...
(QB_NEW_EN)
[uncategorized] ~195-~195: 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 - **Perm...
(EN_COMPOUND_ADJECTIVE_INTERNAL)
[grammar] ~195-~195: There might be a mistake here.
Context: ... limiting counters**: Until period reset - Permanent config: No TTL (keys persist...
(QB_NEW_EN)
content/Guides/agent-communication.mdx
[style] ~12-~12: ‘overall goal’ might be wordy. Consider a shorter alternative.
Context: ...t-to-agent communication to achieve the overall goal. There are a number of ways to achieve...
(EN_WORDINESS_PREMIUM_OVERALL_GOAL)
[grammar] ~42-~42: There might be a mistake here.
Context: ...her agents: | Type | Description | |-----------|-------------| | Handoff | ...
(QB_NEW_EN)
[grammar] ~43-~43: There might be a mistake here.
Context: ...escription | |-----------|-------------| | Handoff | Agents can handoff a request...
(QB_NEW_EN)
[grammar] ~44-~44: Ensure spelling is correct
Context: ...-|-------------| | Handoff | Agents can handoff a request to another agent to complete ...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[grammar] ~44-~44: There might be a mistake here.
Context: ...a request to another agent to complete | | Invocation | Agents can invoke another...
(QB_NEW_EN)
[grammar] ~85-~85: There might be a mistake here.
Context: ...is?", contentType: "text/plain" } ); }} py={from agentuity import AgentRequ...
(QB_NEW_EN)
[grammar] ~88-~88: There might be a mistake here.
Context: ...: AgentResponse, context: AgentContext): return response.handoff({"name":"My Othe...
(QB_NEW_EN)
[grammar] ~89-~89: There might be a mistake here.
Context: ...er Agent"}, "would you please do this?") `} /> ### Invocation When an agent nee...
(QB_NEW_EN)
[grammar] ~120-~120: There might be a mistake here.
Context: ...({ data: "would you please do this?" }); // Explicit control when needed: // ...
(QB_NEW_EN)
[grammar] ~124-~124: There might be a mistake here.
Context: ...data.text(); return resp.text(text); }} py={from agentuity import AgentRequ...
(QB_NEW_EN)
[grammar] ~127-~127: There might be a mistake here.
Context: ...: AgentResponse, context: AgentContext): agent = await context.get_agent({"name":...
(QB_NEW_EN)
[grammar] ~128-~128: There might be a mistake here.
Context: ...ext.get_agent({"name":"My Other Agent"}) # Send plain text (content type inferred...
(QB_NEW_EN)
[grammar] ~203-~203: There might be a mistake here.
Context: ...signed to an agent when it is created. | | Agent Name | The agent name is a human...
(QB_NEW_EN)
⏰ 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 (13)
content/Guides/agent-data-handling.mdx (2)
6-8: Good addition: clear Overview section.Concise intro and grammar fix improve readability.
261-287: JS/Py reply examples look good; keep metadata prerequisite callout.Examples align with
sendReply(request, context, ...)contract and large-attachment note.content/Guides/agent-streaming.mdx (3)
29-29: Heading level tweak improves structure.Promoting “Real-World Use Cases” to H3 is consistent with other guides.
81-111: Solid addition: structured object streaming with Vercel AI SDK.Auto JSONL conversion note is helpful.
160-181: Agent-to-Agent streaming example is clear and correct.Uses
ctx.getAgent, pipesexpertResp.data.stream()correctly.content/Guides/agent-tracing.mdx (2)
6-8: Good Overview section.Sets context for the rest of the tracing guide.
151-156: Confirm Python trigger accessor.If Python also exposes a property (not method), mirror the JS change; otherwise keep as-is. Please verify against the Python SDK.
Would you like me to scan the repo for
class AgentRequestin the Python SDK to confirm whethertriggeris a property or method?content/Guides/ai-gateway.mdx (1)
3-3: Micro copy improvement in description.“The AI Gateway” reads better; no further changes needed.
content/Guides/key-value.mdx (2)
41-49: Nice: concise ctx/resp pattern and auto-create note.The handler snippet is clean and aligned with the rest of the guides. No action needed.
69-70: Good clarification on “bucket name” semantics.Helpful to preempt confusion. No changes requested.
content/Guides/agent-communication.mdx (1)
197-206: Resolution table reads well.Clear guidance on ID/Name/Project ID. No action needed.
content/Guides/vector-db.mdx (2)
163-176: Good addition: explicitgetvssearchguidance.Clear heuristics; this will reduce misuse. No action needed.
248-256: Verify JSvector.deletesupports multiple keys
Repo search didn’t locate a vararg signature forvector.delete. Manually inspect the SDK’s TypeScript definitions to confirm if it accepts multiple keys (e.g.delete(name: string, ...keys: string[])) or only a single key and adjust the example accordingly.
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
content/SDKs/python/api-reference.mdx (1)
1023-1037: Fix async method signatures for request data accessors.Examples correctly use
await, but the signatures omit “async”. This mismatch can confuse users.-#### json - -`json() -> dict` +#### json + +`async json() -> dict` @@ -#### text - -`text() -> str` +#### text + +`async text() -> str` @@ -#### binary - -`binary() -> bytes` +#### binary + +`async binary() -> bytes` @@ -# Get an image from the request -image = await request.data.png() +# Get an image from the request +image = await request.data.png()Also update all media-specific method signatures in this section to
asyncfor consistency.Also applies to: 1041-1054, 1069-1071, 1093-1099
♻️ Duplicate comments (2)
content/SDKs/python/api-reference.mdx (1)
779-786: Agent retrieval and invocation: Python example now passes raw payload.This addresses prior feedback to avoid the JS-style
{ data, contentType }wrapper in Python.Also applies to: 789-791
content/Guides/vector-db.mdx (1)
167-206: get-by-key section is clear; Python import fortimeadded.The previous missing import appears addressed.
Also applies to: 207-243
🧹 Nitpick comments (7)
content/Guides/agent-streaming.mdx (1)
140-141: Clarifyresp.streamparameters when using a transformer.
return resp.stream(dataStream, undefined, {}, transformer)is unclear without a signature. Briefly document the argument order or prefer a named-params form to reduce reader confusion.- return resp.stream(dataStream, undefined, {}, transformer); + // resp.stream(source, contentType?, metadata?, transformer?) + return resp.stream(dataStream, undefined, {}, transformer); + // or (preferred) support an options object in docs: + // return resp.stream(dataStream, { transformer });content/Guides/agent-communication.mdx (3)
82-90: Handoff payload examples: clarify Python content-type inference.Call out that Python infers
text/plainfor raw strings andapplication/jsonfor dicts, so users rarely need to passcontent_type.-async def run(request: AgentRequest, response: AgentResponse, context: AgentContext): - return response.handoff({"name":"My Other Agent"}, "would you please do this?") +async def run(request: AgentRequest, response: AgentResponse, context: AgentContext): + # Raw string → inferred text/plain + return response.handoff({"name":"My Other Agent"}, "would you please do this?") + # Or JSON → inferred application/json + # return response.handoff({"name":"My Other Agent"}, {"message": "would you please do this?"})
229-231: Use a consistent ID format across docs (hyphen vs underscore).Elsewhere (API reference) uses hyphenated IDs (e.g.,
agent-123). Align here to avoid confusion.- id: 'agent_123456789abcedef', - projectId: 'project_123456789abcedef', + id: 'agent-123456789abcedef', + projectId: 'project-123456789abcedef',- "id": "agent_123456789abcedef", - "projectId": "project_123456789abcedef" + "id": "agent-123456789abcedef", + "projectId": "project-123456789abcedef"Also applies to: 237-239
246-249: Authorization token: specify default TTL if stable.If there’s a standard expiration (e.g., 5–15 minutes), noting it helps users reason about retries and clock skew.
content/SDKs/python/api-reference.mdx (2)
828-835: Python handoff example: prefer raw payload over{ "data": ... }wrapper for consistency.Align with earlier guidance that Python infers content type from the raw payload.
return response.handoff( {"name": "data-processing-agent"}, - {"data": "process this"}, - "application/json", + "process this", # inferred as text/plain {"source": "web-agent"} )Or, if JSON is intentional, pass the actual object shape you want to send, e.g.
{"message": "process this"}and omitcontent_type(it will inferapplication/json).
284-304: Minor import path consistency.Examples alternate between
from agentuity import ...andfrom agentuity.sdk import .... Pick one canonical import style for SDK types in this doc to reduce ambiguity.Also applies to: 543-552, 612-667
content/Guides/vector-db.mdx (1)
244-249: Language note: “returns null” — clarify per language.Use “null (JS) / None (Python)” to avoid confusion.
-- `get` returns `null` if not found, never throws an error +- `get` returns `null` (JS) / `None` (Python) if not found; it never throws for missing keys
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (7)
content/Guides/agent-communication.mdx(7 hunks)content/Guides/agent-data-handling.mdx(3 hunks)content/Guides/agent-streaming.mdx(2 hunks)content/Guides/agent-tracing.mdx(2 hunks)content/Guides/key-value.mdx(6 hunks)content/Guides/vector-db.mdx(6 hunks)content/SDKs/python/api-reference.mdx(6 hunks)
🚧 Files skipped from review as they are similar to previous changes (3)
- content/Guides/agent-tracing.mdx
- content/Guides/agent-data-handling.mdx
- content/Guides/key-value.mdx
🧰 Additional context used
🧠 Learnings (1)
📚 Learning: 2025-07-23T12:40:34.834Z
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
Applied to files:
content/Guides/agent-communication.mdx
⏰ 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 (10)
content/Guides/agent-streaming.mdx (2)
29-35: Good additions to real-world use cases.Clear, practical bullets that map to user scenarios.
73-79: Python: correct async payload access + sensible fallback.
await request.data.text()matches the updated API and the default prompt improves demo resilience.content/Guides/agent-communication.mdx (5)
8-8: Hero image addition looks good.Alt text, sizing, and placement are appropriate.
10-13: Overview reads well and sets the right guidance.Encouraging specialization + composition is clear.
118-125: Invocation examples are aligned (JS uses {data, contentType}; Python passes raw payload).Looks consistent with the platform model.
Also applies to: 128-135
154-166: Parallel execution examples are correct and idiomatic.JS shows optional explicit contentType; Python infers JSON from dicts.
Also applies to: 172-178
36-37: Verify network wording and constraints for inter-organization calls.“Communicate over the internal network” plus “only public targets with known ID” may be inaccurate or incomplete for cross-org. Please confirm intended transport and constraints and adjust phrasing.
Also applies to: 244-244
content/SDKs/python/api-reference.mdx (1)
496-524: Vector Storage get(): concise and matches new API.Return type and example are clear.
content/Guides/vector-db.mdx (2)
69-85: Upsert examples look solid and consistent across JS/Python.Batching and idempotency messaging are clear.
Also applies to: 88-97, 98-123
12-15: Ignore incorrect link change suggestion. The vector-db guide intentionally links to the Cloud service pages—just like other Guides (e.g., key-value.mdx and object-storage.mdx both use/Cloud/...routes)—so no edits are needed here.Likely an incorrect or invalid review comment.
There was a problem hiding this comment.
Actionable comments posted: 3
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
content/Guides/agent-data-handling.mdx (1)
441-453: Fix Python example: await the async text accessor.
request.data.text()is async per this PR’s API changes; withoutawait, it passes a coroutine into the OpenAI message.Apply:
- {"role": "user", "content": request.data.text or "Why is the sky blue?"}, + {"role": "user", "content": (await request.data.text()) or "Why is the sky blue?"},
♻️ Duplicate comments (1)
content/Guides/vector-db.mdx (1)
203-239: Prior comment addressed: Python snippet now imports time.Import is present before usage. ✅
🧹 Nitpick comments (1)
content/SDKs/javascript/api-reference.mdx (1)
273-301: Clarify whether similarity is present in get-by-key results.If
VectorSearchResultincludes asimilarityfield from search, note thatget()may return no similarity (or define it as optional) to prevent confusion for readers. Consider a one-line note under Return Value.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (10)
content/Guides/agent-communication.mdx(7 hunks)content/Guides/agent-data-handling.mdx(3 hunks)content/Guides/agent-streaming.mdx(2 hunks)content/Guides/agent-tracing.mdx(2 hunks)content/Guides/ai-gateway.mdx(1 hunks)content/Guides/key-value.mdx(6 hunks)content/Guides/object-storage.mdx(8 hunks)content/Guides/vector-db.mdx(7 hunks)content/SDKs/javascript/api-reference.mdx(1 hunks)content/SDKs/python/api-reference.mdx(8 hunks)
⏰ 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 (25)
content/Guides/ai-gateway.mdx (1)
3-3: Minor copy edit looks good.Description reads well and matches guide tone.
content/Guides/agent-tracing.mdx (2)
6-7: Good addition of an Overview section.Improves scannability and aligns with other guides.
101-101: Confirmrequest.triggerusage
Ensuretriggeris a property; if it’s a method, call it (request.trigger()) to record its return value instead of the function reference.content/Guides/agent-data-handling.mdx (2)
6-9: Overview improvements read well.Clearer framing without changing semantics.
42-51: Nice normalization of Python indentation.Async accessors and flow look consistent.
content/Guides/agent-streaming.mdx (2)
29-35: Good content additions and heading level tweak.The new bullets clarify practical scenarios.
73-74: Ignore this comment: async text retrieval is already applied in all agent-data-handling examples.Likely an incorrect or invalid review comment.
content/Guides/object-storage.mdx (1)
71-75: Clear split between auto-detect and explicit params.Nice structure; aligns JS inline options with Python
ObjectStorePutParams.content/Guides/key-value.mdx (3)
41-49: JS handler signature + ctx usage standardized.Matches patterns used elsewhere in the guides.
85-89: Verify JS KV.setcontentTypeoption support
The guide example uses acontentTypeoption, but the JS API reference only documentsttl. Confirm whether the underlyingctx.kv.setimplementation acceptscontentType. If it does, addcontentTypeto the JS API reference; if not, remove it from the guide to avoid confusion.
190-197: Document and cross-link 60 s minimum TTL across SDKs
- Link the JavaScript API reference’s “minimum 60 seconds” (content/SDKs/javascript/api-reference.mdx L141) in the key-value guide.
- Add “minimum 60 seconds” to the TTL parameter description in Python (content/SDKs/python/api-reference.mdx) and any other SDKs that omit it.
- Confirm with the backend team that TTL values below 60 s are rejected by the service.
content/Guides/agent-communication.mdx (3)
82-86: JS handoff payload format update is correct.Using
{ data, contentType }matches the new conventions.
128-136: Python invocation: good shift to raw payload with inferred content type.Consistent with other Python examples.
157-167: Parallel exec examples are clear and consistent.Explicit JSON comments help.
content/SDKs/python/api-reference.mdx (3)
1024-1071: Async data accessors documented correctly.json/text/binary examples now await their calls. Good.
1077-1086: Media-specific async accessors look consistent.Examples align with the new async contract.
628-634: Good: clarify bytes literal usage for binary data.Prevents confusion about expected types.
content/SDKs/javascript/api-reference.mdx (1)
273-301: Check for accidental duplicate get section.Please confirm this block wasn’t added twice elsewhere in the page during merge.
content/Guides/vector-db.mdx (7)
6-7: Good addition: clear positioning section.Concise intro helps readers decide when to use vectors.
10-15: Verify internal doc links.Confirm the slugs resolve: /Cloud/key-value-memory and /Cloud/object-storage.
69-93: Upsert examples read well and align with API shapes.JS uses varargs; Python uses a list. Looks consistent and clear.
Also applies to: 119-119
125-138: LGTM on search example.Parameters and result handling look correct.
151-151: No action.Formatting-only change.
163-245: Nice “get vs search” guidance.The examples and bullets set correct expectations on null/None handling and performance.
250-264: Confirm Python bulk delete capability.Doc states “Python SDK currently supports single deletion.” If bulk delete has shipped, update this note and add an example; otherwise, keep as-is.
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (2)
content/Guides/vector-db.mdx (2)
69-93: JS upsert requires an array payload (batch), not multiple objects.Current snippet passes multiple objects as separate args; most SDKs expect a single array of entries. Python example below correctly uses a list.
-const ids = await context.vector.upsert( - 'knowledge-base', - { - key: 'doc-1', - document: 'Agentuity is an agent-native cloud platform', - metadata: { category: 'platform', source: 'docs' } - }, - { - key: 'doc-2', - document: 'Vector storage enables semantic search capabilities', - metadata: { category: 'features', source: 'docs' } - } -); +const ids = await context.vector.upsert( + 'knowledge-base', + [ + { + key: 'doc-1', + document: 'Agentuity is an agent-native cloud platform', + metadata: { category: 'platform', source: 'docs' } + }, + { + key: 'doc-2', + document: 'Vector storage enables semantic search capabilities', + metadata: { category: 'features', source: 'docs' } + } + ] +);-const embeddingIds = await context.vector.upsert( - 'custom-embeddings', - { - key: 'embedding-1', - embeddings: [0.1, 0.2, 0.3, 0.4], - metadata: { id: 'doc-1', type: 'custom' } - } -); +const embeddingIds = await context.vector.upsert( + 'custom-embeddings', + [ + { + key: 'embedding-1', + embeddings: [0.1, 0.2, 0.3, 0.4], + metadata: { id: 'doc-1', type: 'custom' } + } + ] +);
181-190: JS: upsert-after-existence must pass an array.This still shows a single object. Wrap in an array; keep the safe metadata merge you added.
- await context.vector.upsert('products', { + await context.vector.upsert('products', [{ key: 'product-123', document: 'Updated product description', metadata: { ...(existing.metadata ?? {}), lastUpdated: Date.now() } - }); + }]);
🧹 Nitpick comments (6)
content/Guides/vector-db.mdx (6)
2-3: Unify naming: prefer “Vector Storage” over “Vector DB”.Title/description use “Vector DB” while the guide standardizes on “Vector Storage”. Recommend aligning to avoid confusion.
-title: Using Vector DB -description: Using the Vector DB for search and retrieval +title: Vector Storage +description: Semantic search and retrieval with Vector Storage
125-138: Minor: guard optional metadata and format similarity.Avoid runtime errors if metadata is missing; optionally format similarity.
-results.forEach(result => { - console.log(`Found: ${result.metadata.source}`); - console.log(`Similarity: ${result.similarity}`); -}); +results.forEach(result => { + console.log(`Found: ${result.metadata?.source ?? '(no source)'}`); + console.log(`Similarity: ${result.similarity?.toFixed?.(3) ?? result.similarity}`); +});
240-245: Behavior note is helpful; consider clarifying errors vs not-found.You already mention null/None on not-found. Add one sentence that network/auth errors raise exceptions to set user expectations.
250-263: Confirm bulk-delete support and keep SDKs consistent.JS shows multi-key delete, while Python notes single-key only. Please verify JS API supports multiple keys (varargs vs array). If not, switch to single delete or document the supported bulk form for both SDKs.
526-537: Consistency: use the same instance name as earlier (“knowledge-base”).Small coherence tweak.
-let results = await context.vector.search('kb', { +let results = await context.vector.search('knowledge-base', {
95-105: Consistency: use the same key style across JS/Python examples.Keys alternate between hyphens and underscores (doc-1 vs doc_1). Pick one style to reduce reader friction.
Also applies to: 101-104
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
content/Guides/agent-data-handling.mdx(4 hunks)content/Guides/object-storage.mdx(8 hunks)content/Guides/vector-db.mdx(7 hunks)
🚧 Files skipped from review as they are similar to previous changes (2)
- content/Guides/object-storage.mdx
- content/Guides/agent-data-handling.mdx
⏰ 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 (3)
content/Guides/vector-db.mdx (3)
6-7: Section addition reads well.Clear motivation and placement. No issues.
10-15: Verify internal link slugs.Confirm these slugs exist and are canonical for the target pages to avoid 404s or duplicate guides: /Cloud/key-value-memory, /Cloud/object-storage.
203-214: Nice: added missing import and clear get-by-key example.Looks good.
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
content/SDKs/javascript/api-reference.mdx (1)
321-336: Clarify delete() operates on keys (not internal IDs) and fix examples.Examples currently use id1/id2 which can be confused with the result.id from searches. Align with earlier docs that delete takes keys.
Apply this diff to make it unambiguous:
-// Delete a single vector -const deletedCount = await context.vector.delete('product-descriptions', 'id1'); +// Delete a single vector by key +const deletedCount = await context.vector.delete('product-descriptions', 'chair-001'); console.log(`Deleted ${deletedCount} vector(s)`); // Output: Deleted 1 vector(s) -// Delete multiple vectors in bulk (more efficient than individual calls) -const deletedCount = await context.vector.delete('product-descriptions', 'id1', 'id2', 'id3'); +// Delete multiple vectors by key (more efficient than individual calls) +const deletedCount = await context.vector.delete('product-descriptions', 'chair-001', 'headphones-001', 'desk-002'); console.log(`Deleted ${deletedCount} vector(s)`); // Output: Deleted 3 vector(s) -// Delete with array spread -const keysToDelete = ['id1', 'id2', 'id3']; +// Delete with array spread +const keysToDelete = ['chair-001', 'headphones-001', 'desk-002']; const deletedCount = await context.vector.delete('product-descriptions', ...keysToDelete); -// Handle cases where some vectors might not exist -const deletedCount = await context.vector.delete('product-descriptions', 'existing-id', 'non-existent-id'); +// Handle cases where some vectors might not exist +const deletedCount = await context.vector.delete('product-descriptions', 'existing-key', 'non-existent-key'); console.log(`Deleted ${deletedCount} vector(s)`); // Output: Deleted 1 vector(s)
♻️ Duplicate comments (1)
content/SDKs/python/api-reference.mdx (1)
828-835: Fix handoff example: metadata passed into content_type positional slot.This was flagged earlier and still present. Use a keyword for metadata (or insert None for content_type).
return response.handoff( - {"name": "data-processing-agent"}, # params - "process this", # args (inferred as text/plain) - {"source": "web-agent"} # metadata + {"name": "data-processing-agent"}, # params + "process this", # payload (inferred as text/plain) + metadata={"source": "web-agent"} # metadata (keyword arg) )
🧹 Nitpick comments (3)
content/SDKs/javascript/api-reference.mdx (1)
1484-1484: Tiny consistency nit: include structured context in child logger calls.Match prior guidance by adding a small context object (e.g., requestId).
-requestLogger.info('Processing request'); +requestLogger.info('Processing request', { requestId: 'req_123' });content/Guides/agent-logging.mdx (1)
48-51: Clarify Python supports structured logging via standard patterns.Mention Python’s logging supports structure via extra, dictConfig/JSON formatters even if child() isn’t exposed yet, to avoid implying strings-only.
content/SDKs/python/api-reference.mdx (1)
525-553: Confirm cross-language difference: bulk delete support.JS docs show delete(...keys: string[]) returning count; Python shows delete(name, key) -> int (single key). If Python supports bulk deletes, document it; if not, call out the difference explicitly.
I can draft a short note in both SDK references clarifying this behavior once confirmed.
Also applies to: 303-341
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
content/Guides/agent-logging.mdx(1 hunks)content/SDKs/javascript/api-reference.mdx(2 hunks)content/SDKs/python/api-reference.mdx(10 hunks)
🧰 Additional context used
🧠 Learnings (2)
📚 Learning: 2025-07-23T12:40:22.412Z
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")`
Applied to files:
content/SDKs/javascript/api-reference.mdxcontent/Guides/agent-logging.mdxcontent/SDKs/python/api-reference.mdx
📚 Learning: 2025-07-23T12:40:34.834Z
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
Applied to files:
content/Guides/agent-logging.mdx
⏰ 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 (5)
content/SDKs/javascript/api-reference.mdx (1)
273-302: Vector Storage get(): looks good and consistent with Guides/Python.Clear params/return contract and example. No issues.
content/Guides/agent-logging.mdx (2)
153-161: Use consistent attribute naming for Python context properties.Snippet mixes context.agent_id (snake_case) with context.sessionId (camelCase). Align both to the actual SDK attributes.
Would you confirm the canonical names? If they’re snake_case in Python, prefer context.agent_id and context.session_id.
213-230: Child logger pattern (JS) is solid.Good use of component scoping and structured fields.
content/SDKs/python/api-reference.mdx (2)
496-524: Vector Storage get(): API shape and example look correct.Matches JS and Guides; return typing and not-found behavior are clear.
1024-1100: Async request.data accessors: consistent and clear.json/text/binary and media helpers now async; examples align.
There was a problem hiding this comment.
Actionable comments posted: 0
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (3)
content/Guides/vector-db.mdx (1)
69-93: JS upsert examples pass objects/varargs; API expects an array.Update both text and embeddings examples to pass a single array of documents.
-const ids = await context.vector.upsert( - 'knowledge-base', - { - key: 'doc-1', - document: 'Agentuity is an agent-native cloud platform', - metadata: { category: 'platform', source: 'docs' } - }, - { - key: 'doc-2', - document: 'Vector storage enables semantic search capabilities', - metadata: { category: 'features', source: 'docs' } - } -); +const ids = await context.vector.upsert('knowledge-base', [ + { + key: 'doc-1', + document: 'Agentuity is an agent-native cloud platform', + metadata: { category: 'platform', source: 'docs' } + }, + { + key: 'doc-2', + document: 'Vector storage enables semantic search capabilities', + metadata: { category: 'features', source: 'docs' } + } +]);-const embeddingIds = await context.vector.upsert( - 'custom-embeddings', - { - key: 'embedding-1', - embeddings: [0.1, 0.2, 0.3, 0.4], - metadata: { id: 'doc-1', type: 'custom' } - } -); +const embeddingIds = await context.vector.upsert('custom-embeddings', [ + { + key: 'embedding-1', + embeddings: [0.1, 0.2, 0.3, 0.4], + metadata: { id: 'doc-1', type: 'custom' } + } +]);Also applies to: 119-119
content/SDKs/python/api-reference.mdx (2)
253-255: Fix Python logging call; extra positional arg breaks %-formatting.Use formatting or f-string with a single argument.
- context.logger.error("Error processing request", error) + context.logger.error("Error processing request: %s", error) + # or + # context.logger.error(f"Error processing request: {error}")
1392-1411: Use a sync context manager for OpenTelemetry spans.tracer.start_as_current_span() is a synchronous context manager — use
with, notasync with(unless your SDK wrapper explicitly returns an async context manager). (opentelemetry-python.readthedocs.io)-async with context.tracer.start_as_current_span("process-data") as span: +with context.tracer.start_as_current_span("process-data") as span:
♻️ Duplicate comments (1)
content/Guides/vector-db.mdx (1)
185-190: JS upsert after existence check still not an array.Wrap the single object in an array to match the API. This was flagged earlier.
- await context.vector.upsert('products', { + await context.vector.upsert('products', [{ key: 'product-123', document: 'Updated product description', metadata: { ...(existing.metadata ?? {}), lastUpdated: Date.now() } - }); + }]);
🧹 Nitpick comments (6)
content/Guides/vector-db.mdx (3)
2-3: Rename to “Vector Storage” for consistency.Most of the guide uses “Vector Storage”; align the title/description.
-title: Using Vector DB -description: Using the Vector DB for search and retrieval +title: Using Vector Storage +description: Using vector storage for search and retrieval
149-151: Avoid KeyError on missing metadata fields.Use .get() when reading optional metadata.
-for result in results: - print(f"Found: {result.metadata['source']}") - print(f"Similarity: {result.similarity}") +for result in results: + print(f"Found: {result.metadata.get('source')}") + print(f"Similarity: {result.similarity}")
256-259: Confirm JS bulk-delete signature (varargs vs array).If delete expects a list/array, this varargs form will mislead readers. Consider an array example or document both forms explicitly.
Would you like me to update this to an array form once you confirm the JS SDK signature?
-const bulkDeleteCount = await context.vector.delete( - 'knowledge-base', - 'doc-1', 'doc-2', 'doc-3' -); +// If array form is required: +const bulkDeleteCount = await context.vector.delete('knowledge-base', ['doc-1', 'doc-2', 'doc-3']);content/SDKs/python/api-reference.mdx (3)
498-509: Type hint style for broader Python version compatibility.Prefer Optional[...] over union operator in docs unless 3.10+ is guaranteed.
-`async get(name: str, key: str) -> VectorSearchResult | None` +`async get(name: str, key: str) -> Optional[VectorSearchResult]`
284-304: Standardize imports for AgentContext across examples.Examples alternate between
from agentuity import AgentContextandfrom agentuity.sdk import AgentContext. Pick one canonical path and use it consistently.If
AgentContextis re-exported at the top level, suggest switching all tofrom agentuity import AgentContextfor simplicity. Want me to submit a pass normalizing these imports?Also applies to: 388-424, 470-494, 543-552, 720-753
912-923: Clarify async vs sync for Response helpers.Elsewhere you upgraded request data accessors to async; verify whether response helpers (e.g., png(), mp4()) are sync (builder-style) or async. If async, mark them
asyncfor consistency.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (4)
content/Guides/agent-logging.mdx(1 hunks)content/Guides/vector-db.mdx(7 hunks)content/SDKs/javascript/api-reference.mdx(3 hunks)content/SDKs/python/api-reference.mdx(10 hunks)
🚧 Files skipped from review as they are similar to previous changes (2)
- content/SDKs/javascript/api-reference.mdx
- content/Guides/agent-logging.mdx
🧰 Additional context used
🧠 Learnings (1)
📚 Learning: 2025-07-23T12:40:22.412Z
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")`
Applied to files:
content/SDKs/python/api-reference.mdx
⏰ 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
get_agent)vector.get()usage to API reference, examples in GuidesSummary by CodeRabbit
New Features
Documentation