feat: Add ctx.agents.react for multi-step agent functionality (#854)

* feat: Add ctx.agents.react for multi-step agent functionality

* Update sdk-node/src/workflows/workflow.ts

Co-authored-by: John Smith <john@johnjcsmith.com>

* fix: Correct variable name from instruction to instructions across modules and update package dependency version

* chore: Update package-lock.json

* feat: Enhance AI message handling with previous attempt tracking and parameter refinement

---------

Co-authored-by: John Smith <john@johnjcsmith.com>

Author: nadeesha

app/client/contract.ts

@@ -1458,7 +1458,7 @@ export const definition = {
     }),
     body: z.object({
       input: z.string(),
-      instruction: z.string().optional(),
+      instructions: z.string().optional(),
       schema: z.record(z.any()),
     }),
     headers: z.object({

control-plane/package-lock.json

@@ -27,7 +27,7 @@
     "@e2b/code-interpreter": "^1.0.4",
     "@fastify/cors": "^8.5.0",
     "@hyperdx/node-opentelemetry": "^0.8.1",
-    "@l1m/core": "^0.1.3",
+    "@l1m/core": "^0.1.5",
     "@langchain/cohere": "^0.3.1",
     "@langchain/langgraph": "^0.1.9",
     "@nangohq/node": "^0.48.1",
@@ -97,4 +97,4 @@
     "ts-node": "^10.9.2",
     "tsx": "^4.7.0"
   }
-}
+}

control-plane/package.json

@@ -1458,7 +1458,7 @@ export const definition = {
     }),
     body: z.object({
       input: z.string(),
-      instruction: z.string().optional(),
+      instructions: z.string().optional(),
       schema: z.record(z.any()),
     }),
     headers: z.object({

control-plane/src/modules/contract.ts

@@ -1566,9 +1566,9 @@ export const router = initServer().router(contract, {
       status: 200,
       body: tools,
     };
- },
+  },
   l1mStructured: async request => {
-    const { input, instruction, schema } = request.body;
+    const { input, instructions, schema } = request.body;
     const { clusterId } = request.params;
 
     const auth = request.request.getAuth();
@@ -1579,7 +1579,7 @@ export const router = initServer().router(contract, {
     const providerUrl = request.headers["x-provider-url"];
 
     const executionId = request.headers["x-workflow-execution-id"];
-    const maxAttempts = request.headers["x-max-attempts"]
+    const maxAttempts = request.headers["x-max-attempts"];
 
     if (!executionId) {
       return {
@@ -1591,14 +1591,14 @@ export const router = initServer().router(contract, {
     }
 
     const hash = crypto.createHash("sha256");
-    hash.update(input)
-    hash.update(JSON.stringify(schema))
-    hash.update(providerModel)
-    hash.update(providerKey)
-    hash.update(executionId)
-    instruction && hash.update(instruction)
+    hash.update(input);
+    hash.update(JSON.stringify(schema));
+    hash.update(providerModel);
+    hash.update(providerKey);
+    hash.update(executionId);
+    instructions && hash.update(instructions);
 
-    const messageKey = `${executionId}_structured_${hash.digest("hex")}`
+    const messageKey = `${executionId}_structured_${hash.digest("hex")}`;
 
     const existingMessage = await kv.get(clusterId, messageKey);
     if (existingMessage) {
@@ -1636,7 +1636,7 @@ export const router = initServer().router(contract, {
       url: providerUrl,
       key: providerKey,
       model: providerModel,
-    }
+    };
 
     if (providerUrl.includes("inferable") || providerUrl === "") {
       if (!["claude-3-5-sonnet", "claude-3-haiku"].includes(providerModel)) {
@@ -1652,7 +1652,7 @@ export const router = initServer().router(contract, {
         identifier: providerModel as any,
         trackingOptions: {
           clusterId: clusterId,
-        }
+        },
       });
 
       provider = async (params, prompt, previousAttempts) => {
@@ -1664,7 +1664,7 @@ export const router = initServer().router(contract, {
           messages.push({
             role: "user",
             content: [
-              { type: "text", text: `${instruction} ${prompt}` },
+              { type: "text", text: `${instructions} ${prompt}` },
               {
                 type: "image",
                 source: {
@@ -1678,15 +1678,19 @@ export const router = initServer().router(contract, {
         } else {
           messages.push({
             role: "user",
-            content: `${input} ${instruction} ${prompt}`,
+            content: `${input} ${instructions} ${prompt}`,
           });
         }
 
         if (previousAttempts.length > 0) {
-          previousAttempts.forEach((attempt) => {
+          previousAttempts.forEach(attempt => {
             messages.push({
               role: "user",
-              content: "You previously responded: " + attempt.raw + " which produced validation errors: " + attempt.errors,
+              content:
+                "You previously responded: " +
+                attempt.raw +
+                " which produced validation errors: " +
+                attempt.errors,
             });
           });
         }
@@ -1700,17 +1704,17 @@ export const router = initServer().router(contract, {
         } else {
           throw new Error("Anthropic API returned invalid response");
         }
-      }
+      };
     }
 
     const result = await structured({
       input,
       type,
       schema,
       maxAttempts: maxAttempts ? parseInt(maxAttempts) : 3,
-      instruction,
+      instructions,
       provider,
-    })
+    });
 
     if (!result.valid || !result.structured) {
       return {

control-plane/src/modules/router.ts

@@ -4,7 +4,7 @@
   "description": "Javascript SDK for inferable.ai",
   "main": "bin/index.js",
   "scripts": {
-    "build": "tsc",
+    "build": "tsc -p tsconfig.build.json",
     "clean": "rm -rf ./bin",
     "prepare": "husky",
     "test": "jest ./src --runInBand --forceExit --setupFiles dotenv/config",
@@ -56,4 +56,4 @@
     "email": "hi@inferable.ai",
     "url": "https://github.com/inferablehq/inferable/issues"
   }
-}
+}

sdk-node/package.json

@@ -78,13 +78,20 @@ export type ToolSchema<T extends z.ZodTypeAny | JsonSchemaInput> = {
   input: T;
 };
 
-export type ToolRegistrationInput<
-  T extends z.ZodTypeAny | JsonSchemaInput,
-> = {
+export type ToolRegistrationInput<T extends z.ZodTypeAny | JsonSchemaInput> = {
   name: string;
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  func: (input: ToolInput<T>, context: JobContext) => any;
+  func: (input: ToolInput<T>, context: JobContext) => Promise<any>;
   schema?: ToolSchema<T>;
   config?: ToolConfig;
   description?: string;
 };
+
+export type WorkflowToolRegistrationInput<
+  T extends z.ZodTypeAny | JsonSchemaInput,
+> = {
+  name: string;
+  inputSchema?: T;
+  config?: ToolConfig;
+  func: (input: ToolInput<T>, context: JobContext) => Promise<unknown>;
+};

sdk-node/src/types.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { helpers } from "./workflow";
 import { inferableInstance } from "../tests/utils";
+import assert from "assert";
 
 describe("workflow", () => {
   jest.setTimeout(60_000);
@@ -12,18 +13,6 @@ describe("workflow", () => {
     const onSimpleResult = jest.fn();
     const toolCall = jest.fn();
 
-    inferable.tools.register({
-      func: (_i, _c) => {
-        toolCall();
-        return {
-          word: "needle",
-        };
-      },
-      name: "searchHaystack",
-    });
-
-    inferable.tools.listen();
-
     // Generate a unique workflow name to prevent conflicts with other tests
     const workflowName = `haystack-search-${Math.random().toString(36).substring(2, 15)}`;
 
@@ -35,59 +24,88 @@ describe("workflow", () => {
       }),
     });
 
+    workflow.tools.register({
+      name: "searchHaystack2",
+      inputSchema: z.object({
+        searchQuery: z.string(),
+      }),
+      func: async (input) => {
+        toolCall(input);
+        if (input.searchQuery === "marco") {
+          return { word: "not-needle" };
+        } else if (input.searchQuery === "marco 42") {
+          return { word: "needle" };
+        } else {
+          return { word: `not-found-${input.searchQuery}` };
+        }
+      },
+    });
+
     workflow.version(1).define(async (ctx, input) => {
       onStart(input);
       ctx.log("info", { message: "Starting workflow" });
-      const searchAgent = ctx.agent({
+      const { word } = await ctx.agents.react({
         name: "search",
-        tools: ["searchHaystack"],
-        systemPrompt: helpers.structuredPrompt({
+        instructions: helpers.structuredPrompt({
           facts: ["You are haystack searcher"],
-          goals: ["Find the special word in the haystack"],
+          goals: [
+            "Find the special word in the haystack. Only search for the words asked explictly by the user.",
+          ],
         }),
-        resultSchema: z.object({
+        schema: z.object({
           word: z.string(),
         }),
+        tools: ["searchHaystack2"],
+        input: `Try the searchQuery 'marco'.`,
+        onBeforeReturn: async (result, agent) => {
+          if (result.word !== "needle") {
+            await agent.sendMessage("Try the searchQuery 'marco 42'.");
+          }
+        },
       });
 
-      const result = await searchAgent.trigger({
-        data: {},
-      });
+      assert(word === "needle", `Expected word to be "needle", got ${word}`);
 
-      ctx.result("testResultCall", async () => {
+      const cachedResult = await ctx.result("testResultCall", async () => {
         return {
           word: "needle",
         };
       });
 
-      if (!result || !result.result || !result.result.word) {
-        throw new Error("No result");
-      }
+      assert(
+        cachedResult.word === "needle",
+        `Expected cachedResult to be "needle", got ${cachedResult.word}`,
+      );
 
-      onAgentResult(result.result.word);
+      onAgentResult(cachedResult.word);
 
       ctx.log("info", { message: "About to run simple LLM call" });
 
       await ctx.llm.structured({
         input: "Return the word, needle.",
         schema: z.object({
           word: z.string(),
-        })
+        }),
       });
 
       // Duplicate call
       const simpleResult = await ctx.llm.structured({
         input: "Return the word, needle.",
         schema: z.object({
           word: z.string(),
-        })
+        }),
       });
 
-      if (!simpleResult || !simpleResult.word) {
-        throw new Error("No simpleResult");
-      }
+      assert(
+        simpleResult.word === "needle",
+        `Expected simpleResult to be "needle", got ${simpleResult.word}`,
+      );
+
       onSimpleResult(simpleResult.word);
 
+      return {
+        word: "needle",
+      };
     });
 
     await workflow.listen();
@@ -114,7 +132,7 @@ describe("workflow", () => {
     expect(onAgentResult).toHaveBeenCalledWith("needle");
     expect(onAgentResult).toHaveBeenCalledTimes(1);
 
-    expect(toolCall).toHaveBeenCalledTimes(1);
+    expect(toolCall).toHaveBeenCalledTimes(2);
 
     expect(onSimpleResult).toHaveBeenCalledWith("needle");
     expect(onSimpleResult).toHaveBeenCalledTimes(1);