Docs updates #343
Docs updates #343
Conversation
📝 WalkthroughWalkthroughDocumentation updates across Agents, CLI, Sandbox, Storage, Observability, and Services: added multiple "Why..." sections, changed AgentContext examples from Changes
🚥 Pre-merge checks | ✅ 1✅ Passed checks (1 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. 📜 Recent review detailsConfiguration used: Organization UI Review profile: CHILL Plan: Pro ⛔ Files ignored due to path filters (1)
📒 Files selected for processing (2)
🧰 Additional context used🪛 LanguageToolcontent/Services/queues.mdx[uncategorized] ~20-~20: If this is a compound adjective that modifies the following noun, use a hyphen. (EN_COMPOUND_ADJECTIVE_INTERNAL) 🔇 Additional comments (13)
✏️ Tip: You can disable this entire section by setting 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 |
![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
🤖 Fix all issues with AI agents
In `@content/Services/queues.mdx`:
- Around line 237-257: The snippet uses an undefined agent context `ctx`
(ctx.logger.warn) while calling listDeadLetterMessages/replayDeadLetterMessage;
replace the undefined `ctx.logger.warn` call with a standalone logger such as
`console.warn` (or remove the log) inside the for loop that iterates `messages`,
ensuring the references to `msg.id`, `msg.failure_reason`, and
`msg.delivery_attempts` remain the same so the loop and calls to
replayDeadLetterMessage(client, 'order-processing', msg.id) continue to work in
a non-agent standalone context.
In `@content/Services/Storage/durable-streams.mdx`:
- Around line 18-21: The doc currently calls streams "permanent" and "permanent
public URLs" but the Best Practices also instructs to "Delete streams after
they're no longer needed"; update the wording to remove the absolute "permanent"
claim: change phrases like "permanent" and "permanent public URL" to "durable
while retained", "durable public URL", or "accessible via their URL", and add
one sentence noting streams can be deleted and are immutable only for the
duration of their retention; also briefly mention that retention/delete behavior
and access control (ACL/permissions) determine how long URLs remain accessible
so readers know deletion/retention policies affect permanence.
🧹 Nitpick comments (6)
content/Reference/CLI/development.mdx (1)
175-180: Add a brief security caveat for public URLs.Since public URLs can expose local endpoints, a short note about auth/secret validation (e.g., for webhook signatures) would help prevent accidental exposure.
✍️ Suggested doc addition
**Example use cases:** - Testing Slack, Discord, or Twilio webhooks - Sharing with team members - Testing from mobile devices - OAuth callback URLs + +> Tip: Treat public URLs as internet‑exposed endpoints—validate webhook signatures and require auth where possible.content/Agents/evaluations.mdx (1)
8-22: Avoid absolute claims about production-wide eval execution.“Run on every session in production” sounds unconditional. If evals can be scoped, disabled, or rate‑limited, consider softer phrasing.
✍️ Suggested wording adjustment (if configurable)
- Agentuity evals test the whole run—every tool call, state change, and orchestration step. They run on every session in production, so you catch issues with real traffic. + Agentuity evals test the whole run—every tool call, state change, and orchestration step. They can run on production sessions (when enabled), so you catch issues with real traffic.content/Services/Observability/sessions-debugging.mdx (1)
8-21: Confirm “time‑travel debugging” and full thread preservation are accurate.If replay/time‑travel is gated or only available in certain tiers, consider qualifying that bullet, and avoid implying all threads are always preserved.
✍️ Suggested wording adjustment (if conditional)
- Agentuity tracks all of this automatically. Every run ties to a session. Every conversation thread is preserved. You get full context into what happened, when, and why—*without* writing tracking code. + Agentuity tracks all of this automatically. Every run ties to a session. Conversation threads are preserved (per retention settings), giving full context into what happened, when, and why—*without* writing tracking code. - **Time-travel debugging**: Replay what happened in a session to reproduce issues + **Time-travel debugging**: Replay what happened in a session (where supported) to reproduce issuescontent/Reference/CLI/deployment.mdx (1)
135-141: Clarify that Domains/DNS fields are conditional.Consider noting that these fields appear only when custom domains are configured to avoid implying they always show.
Suggested wording tweak
- - DNS records (for custom domain configuration) + - DNS records (only when custom domains are configured) - Domains: api.example.com - DNS Records: api.example.com CNAME p1234567890.agentuity.cloud + Domains: api.example.com (custom domains only) + DNS Records: api.example.com CNAME p1234567890.agentuity.cloud (custom domains only)Also applies to: 145-153
content/Services/Sandbox/sdk-usage.mdx (1)
437-479: Clarify optionality for conditional SandboxInfo fields.The examples use null-checks for
user,agent, andproject, implying these fields are optional. Reflecting that in the table avoids ambiguity.📝 Suggested table clarification
-| `networkPort` | `number` | Port exposed from sandbox (if configured) | -| `url` | `string` | Public URL (when port is configured) | -| `user` | `SandboxUserInfo` | User who created the sandbox | -| `agent` | `SandboxAgentInfo` | Agent that created the sandbox | -| `project` | `SandboxProjectInfo` | Associated project | +| `networkPort` | `number \| undefined` | Port exposed from sandbox (if configured) | +| `url` | `string \| undefined` | Public URL (when port is configured) | +| `user` | `SandboxUserInfo \| undefined` | User who created the sandbox | +| `agent` | `SandboxAgentInfo \| undefined` | Agent that created the sandbox | +| `project` | `SandboxProjectInfo \| undefined` | Associated project |content/Services/Sandbox/index.mdx (1)
176-177: Add the dependency note fornetwork.port.Consider mirroring the requirement that
network.enabled: trueis needed when exposing a port.📝 Suggested wording
-| `network.port` | Port to expose to internet (1024-65535) | `3000` | +| `network.port` | Port to expose to internet (1024-65535; requires `network.enabled: true`) | `3000` |
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (14)
content/Agents/evaluations.mdxcontent/Agents/standalone-execution.mdxcontent/Agents/workbench.mdxcontent/Reference/CLI/configuration.mdxcontent/Reference/CLI/deployment.mdxcontent/Reference/CLI/development.mdxcontent/Reference/CLI/getting-started.mdxcontent/Reference/CLI/storage.mdxcontent/Services/Observability/sessions-debugging.mdxcontent/Services/Sandbox/index.mdxcontent/Services/Sandbox/sdk-usage.mdxcontent/Services/Storage/durable-streams.mdxcontent/Services/Storage/key-value.mdxcontent/Services/queues.mdx
🧰 Additional context used
🪛 LanguageTool
content/Services/queues.mdx
[uncategorized] ~20-~20: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ...ndpoints - Handle bursty workloads with rate limiting - Retry failed operations with exponent...
(EN_COMPOUND_ADJECTIVE_INTERNAL)
🔇 Additional comments (23)
content/Reference/CLI/development.mdx (1)
153-173: Verify Gravity claims and example output match current CLI behavior.Please confirm the HTTPS/cert generation, “secure tunneling,” and “automatic reconnection” claims, and that the “Agentuity DevMode” output format is accurate. If there’s an authoritative Gravity/CLI reference, consider linking it here for durability.
content/Agents/workbench.mdx (1)
8-19: Validate Workbench capability claims (metrics/token usage).Please confirm that Workbench always shows token usage and response times for every request. If metrics require specific config or aren’t available for all models, soften the wording to avoid overpromising.
✍️ Suggested wording adjustment (if conditional)
-- **Execution metrics**: See token usage and response times for every request +- **Execution metrics**: See token usage (when available) and response times for requestscontent/Reference/CLI/configuration.mdx (1)
121-171: Verify--orgflag shorthand and org-selection command name.Examples use
--orgwithout a value to target the default org and referenceagentuity auth org select. Please confirm both match the CLI’s actual syntax/verbs; otherwise adjust to the correct form (e.g.,--org <org-id>).content/Reference/CLI/deployment.mdx (2)
8-20: Nice concise rationale section.Clear value proposition and feature framing; reads well.
167-169: DNS callout is helpful.Good placement to reinforce how to validate custom domain setup.
content/Reference/CLI/getting-started.mdx (4)
95-125: Confirm organization/region preference command verbs.Please verify the CLI uses
agentuity auth org select/current/unselectandagentuity cloud region select/current/unselectexactly as shown; update if the verbs differ.
165-175: Verify new project-creation flags and accepted values.Ensure
--database,--storage, and--enable-authare the correct flag names and that the documented value set (skip,new, or existing name) matches CLI behavior.
186-213: Headless examples look solid.Examples are clear and align with automation use cases.
263-282: Confirm import validation and auto-reconciliation behavior.Please verify the stated validation criteria (
@agentuity/runtimeplusagentuity.config.tsoragentuity/directory) and the auto-prompt behavior duringagentuity dev/deployfor unregistered projects.content/Reference/CLI/storage.mdx (1)
16-18: Org-scoped KV callout is clear.Good clarification for directory/project context expectations.
content/Services/Storage/key-value.mdx (3)
155-163: ConfirmcreateNamespaceoption name anddefaultTTLSecondssemantics.Please verify the option name and that
defaultTTLSeconds: 0truly means “never expire,” and3600applies to all keys by default. This is API‑behavior‑dependent.
173-183: Verify TTL range and sliding-expiration threshold.The table claims a 60–7,776,000s range and the callout specifies auto-extension when <50% TTL remains. Please confirm these exact limits/thresholds match the KV service behavior.
191-191: Confirm the “7 days default TTL” statement.Ensure the default TTL (when unspecified at both namespace and key level) is indeed 7 days and consistent with the behavior above.
content/Agents/standalone-execution.mdx (5)
18-20: Basicctx.runexample is clear and concise.
Nice update to the new entry point without extra ceremony.
22-32: No-input usage + legacy callout reads well.
This should ease migration and clarify the preferred pattern.
56-59: Cron example aligns cleanly with the new invocation style.
Looks consistent with the rest of the page.
112-133: Runtime detection utility example is a strong addition.
Good dual-path guidance for inside vs. outside runtime usage.
68-83: Resolve the session/tracing context behavior inconsistency.
Line 83 states eachctx.run()call shares the same session and tracing context, while line 92 states each run gets its own session and tracing span. These statements conflict. Confirm whether the difference is due to thetriggerparameter (line 90 uses{ trigger: 'websocket' }) or if one statement is incorrect, then align the documentation.Also applies to: 92-95
content/Services/Sandbox/sdk-usage.mdx (3)
151-165: Clear and practical project association example.Nice, concise flow for creating and listing by
projectId.
396-397: Config reference stays aligned with the new options.Good addition of
network.portandprojectIdin the options table.
124-145: Clarify howsandbox.execute()handles long-running processes in the port exposure example.The code calls
await sandbox.execute({ command: ['npm', 'run', 'serve'] })followed byctx.sandbox.get(sandbox.id)to retrieve the server URL. Ifexecute()waits for process completion, the server command will block indefinitely and the subsequent code won't run. The documentation doesn't explicitly specify whetherexecute()blocks on long-running processes or whether backgrounding is required. Either clarify the expected behavior in the example or show how to properly start a long-running service without blocking—for example, using the streaming stdout API or documenting support for detached/background process flags.content/Services/Sandbox/index.mdx (2)
8-22: Strong rationale section.Clear and persuasive framing of isolation and lifecycle benefits.
80-94: Runtime metadata section reads well.Helpful list of fields and a concise command pointer.
✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@content/Services/queues.mdx`:
- Around line 146-168: The code examples in the Programmatic Management section
reference a `client` parameter used in functions like `createQueue`,
`listQueues`, and `deleteQueue`, but the documentation never shows how to
initialize or create this client object. Add a code example at the beginning of
the Programmatic Management section that demonstrates how to create the client
using `createServerFetchAdapter` with proper Authorization headers configured
with the AGENTUITY_SDK_KEY environment variable. This will allow readers to
actually run the provided code snippets.
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (4)
content/Agents/evaluations.mdxcontent/Services/Observability/sessions-debugging.mdxcontent/Services/Storage/durable-streams.mdxcontent/Services/queues.mdx
🚧 Files skipped from review as they are similar to previous changes (1)
- content/Agents/evaluations.mdx
🧰 Additional context used
🪛 LanguageTool
content/Services/queues.mdx
[uncategorized] ~20-~20: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ...ndpoints - Handle bursty workloads with rate limiting - Retry failed operations with exponent...
(EN_COMPOUND_ADJECTIVE_INTERNAL)
🔇 Additional comments (8)
content/Services/Observability/sessions-debugging.mdx (1)
8-21: LGTM!The "Why Sessions?" section provides clear rationale for the feature. The explanation of traditional observability limitations versus agent-specific needs is well-articulated, and the bullet points effectively summarize the practical benefits.
content/Services/Storage/durable-streams.mdx (1)
6-21: LGTM!The updates effectively address the previous review concern about the "permanent" terminology. Line 6 now correctly states streams are "accessible via URL until deleted," and the bullet point uses "Durable artifacts" instead of "Permanent artifacts." The "Why Durable Streams?" section clearly articulates the problem with WebSocket/SSE fragility during LLM streaming and explains how durable streams solve it.
content/Services/queues.mdx (6)
1-29: Well-structured introduction and overview.The comparison table, use cases, and queue type explanations provide clear guidance for users deciding when to use queues versus other storage options.
30-92: LGTM!The publishing examples correctly demonstrate
ctx.queue.publish()within agent handlers, with comprehensive options documentation and clear result interface.
94-117: Good error handling pattern.The example demonstrates proper typed error handling with
QueueNotFoundErrorandQueueValidationError, providing clear recovery paths.
170-218: LGTM!The webhook destination configuration with retry policy and the pull-based ack/nack consumption pattern are well-documented. The
clientinitialization gap applies here as well (covered in previous comment).
237-260: Context initialization issue resolved.The code now correctly uses
createAgentContext()to obtain a validctxobject for logging. The explanatory note on line 259 linking to standalone execution documentation is helpful.Note: The
clientvariable remains undefined here as well (same documentation gap noted in the Queue Management section).
261-324: Comprehensive reference sections.The HTTP ingestion sources, queue settings, validation limits, and best practices provide excellent reference material. The auth type options and default settings tables are particularly useful.
✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.
content/Services/queues.mdx
Outdated
| ### Programmatic Management | ||
|
|
||
| Use `@agentuity/server` for full queue management in routes or standalone scripts: | ||
|
|
||
| ```typescript | ||
| import { createQueue, listQueues, deleteQueue } from '@agentuity/server'; | ||
|
|
||
| // Create a queue | ||
| const queue = await createQueue(client, { | ||
| name: 'order-processing', | ||
| queue_type: 'worker', | ||
| settings: { | ||
| default_max_retries: 5, | ||
| default_visibility_timeout_seconds: 60, | ||
| }, | ||
| }); | ||
|
|
||
| // List queues | ||
| const { queues } = await listQueues(client); | ||
|
|
||
| // Delete a queue | ||
| await deleteQueue(client, 'old-queue'); | ||
| ``` |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# First, let's find and read the queues.mdx file to see the context
find . -name "queues.mdx" -type f | head -5Repository: agentuity/docs
Length of output: 87
🏁 Script executed:
# Search for createClient documentation
rg "createClient" --type md --type mdx -n -B 2 -A 5Repository: agentuity/docs
Length of output: 85
🏁 Script executed:
# Search for client initialization patterns in documentation
rg "client.*=.*createClient|const.*client" --type md --type mdx -n -A 2Repository: agentuity/docs
Length of output: 85
🏁 Script executed:
# Look for any client initialization or setup documentation
rg "initialize.*client|setup.*client|client.*initialization" --type md --type mdx -n -B 2 -A 3 -iRepository: agentuity/docs
Length of output: 85
🏁 Script executed:
# Read the queues.mdx file to see context around lines 146-168
wc -l ./content/Services/queues.mdxRepository: agentuity/docs
Length of output: 91
🏁 Script executed:
# Read lines around 146-168 to see full context
sed -n '1,180p' ./content/Services/queues.mdx | cat -nRepository: agentuity/docs
Length of output: 6372
🏁 Script executed:
# Search for createClient without type restrictions
rg "createClient" -n -B 2 -A 5Repository: agentuity/docs
Length of output: 3021
🏁 Script executed:
# Search for any client setup or initialization examples
rg "client.*=|import.*client" -n -B 1 -A 3 | head -100Repository: agentuity/docs
Length of output: 9318
🏁 Script executed:
# Search for `@agentuity/server` usage in documentation
rg "@agentuity/server" -n -B 2 -A 8Repository: agentuity/docs
Length of output: 19147
🏁 Script executed:
# Look at webhook destination code which also uses client
sed -n '170,195p' ./content/Services/queues.mdx | cat -nRepository: agentuity/docs
Length of output: 832
🏁 Script executed:
# Search for any server-side client initialization or setup documentation
rg "server.*client|Server.*API|API.*key" -i -n | head -50Repository: agentuity/docs
Length of output: 16748
Add documentation for initializing the client object in server-side queue management examples.
The code examples in this section (and subsequent sections: webhook destinations, pull-based consumption, DLQ operations, HTTP sources) use a client parameter in createQueue(client, ...), listQueues(client), deleteQueue(client, ...), and similar functions, but never show how to create or obtain this client. Readers cannot run these code snippets without knowing client initialization.
Add an example showing client setup, e.g.:
import { createServerFetchAdapter } from '@agentuity/server';
const client = createServerFetchAdapter({
headers: {
Authorization: `Bearer ${process.env.AGENTUITY_SDK_KEY}`,
},
});🤖 Prompt for AI Agents
In `@content/Services/queues.mdx` around lines 146 - 168, The code examples in the
Programmatic Management section reference a `client` parameter used in functions
like `createQueue`, `listQueues`, and `deleteQueue`, but the documentation never
shows how to initialize or create this client object. Add a code example at the
beginning of the Programmatic Management section that demonstrates how to create
the client using `createServerFetchAdapter` with proper Authorization headers
configured with the AGENTUITY_SDK_KEY environment variable. This will allow
readers to actually run the provided code snippets.
Summary by CodeRabbit
Documentation
New Features
✏️ Tip: You can customize this high-level summary in your review settings.