Docs updates #343
Docs updates #343
Conversation
📝 WalkthroughWalkthroughDocumentation expanded across Agents, CLI, Services, and Learning. Notable factual changes: Agent invocation pattern documented as ctx.run(agent, input) with new isInsideAgentRuntime(), SandboxInfo and sandbox options added, TTL semantics extended across storage, and comprehensive Queues documentation introduced. 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 selected for processing (2)
🚧 Files skipped from review as they are similar to previous changes (1)
🔇 Additional comments (4)
✏️ 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.
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@content/Services/Sandbox/sdk-usage.mdx`:
- Around line 137-139: The line awaiting the long-running server prevents
subsequent URL logging from executing; remove the await on sandbox.execute({
command: ['npm','run','serve'] }) so the server is started in the background
(optionally capture the returned promise in a variable like serverPromise if you
need to manage or await it later), ensuring the URL logging code runs
immediately after.
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (5)
content/Agents/creating-agents.mdxcontent/Agents/streaming-responses.mdxcontent/Routes/sse.mdxcontent/Services/Sandbox/sdk-usage.mdxcontent/Services/Storage/vector.mdx
✅ Files skipped from review due to trivial changes (2)
- content/Services/Storage/vector.mdx
- content/Routes/sse.mdx
🔇 Additional comments (3)
content/Agents/streaming-responses.mdx (1)
53-55: Clear, actionable guidance for AI SDK streaming.
This callout succinctly clarifies the integration path and reduces misuse.content/Agents/creating-agents.mdx (1)
200-208: LGTM!The new guidance is accurate and well-presented. Letting TypeScript infer types from schemas avoids potential type mismatches that could occur when explicit annotations conflict with schema-derived types. The good/bad pattern makes the advice immediately actionable, and all existing examples in the file already follow this convention.
content/Services/Sandbox/sdk-usage.mdx (1)
140-143: No action needed—the identifier naming is consistent across different object types.The example correctly uses
sandbox.idbecausesandboxis the object returned byctx.sandbox.create(). The reference section usessandboxIdbecause it documents theSandboxInfoobject returned byctx.sandbox.get(). These are different types with appropriately named properties, so the code snippet at line 141 is correct.
✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.
| // Start a web server inside the sandbox | ||
| await sandbox.execute({ command: ['npm', 'run', 'serve'] }); | ||
|
|
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# First, let's look at the full context around lines 137-139
cat -n content/Services/Sandbox/sdk-usage.mdx | sed -n '120,160p'Repository: agentuity/docs
Length of output: 1407
🏁 Script executed:
# Search for documentation about sandbox.execute behavior
rg -i "sandbox\.execute|execute.*command" content/Services/Sandbox/sdk-usage.mdx -A 2 -B 2Repository: agentuity/docs
Length of output: 1163
🏁 Script executed:
# Look for other examples of long-running processes or server commands
rg -i "npm.*serve|long.running|background" content/Services/Sandbox/sdk-usage.mdx -B 2 -A 2Repository: agentuity/docs
Length of output: 424
Remove await to prevent blocking the URL logging code.
The npm run serve command runs indefinitely, so await sandbox.execute() will never complete and the URL logging code below will never run. Remove the await to start the server in the background.
Suggested fix
-// Start a web server inside the sandbox
-await sandbox.execute({ command: ['npm', 'run', 'serve'] });
+// Start a web server inside the sandbox (runs in background)
+sandbox.execute({ command: ['npm', 'run', 'serve'] });🤖 Prompt for AI Agents
In `@content/Services/Sandbox/sdk-usage.mdx` around lines 137 - 139, The line
awaiting the long-running server prevents subsequent URL logging from executing;
remove the await on sandbox.execute({ command: ['npm','run','serve'] }) so the
server is started in the background (optionally capture the returned promise in
a variable like serverPromise if you need to manage or await it later), ensuring
the URL logging code runs immediately after.
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Fix all issues with AI agents
In `@content/Reference/CLI/deployment.mdx`:
- Around line 409-429: Update the `--confirm` table row to match the example
wording (e.g., change "Confirm region change without prompting" to "Skip
confirmation prompts (useful for CI/CD)"), and add a brief note (or
parenthetical) next to the `--dry-run` table entry stating it is a global option
that must precede the subcommand; also adjust the example block so `--dry-run`
appears before `deploy` (replace the line `agentuity --dry-run deploy` with the
global-option-first form) to keep table descriptions and examples consistent
(update entries referencing `--confirm` and `--dry-run` in the table and the
example block).
In `@content/Reference/CLI/development.mdx`:
- Around line 52-80: The docs currently state the inspector listens on port 9229
by default; update the text in the Debugging with Inspector section to explain
that Bun dynamically selects an available port and prints the chosen port to
stdout (and that you can force a specific port with --inspect=9229), and modify
the VS Code launch example to either instruct users to read the printed port and
use that value when attaching or to show how to use a fixed port via
--inspect=9229; update references to the flags (--inspect, --inspect-wait,
--inspect-brk) to reflect this behavior.
In `@content/Services/Storage/queue.mdx`:
- Around line 1-4: Two docs named queue.mdx and queues.mdx are duplicates;
decide to consolidate or split by purpose. Fix by comparing both files, merge
unique content into a single canonical doc (rename to one filename) or clearly
separate responsibilities (e.g., "Storage queue patterns" vs "General queue
patterns") and update frontmatter titles/descriptions accordingly, remove the
redundant file, and update any links/sidebars referencing the removed file so
docs build correctly.
🧹 Nitpick comments (8)
content/Services/Sandbox/index.mdx (1)
8-22: Minor content duplication with existing Callout.Line 20 ("Multi-language support") repeats nearly the same text as the Callout at lines 31-33. Consider consolidating to avoid redundancy—either keep the bullet point brief (e.g., "Multi-language support: Run Python, Node.js, shell scripts, and more") and let the Callout provide details, or remove the overlap entirely.
content/Learn/Cookbook/Patterns/llm-as-a-judge.mdx (1)
66-72: Model names appear to be placeholders.The model identifiers
gpt-5-miniandopenai/gpt-oss-120bdon't correspond to currently available models. Consider using actual model names (e.g.,gpt-4o-mini,llama-3.3-70b-versatile) or adding a note that these are example placeholders that readers should replace with their preferred models.content/Agents/schema-libraries.mdx (1)
106-127: Verifys.toJSONSchemaAPI + consider noting provider-specific wrapping.Please confirm that
s.toJSONSchemaand the{ strict: true }option are correct for the current@agentuity/schemaAPI. Also consider adding a brief note that some LLM providers may require wrapping the schema (e.g., name/metadata) rather than sending the raw JSON Schema directly.✍️ Optional clarification
<Callout type="tip" title="Strict Mode for LLMs"> Use `{ strict: true }` when generating schemas for LLM structured output (e.g., OpenAI's `response_format`). Strict mode ensures the schema is compatible with model constraints and produces more reliable outputs. +Note: Some LLM APIs require wrapping the JSON Schema with additional metadata rather than sending it as a raw schema object. </Callout>content/Reference/CLI/opencode-plugin.mdx (1)
57-74: Duplicate content: Model Configuration appears twice in this document.The "Model Configuration" section here (lines 57-74) and the "Agent Model Overrides" section (lines 218-234) contain nearly identical JSON examples showing how to override agent models. Consider consolidating to avoid maintenance burden and reader confusion.
Options:
- Keep only the Configuration section (lines 218-234) and reference it from here
- Keep this section brief and link to the detailed Configuration section below
content/Reference/CLI/ai-commands.mdx (1)
136-157: Consider noting this duplicates content from OpenCode Plugin docs.The Cadence Commands section here is nearly identical to the "Managing Cadence Tasks" section in
/Reference/CLI/opencode-plugin.mdx(lines 136-156). While some duplication aids discoverability, consider adding a brief note like "See OpenCode Plugin for more details on the Cadence system" to connect the two and avoid future drift.content/Reference/CLI/deployment.mdx (3)
116-133: Clarify DNS records output for multiple domains.
If multiple custom domains are configured, the CLI likely shows multiple DNS records. Consider making that explicit to avoid ambiguity.📝 Suggested wording tweak
- - DNS records (for custom domain configuration) + - DNS records (for custom domain configuration; multiple entries if several domains are configured)
246-261: Consider clarifying preview environment lifecycle.
A brief note on when preview environments are cleaned up (e.g., on PR close/merge) would set expectations.
380-404: Add a warning about deleting machines’ impact.
Deleting a machine may disrupt running deployments; a short warning/callout would help prevent accidental outages.
⚠️ Optional callout addition+<Callout type="warning" title="Machine Deletion Impact"> +Deleting a machine can interrupt workloads running on it. Consider removing machines only after workloads are migrated or idle. +</Callout>
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (21)
content/Agents/creating-agents.mdxcontent/Agents/evaluations.mdxcontent/Agents/schema-libraries.mdxcontent/Get-Started/quickstart.mdxcontent/Learn/Cookbook/Patterns/llm-as-a-judge.mdxcontent/Learn/Cookbook/Patterns/meta.jsoncontent/Learn/Cookbook/overview.mdxcontent/Reference/CLI/ai-commands.mdxcontent/Reference/CLI/debugging.mdxcontent/Reference/CLI/deployment.mdxcontent/Reference/CLI/development.mdxcontent/Reference/CLI/getting-started.mdxcontent/Reference/CLI/meta.jsoncontent/Reference/CLI/opencode-plugin.mdxcontent/Services/Sandbox/index.mdxcontent/Services/Storage/database.mdxcontent/Services/Storage/durable-streams.mdxcontent/Services/Storage/key-value.mdxcontent/Services/Storage/meta.jsoncontent/Services/Storage/queue.mdxcontent/Services/Storage/vector.mdx
🚧 Files skipped from review as they are similar to previous changes (2)
- content/Reference/CLI/getting-started.mdx
- content/Agents/evaluations.mdx
🔇 Additional comments (45)
content/Services/Sandbox/index.mdx (2)
93-107: LGTM!The Runtime Metadata section is well-structured, with a clear table of fields and a helpful CLI command for viewing details. Consistent with the document's formatting.
189-190: LGTM!New configuration options are documented clearly and consistently with the existing table format. The port range (1024-65535) correctly avoids privileged ports.
content/Learn/Cookbook/Patterns/meta.json (1)
7-7: LGTM!The new entry is correctly placed in alphabetical order and aligns with the corresponding
llm-as-a-judge.mdxfile added in this PR.content/Learn/Cookbook/Patterns/llm-as-a-judge.mdx (6)
1-37: LGTM!Clear introduction with helpful decision tables for when to use LLM-as-judge and the inline vs evals distinction. The callout appropriately links to the evaluations documentation.
178-180: Verify the SDK Explorer link.The link
(/)points to the root path. This likely should point to a specific SDK Explorer page or demo. If the SDK Explorer is at the root, this is fine, but if it's at a different path (e.g.,/sdk-exploreror/demos/model-arena), the link should be updated.
182-250: LGTM!The RAG grounding pattern is well-implemented, demonstrating proper vector search integration and hallucination detection. Good use of optional chaining on
r.metadata?.contentand clear logging of unsupported claims.
252-315: LGTM!The eval example clearly demonstrates background quality monitoring with proper handler signature and return structure. Good inclusion of the link to the main evaluations documentation.
317-362: LGTM!Clear guidance on structuring judge prompts with explicit criteria. The best practices and cost optimization tips are practical and actionable.
364-368: LGTM!Appropriate next steps linking to related documentation for evaluations, AI SDK integration, and vector storage.
content/Learn/Cookbook/overview.mdx (1)
37-37: LGTM!The new entry is correctly placed in alphabetical order and the link/description align with the new
llm-as-a-judge.mdxdocumentation file.content/Services/Storage/queue.mdx (1)
1-171: Documentation content is well-structured and examples are clear.The queue documentation provides comprehensive coverage of the feature with practical examples for different contexts (agents, routes, standalone). The code samples demonstrate proper async/await usage and good patterns like the webhook acknowledgment pattern.
content/Services/Storage/meta.json (1)
3-3: LGTM!The "queue" entry is correctly added to the pages array, positioned logically between "database" and "durable-streams".
content/Services/Storage/key-value.mdx (5)
47-67: LGTM!The TTL examples clearly demonstrate all three scenarios (custom TTL, default 7-day, and no expiration with
null), and the inline comments align with the TTL semantics table documented later.
72-90: LGTM!The addition of
expiresAtin the retrieval example is consistent with the TTL enhancements and provides useful context for developers.
167-188: LGTM!The namespace management examples clearly demonstrate the new
createNamespaceAPI withdefaultTTLSecondsoption, covering both expiring and non-expiring configurations.
190-204: LGTM!The TTL semantics table and callouts are clear and comprehensive. The sliding expiration feature is well-explained and will help developers understand the automatic TTL extension behavior.
210-256: LGTM!The TTL strategy section provides practical guidance with appropriate suggested TTLs for different use cases, and the SessionManager example demonstrates real-world TTL usage effectively.
content/Services/Storage/vector.mdx (5)
78-84: LGTM!The pre-computed embeddings example correctly demonstrates the
ttl: nulloption for vectors that should never expire.
92-114: LGTM!The search example clearly demonstrates how to access the
expiresAtfield in search results, consistent with the TTL documentation.
166-179: LGTM!The clarification about
exists()behavior (returningfalsefor empty namespaces) is valuable and prevents potential confusion when checking namespace state.
191-228: LGTM!The type safety example effectively demonstrates generics usage for both
upsertandsearchoperations, providing a clear pattern for type-safe metadata handling.
63-73: Clarify: Intentional difference in default TTL between storage types.Vector storage documents a 30-day default TTL (line 67), while Key-Value storage documents a 7-day default TTL (line 194). Durable-Streams also uses 30 days. Confirm whether this difference is intentional (different storage types have different retention semantics) or if defaults should be aligned across all storage services. If intentional, consider documenting why each storage type has different defaults.
content/Services/Storage/durable-streams.mdx (5)
6-21: LGTM!The updated wording correctly reflects that streams are accessible "until deleted" rather than "permanent," addressing the previous review feedback. The new "Why Durable Streams?" section provides valuable context about connection fragility and the benefits of decoupling data from connections.
84-94: LGTM!The TTL semantics documentation is consistent with vector storage (30-day default). The local development note about TTL enforcement is helpful for developers testing locally.
101-127: LGTM!The import additions make the code examples self-contained and copy-paste friendly.
168-204: LGTM!The listing and reading examples correctly demonstrate namespace-based filtering and the
expiresAtfield in stream metadata, consistent with the TTL enhancements across all storage types.
346-358: No action needed. The model identifiergroq('openai/gpt-oss-120b')is a valid Groq model listed in their official documentation. No change required.Likely an incorrect or invalid review comment.
content/Agents/creating-agents.mdx (2)
200-208: LGTM!The type inference guidance is helpful. The good/bad pattern clearly communicates the recommendation to let TypeScript infer types from schemas rather than adding explicit annotations that can cause conflicts.
375-377: LGTM!The AI-Assisted Development callout is well-placed in the Next Steps section and links correctly to the new OpenCode plugin documentation being added in this PR.
content/Reference/CLI/opencode-plugin.mdx (2)
188-213: LGTM!The Tmux Integration section is well-documented with clear configuration options and the important warning about server mode requirement.
51-54: Update model names to match current supported versions."Claude Opus 4.5" does not exist; the current latest Opus model is Claude Opus 4.1. "GPT 5.2 Codex" should use the official model name format "gpt-5.2-codex".
Likely an incorrect or invalid review comment.
content/Reference/CLI/meta.json (1)
12-13: LGTM!The navigation entry for
opencode-pluginis correctly placed afterai-commands, maintaining logical grouping of AI-related CLI documentation.content/Get-Started/quickstart.mdx (1)
215-221: LGTM!The AI-Assisted Development callout is well-integrated into the quickstart flow and provides an actionable next step for users who want AI assistance.
content/Reference/CLI/debugging.mdx (3)
39-39: LGTM!Using the explicit
--fileflag is clearer than a positional argument and aligns with CLI best practices for clarity.
205-230: LGTM!The Evaluation Commands section is well-structured and provides clear examples for listing and inspecting evaluations. The cross-reference to the Evaluations documentation is helpful.
310-337: LGTM!The Support Commands section is a valuable addition for troubleshooting. The privacy callout about automatic redaction is important and appropriately placed.
content/Reference/CLI/ai-commands.mdx (2)
92-107: LGTM!The update from CommonJS
requireto ES moduleimportsyntax is appropriate for modern TypeScript/Node.js documentation.
119-134: LGTM!The OpenCode Plugin section provides a good summary with essential commands and appropriately links to the full documentation for details.
content/Reference/CLI/development.mdx (2)
29-32: LGTM!The inspector flags (
--inspect,--inspect-wait,--inspect-brk) are clearly documented in the options table with appropriate descriptions.
130-168: LGTM!The reworked Public URLs section effectively explains the value proposition (why public URLs matter for webhook testing) before diving into technical details. The "Why Public URLs?" subsection addresses a real developer pain point clearly.
content/Reference/CLI/deployment.mdx (3)
8-19: Clear “Why Deploy” positioning and value props.
Strong, scannable intro and benefits list.
148-150: DNS Records callout is helpful and well-placed.
309-311: “Activate Custom Domains” callout reads well.content/Services/Storage/database.mdx (2)
22-35: Clear CLI onboarding for database creation.
Good, concise examples and a helpful note on naming/description benefits.
206-209: Confirm and align callback option naming across examples.The examples show inconsistent casing: lines 206-209 use lowercase
oncloseandonreconnected, while lines 260-268 use camelCaseonReconnected. The pattern elsewhere in the codebase (WebSocket and SSE handlers useonOpen,onMessage,onClose) suggests camelCase is the intended convention. Verify the correct option names in the@agentuity/postgresand@agentuity/drizzlesource code and update both examples to use consistent naming.
✏️ 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
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
content/Reference/CLI/development.mdx (1)
16-20:⚠️ Potential issue | 🟡 MinorAlign public URL wording with default-enabled behavior.
Line 19 calls public URL tunneling “optional,” but later the doc says it’s enabled by default. Consider clarifying the bullet so it reads as default-on with an opt-out to avoid mixed signals.
✅ Suggested wording tweak
- - Public URL tunneling (optional, for webhooks and sharing) + - Public URL tunneling (enabled by default; disable with `--no-public`)
🤖 Fix all issues with AI agents
In `@content/Reference/CLI/opencode-plugin.mdx`:
- Around line 151-161: The documentation shows conflicting defaults for
defaultConcurrency (example sets defaultConcurrency: 3 while the options table
lists defaultConcurrency as 1); update the content so they match by either
changing the YAML example's defaultConcurrency value to 1 to reflect the actual
default or add an inline note next to the example explaining that
defaultConcurrency: 3 is a recommended override (not the product default).
Ensure you update the `defaultConcurrency` reference in the YAML example and/or
add a clarifying sentence so the table and example are consistent.
🧹 Nitpick comments (2)
content/Reference/CLI/opencode-plugin.mdx (1)
106-129: Cadence commands duplicated across files.The exact same Cadence commands (list, status, pause, resume, stop) are documented here and in
ai-commands.mdx(lines 140-155). Consider whether one file should be the canonical reference and the other should simply link to it, to avoid maintenance burden when commands change.content/Reference/CLI/ai-commands.mdx (1)
136-158: Consider consolidating duplicated Cadence command documentation.This section duplicates the same Cadence commands from
opencode-plugin.mdx(lines 112-127). Since line 138 already links to the OpenCode Plugin page for Cadence details, consider removing the repeated command list here and just keeping the link reference to maintain a single source of truth.📝 Suggested simplification
## Cadence Commands -Manage long-running AI tasks with the cadence system. See [OpenCode Plugin](/Reference/CLI/opencode-plugin#cadence-system) for details on how Cadence integrates with the agent workflow. +Manage long-running AI tasks with the cadence system: -```bash -# List all cadence tasks -agentuity ai cadence list - -# Check task status -agentuity ai cadence status <task-id> - -# Pause a running task -agentuity ai cadence pause <task-id> - -# Resume a paused task -agentuity ai cadence resume <task-id> - -# Stop a task -agentuity ai cadence stop <task-id> -``` +- `agentuity ai cadence list` - List all tasks +- `agentuity ai cadence status <task-id>` - Check task status +- `agentuity ai cadence pause/resume/stop <task-id>` - Manage task lifecycle -Cadence tasks persist across sessions, allowing complex operations to continue in the background. +Tasks persist across sessions. See [OpenCode Plugin - Cadence System](/Reference/CLI/opencode-plugin#cadence-system) for full details.
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (6)
content/Reference/CLI/ai-commands.mdxcontent/Reference/CLI/deployment.mdxcontent/Reference/CLI/development.mdxcontent/Reference/CLI/opencode-plugin.mdxcontent/Services/Sandbox/index.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 (11)
content/Services/Sandbox/index.mdx (3)
8-22: Clear and compelling rationale section.Reads well and sets expectations succinctly.
93-106: Confirm runtime metadata field names and optionality match the API.Please verify that
description,icon,brandColor,documentationUrl,tags, andrequirementsare exactly the JSON keys returned byagentuity cloud sandbox runtime list --json, and clarify if any can benull/missing to avoid mismatches in docs.✏️ Suggested clarification
| `requirements` | Minimum memory, CPU, disk, and network needs | +Note: Field names are camelCase as returned by `runtime list --json`; some fields may be null depending on the runtime.
189-190: Clarify prerequisites/behavior fornetwork.port.If port exposure requires
network.enabled: true(or any other prerequisites), call that out explicitly so users don’t setnetwork.portand assume it works without enabling networking.✏️ Suggested clarification
| `network.port` | Port to expose to internet (1024-65535) | `3000` | +| | Requires `network.enabled: true`; ignored otherwise. | |content/Reference/CLI/opencode-plugin.mdx (5)
1-66: LGTM!The introduction, installation instructions, and specialized agents documentation are well-structured. The tables clearly describe each agent's role and provide helpful guidance on when to use Builder vs Architect. The security callout about blocked sensitive commands is a good addition.
67-105: LGTM!The slash commands table and MCP servers documentation are clear and informative. The headless mode section provides practical use cases and a clear example command.
162-187: LGTM!The tmux integration section is well-documented with clear requirements (server mode callout), configuration options, and behavioral descriptions.
188-249: LGTM!The configuration section provides comprehensive coverage of agent model overrides, MCP server configuration, and plugin behavior settings with clear JSON/YAML examples.
250-254: LGTM!Next steps provide relevant cross-references to related documentation.
content/Reference/CLI/ai-commands.mdx (2)
92-107: LGTM!The update from CommonJS (
require) to ES module syntax (import) is a good modernization of the TypeScript examples, aligning with current best practices.
119-135: LGTM!The new OpenCode Plugin section provides a concise overview with installation/uninstallation commands and appropriately links to the full documentation for details.
content/Services/queues.mdx (1)
166-186: The review comment suggests an invalid fix. The queues.mdx code at lines 166–186 usesctx.invoke(async () => { ... })to wrap queue operations and context-dependent logic, not to call an agent. The suggested change toctx.run()would break the code becausectx.run()expects an agent as its first argument (signature:ctx.run(agent, input)), not an arbitrary async callback.While the standalone-execution documentation notes that
ctx.invoke(() => agent.run(input))is a "legacy" pattern for agent execution, there is no documented replacement for usingctx.invoke()to wrap non-agent code that requires context access (like queue publishing and logging). The current example is correct and valid.Likely an incorrect or invalid review comment.
✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.
Summary by CodeRabbit
New Features
Documentation
✏️ Tip: You can customize this high-level summary in your review settings.