@convex-dev/agent 0.0.17-alpha.0 → 0.1.0-alpha.0

package/README.md

@@ -7,6 +7,7 @@
 AI Agent framework built on Convex.
 
 - Automatic storage of chat history, per-user or per-thread, that can span multiple agents.
+- Playground UI for testing, debugging, and development. See [playground/README.md](playground/README.md) for more.
 - RAG for chat context, via hybrid text & vector search, with configuration options.
   Use the API to query the history yourself and do it your way.
 - Opt-in search for messages from other threads (for the same specified user).
@@ -385,17 +386,40 @@ await ctx.runMutation(components.agent.threads.updateThread, {
 });
 ```
 
+## Using the Playground UI
+
+The Playground UI is a simple way to test, debug, and develop with the agent.
+- First configure it with instructions [here](./playground/README.md).
+- Then you can use the [hosted version on GitHub pages](https://get-convex.github.io/agent/)
+or run it locally with `npx @convex-dev/agent-playground`.
+
+[Playground UI Screenshot](./playground/screenshot.png)
+
 ## Using the Workflow component for long-lived durable workflows
 
 The [Workflow component](https://convex.dev/components/workflow) is a great way to build long-lived, durable workflows.
 It handles retries and guarantees of eventually completing, surviving server restarts, and more.
 Read more about durable workflows in [this Stack post](https://stack.convex.dev/durable-workflows-and-strong-guarantees).
 
+To use the agent alongside workflows, you can run indivdual idempotent steps
+that the workflow can run, each with configurable retries, with guarantees that
+the workflow will eventually complete. Even if the server crashes mid-workflow,
+the workflow will pick up from where it left off and run the next step. If a
+step fails and isn't caught by the workflow, the workflow's onComplete handler
+will get the error result.
 
 ### Exposing the agent as Convex actions
 
-You can expose the agent as a Convex internal action.
-This is generally used from a workflow, where each step is a new thread message.
+You can expose the agent's capabilities as Convex functions to be used as steps
+in a workflow.
+
+To create a thread as a standalone mutation, similar to `agent.createThread`:
+
+```ts
+export const createThread = supportAgent.createThreadMutation();
+```
+
+For an action that generates text in a thread, similar to `thread.generateText`:
 
 ```ts
 export const getSupport = supportAgent.asTextAction({
@@ -414,12 +438,16 @@ export const getStructuredSupport = supportAgent.asObjectAction({
 });
 ```
 
-Create a thread from within a workflow, similar to agent.createThread.
+To save messages explicitly as a mutation, similar to `agent.saveMessages`:
 
 ```ts
-export const createThread = supportAgent.createThreadMutation();
+export const saveMessages = supportAgent.asSaveMessagesMutation();
 ```
 
+This is useful for idempotency, as you can first create the user's message,
+then generate a response in an unreliable action with retries, passing in the
+existing messageId instead of a prompt.
+
 ### Using the agent actions within a workflow
 
 You can use the [Workflow component](https://convex.dev/components/workflow)
@@ -439,11 +467,11 @@ export const supportAgentWorkflow = workflow.define({
     const suggestion = await step.runAction(internal.example.getSupport, {
       threadId, userId, prompt,
     });
-    const polished = await step.runAction(internal.example.adaptSuggestionForUser, {
-      userId, suggestion,
+    const { object } = await step.runAction(internal.example.getStructuredSupport, {
+      userId, message: suggestion,
     });
     await step.runMutation(internal.example.sendUserMessage, {
-      userId, message: polished.message,
+      userId, message: object.suggestion,
     });
   },
 });