@convex-dev/agent 0.0.11-alpha.2 → 0.0.12

package/README.md

@@ -52,21 +52,22 @@ export const continueThread = action({
 });
 
 // Or use it within a workflow, specific to a user:
-export const supportAgentStep = supportAgent.asAction({ maxSteps: 10 });
+export const { generateText: getSupport } = supportAgent.asActions({ maxSteps: 10 });
 
 const workflow = new WorkflowManager(components.workflow);
-const s = internal.example; // where steps are defined
 
 export const supportAgentWorkflow = workflow.define({
   args: { prompt: v.string(), userId: v.string(), threadId: v.string() },
   handler: async (step, { prompt, userId, threadId }) => {
-    const suggestion = await step.runAction(s.supportAgentStep, {
-      threadId, generateText: { prompt },
+    const suggestion = await step.runAction(internal.example.getSupport, {
+      threadId, userId, prompt,
     });
-    const polished = await step.runAction(s.adaptSuggestionForUser, {
-      suggestion, userId,
+    const polished = await step.runAction(internal.example.adaptSuggestionForUser, {
+      userId, suggestion,
+    });
+    await step.runMutation(internal.example.sendUserMessage, {
+      userId, message: polished.message,
     });
-    await step.runMutation(s.sendUserMessage, { userId, message: polished.message });
   },
 });
 ```
@@ -216,45 +217,53 @@ export const continueThread = action({
 
 ### Exposing the agent as a Convex action
 
+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.
+
 ```ts
-export const supportAgentStep = supportAgent.asAction({ maxSteps: 10 });
+export const getSupport = supportAgent.asTextAction({
+  maxSteps: 10,
+});
+```
 
-// Then from within another action:
-export const callSupportAgent = action({
-  args: { prompt: v.string(), userId: v.string(), threadId: v.string() },
-  handler: async (ctx, { prompt, userId, threadId }) => {
-    const suggestion = await ctx.runAction(s.supportAgentStep, {
-      threadId, userId, generateText: { prompt },
-    });
-  },
+You can also expose an action that generates an object.
+
+```ts
+export const getStructuredSupport = supportAgent.asObjectAction({
+  schema: z.object({
+    analysis: z.string().describe("A detailed analysis of the user's request."),
+    suggestion: z.string().describe("A suggested action to take.")}),
 });
 ```
 
-### Using the agent within a workflow
+### Using the agent actions within a workflow
 
 You can use the [Workflow component](https://convex.dev/components/workflow)
-to run, with retries and guarantees of eventually completing, surviving server restarts,
-and more. Read more about durable workflows
+to run agent flows. 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).
 
 ```ts
 const workflow = new WorkflowManager(components.workflow);
-const s = internal.example; // where steps are defined
 
 export const supportAgentWorkflow = workflow.define({
   args: { prompt: v.string(), userId: v.string(), threadId: v.string() },
   handler: async (step, { prompt, userId, threadId }) => {
-    const suggestion = await step.runAction(s.supportAgentStep, {
-      threadId, userId, generateText: { prompt },
+    const suggestion = await step.runAction(internal.example.getSupport, {
+      threadId, userId, prompt,
+    });
+    const polished = await step.runAction(internal.example.adaptSuggestionForUser, {
+      userId, suggestion,
     });
-    const polished = await step.runAction(s.adaptSuggestionForUser, {
-      threadId, userId, generateText: { prompt: suggestion },
+    await step.runMutation(internal.example.sendUserMessage, {
+      userId, message: polished.message,
     });
-    await step.runMutation(s.sendUserMessage, { userId, message: polished.message });
   },
 });
 ```
 
+See another example in [example.ts](./example/convex/example.ts#L120).
+
 ### Fetching thread history
 
 ```ts