Repository navigation
Conversation
🦋 Changeset detectedLatest commit: 8e077ef The changes in this PR will be included in the next version bump. This PR includes changesets to release 4 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
8e077ef to
08227de
Compare
| `refresh` must return the raw channel descriptor, not a hydrated channel: | ||
|
|
||
| - A backend method returns `channel.toJSON()` without its `__blocks` field. That method issues tokens, so give it the same authorization as the method that returns the channel. | ||
| - The callback adds the field back: `async (channelId) => ({ ...(await api.agentGetRawDescriptor(channelId)), __blocks: 'realtime/channel' })`, where `agentGetRawDescriptor` is that backend method. |
There was a problem hiding this comment.
The refresh example calls api.agentGetRawDescriptor, a backend method the README never defines.
Either add an agentGetRawDescriptor method to the backend ApiNamespace example (returning channel.toJSON() minus __blocks, with the same auth as agentGetChannel), or point the reference at a method the example does define. At minimum, we can say explicitly that the reader must add this backend method.
|
|
||
| const agent = new Agent(scope, 'chat', { | ||
| systemPrompt: 'You are a helpful assistant.', | ||
| }); |
There was a problem hiding this comment.
The backend and createChat wiring examples are not compile-checked, so a type error would ship silently.
Consider bringing the backend + createChat wiring under the doc-snippets/readme compile harness, as the useChat samples were, even as a type-only fixture, so these examples cannot drift out of compilation.
The seven Model Configuration subsections move verbatim into MODELS.md, which package.json already lists in files. The README keeps the model option table, the deployed/local/fallback examples and the facts needed before deploying. Also: recommend createChat, not the deprecated useChat, for subscribe-before-send ordering; list the two missing cases that throw InvalidModelConfig; and make the useChat samples compile under tsc --strict.
…correct the error cases
The createChat example called six api.agent* methods that no backend in the README defined, and its subscribe callback passed a handler-or-options argument straight to channel.subscribe(handler); the backend ApiNamespace is now shown with the same method names and the callback narrows with typeof.
The Errors table gains an error.name column and case lists: InvalidModelConfig says which cases the constructor and stream()/resume() throw, which fail the turn with StreamFailed, and that a bedrock model without modelId or an unknown provider fails the health check and ends in ModelUnavailable; PersistenceRequired, InterruptRequired and InvalidUsage list their missing cases.
The createChat intro no longer says the runtime is Lambda + Realtime, the model option is typed { deployed?, local? }, the fallback example sets apiKey on its openai-api candidate, and reconnect recovery states the 11-minute timeout.
Options (with a Default column) and Errors follow the method table; createChat has an options table and a controller-method table; ConversationManagerConfig and InterruptResponse have field tables.
The useChat section is a comparison table with createChat; the useChat samples and the Full Examples section are removed.
Three searchDocs definitions remain of five, each with untrustedOutput: true and a filter from the tool context.
The section AWS Credentials (Bedrock) is renamed Bedrock model access and leads with a table: the error message, its cause and the fix (use case details form, AWS Marketplace subscription, account availability, global versus regional inference profile). The example that only set deployed: BedrockModels.BALANCED is one sentence, and the preset notes state that BALANCED is the default when model.deployed is omitted. The Ollama preset example, the custom-endpoint snippet with its apiKey and the logger example keep their imports.
…waitUntilSynced tables chunkOverlap was documented as 0-100 in the options table and 1-99 under Local development; it is 1-99 on AWS and the mock also accepts 0, stated once. maxResults said Range: 1-100; a value outside the range is clamped and a non-integer throws ValidationError. waitUntilSynced() has an options table and a table of which poll failures are retried and which are thrown at once, replacing three paragraphs. Errors follows API, the asAgentTool() filter rules and tool properties are two lists, supported formats and the maximum document size are under Source Configuration, and Deploy Behavior is merged into Sync.
…t` samples and compile both The `refresh` rule under the `createChat` options table called `api.agentGetRawDescriptor`, a backend method no sample defined. The backend sample now defines it, with the same `auth.requireAuth(context)` as `agentGetChannel`, and the frontend sample passes it to `refresh`. Both samples name their file on the first line (`aws-blocks/index.ts`, `src/chat.ts`) and the frontend sample declares the three UI functions it calls, so the shipped-docs code-sample check (`packages/blocks` `doc-snippets`) typechecks them together as one app instead of checking only their imports. The changeset gains one line for the two changes.
08227de to
667df38
Compare
Problem
## APIand the errors 408.createChatexample called sixapi.agent*methods that no backend in the README defined, and itssubscribecallback passed a value that is a handler or an options object straight tochannel.subscribe(handler).InvalidModelConfigrow listed "Missing modelId, apiKey, unknown provider" with no condition; two of those never surface asInvalidModelConfig, and four other cases were missing.searchDocsexamples returned retrieved content withoutuntrustedOutput: trueand without a filter from the tool context.chunkOverlapas "0–100" in one place and "1–99" in another.Issue #, if available:
Changes
This builds on commit
91c0004a1, which moves the seven Model Configuration subsections verbatim intopackages/bb-agent/MODELS.md(already listed infilesofpackage.json), namescreateChatfor subscribe-before-send ordering, and addstrustablewithinterruptandguardrailon a non-bedrockprovider to theInvalidModelConfigrow. It also made theuseChatsamples compile understrict; they are removed here.packages/bb-agent/README.mdBelow,
src/ispackages/bb-agent/src/. Corrections:ApiNamespaceis shown with the method names the client calls (agentCreateConversationId,agentGetChannel,agentStream,agentResume,agentGetConversation,agentGetPendingInterrupts). Shapes:src/index.chat.ts:58-79,src/transport.ts:181-198. Thesubscribecallback narrows withtypeof(src/transport.ts:164-167,packages/bb-realtime/src/types.ts:79-80).agentGetRawDescriptor, the method therefreshrule names, with the sameauth.requireAuth(context)asagentGetChannel; the frontend sample passes it torefresh, astest-apps/comprehensive/src/index.ts:356does. Shapes:src/index.chat.ts:113,packages/bb-realtime/src/types.ts:82,:89-93.aws-blocks/index.ts,src/chat.ts), and the frontend sample declares the three UI functions it calls.packages/blocksdoc-snippetstherefore typechecks them together as one app (packages/blocks/src/test-support/doc-snippets.ts:19-23) instead of checking only their imports.InvalidModelConfigis a case list: thrown by the constructor, thrown bystream()/resume(), or failing the turn, wherecomplete()rejects withStreamFailed(src/agent.ts:77-82,:244-258,:639,:1035,src/model-factory.ts:219-303,src/providers/canned.ts:77-89). Abedrockmodel withoutmodelIdand an unknownproviderfail the health check and end inModelUnavailable(src/agent.ts:693-702,src/model-factory.ts:51-83,:184,src/agent.mock.ts:11-13).PersistenceRequiredalso coversstream()/resume()withoutoptions.userId(src/agent.ts:795,:877);InterruptRequiredalso coversresume()with emptyresponsesor noconversationId(:854,:875);InvalidUsagealso covers an invalid channel name andchat.subscribe()withoutchannelId(:922-937,src/index.chat.ts:763-770).createChatintro no longer says "Lambda + Realtime today, others later" (src/agent.aws.ts:126,src/index.cdk.ts:67);modelis{ deployed?, local? }(src/types.ts:129-134); the fallback example setsapiKey: 'ollama'(src/model-factory.ts:174-176,:281-284); reconnect recovery states the 11-minute timeout (src/index.chat.ts:191); the message-roles note namescreateChat(src/index.hooks.ts:237).Tables added:
### Optionswith a Default column andremovalPolicy/loggerrows (src/types.ts:95-227);error.namecolumn (src/errors.ts:23-34);createChatoptions and controller methods (src/index.chat.ts:82-167);ConversationManagerConfig(src/types.ts:235-237);InterruptResponse(src/types.ts:258-271).Moved inside the file:
### Optionsand## Errorsfollow the method table;Authorization,Model ConfigurationandLimiting runaway costare##sections; a new## Conversation historyholds the history subsections.Removed: the
useChatcall sample, "Full Examples" and the "Key points" lists (theuseChatsection is a comparison table withcreateChat); twosearchDocsdefinitions (the complete example is "Use as an Agent tool" in the KnowledgeBase README); "Declaring tools", "Streaming Mode", "Reading conversation history", "Use Local LLM", "Best Practices" and the headless example without approval, whose facts are in the tables and neighbouring sentences.packages/bb-agent/MODELS.md## AWS Credentials (Bedrock)is## Bedrock model accessand leads with a table of error message, cause and fix; the wordings matchpackages/bb-agent/src/errors.ts:166-196. README links point to the new anchor.packages/bb-knowledge-base/README.mdBelow,
src/ispackages/bb-knowledge-base/src/.chunkOverlap: 1–99 on AWS, the mock also accepts 0 (src/types.ts:54-60,src/index.mock.ts:80-84,src/index.cdk.ts:59).maxResults: a value outside 1–100 is clamped; a non-integer throwsValidationError(src/normalize.ts:28-37).waitUntilSynced()has an options table and a retry table (src/types.ts:242-292,src/index.aws.ts:212-222,:565-636), replacing three paragraphs.## Error Handlingis## Errors, after## API. Formats and maximum document size moved to "Source Configuration"; "Deploy Behavior" is merged into "Sync".packages/bb-agent/README.mdpackages/bb-agent/MODELS.md(new)packages/bb-knowledge-base/README.mdLook hardest at:
ApiNamespaceand thecreateChatexample: same method names,refreshincluded, and typechecked together bydoc-snippets.InvalidModelConfigcases, in particular the two that end inModelUnavailablebecause the health check fails first (for an undefinedmodelIdonbedrock, read from the source, not run).useChatsection: the hook is deprecated but still exported, and its samples are gone.searchDocsexamples were removed (each remaining one setsuntrustedOutput: trueand a filter), and the newcreateChatoptions and controller-method tables.Not changed on purpose:
@aws-blocks/coreand@aws-blocks/bb-*, not from@aws-blocks/blocks.src/transport.ts:9-10,:145-148still says "Lambda + Realtime";src/types.ts:206-207still says an omittedremovalPolicyleaves the CDK default, whileFileBucketfalls back to the stack defaults (packages/bb-file-bucket/src/index.cdk.ts:92-97), which the README states.Open questions:
@aws-blocks/blocks?InvalidModelConfigraised inside a turn reaches the caller asStreamFailedwith the original message. Is that the intended contract?Changed after review:
agentGetRawDescriptoris defined in the backend sample and used byrefreshin the frontend sample; therefreshrules name only methods the samples define.createChatsamples are under the shipped-docs compile check. No test file was added: the existing check takes a sample whose first line names its file. Proof that it compiles them: withagentGetRawDescriptormisspelled in the frontend sample,doc-snippetsfails with "Property 'agentGetRawDescriptorX' does not exist on type 'AsyncAPI<…>'" atpackages/bb-agent/README.md:729. I found no compile check of theuseChatREADME samples to copy;packages/bb-agent/src/index.test.tstests the hook at runtime.Related pull requests: This supersedes the
bb-agentpart of #1496 (theMODELS.mdmove and three README fixes, taken over unchanged as commit91c0004a1). Open pull requests on the same files; whichever merges second rebases:packages/bb-agent/README.mdpackages/bb-agent/README.mdpackages/bb-agent/README.md; adds a "Prompt Caching" subsection inside Model Configuration and links#bedrock-presets, which now lives inMODELS.mdpackages/bb-knowledge-base/README.mdPart of a set of README revisions: #1635 (core), #1636 (hosting and pipeline), #1638 (bb-auth and auth-common), #1639 (the storage blocks), #1640 (compute, jobs, realtime, email and observability), #1641 (the guide, the scaffolder and its templates), #1642 (the native SDKs), #1643 (contributor docs). Each merges on its own.
Validation
Run on this branch alone at
667df3803, onmain8940cfd2f, with Node 22. All pass:npm run buildpackages/blocks(readme-links,docs-pointers,doc-snippets,imports-reference)packages/blockssandbox-dir-coverage(no tracked file names the old directory.blocks-sandbox)packages/corereadme-policies(the IAM policy JSON)packages/bb-authreadme-recipes,first-admin,multi-block-snippets,users-cli,gate-diagnosticspackages/auth-commonui.react-typespackages/bb-kv-storereadme.generated(every README snippet compiled) andlegacy/runtimepackages/create-blocks-appnpm testnpm run sync-docs:checknpm run check:importschangeset-guard.ts validate-structurechangeset-guard.ts verify-coveragechangeset-guard.ts verify-umbrellachangeset-guard.ts block-major#anchorin the changed files, and every link into them from another Markdown file, resolves (checked with a script)Run once on all the README branches of this set combined, as they were on an earlier
maincommit (e1e484465), and not run again after the rebases:packages/coreunit suite,packages/blocksunit suite,packages/bb-kv-storeunit suite,packages/bb-authunit suite,packages/auth-commonunit suite,npm run lint,npm run lint:depsandnpm run check:api. All passed.Not run locally: the full
npm testacross all workspaces,npm run test:e2e:localand the sandbox e2e suites. CI runs them.No test was added: the tests listed above already read these READMEs, and the remaining statements are checked against the source by review.
Checklist
By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.