feat(agent): IMicroAgenticaConfig.throw (#517)

Author: samchon

packages/core/src/MicroAgentica.ts

@@ -19,6 +19,7 @@ import { createUserMessageEvent } from "./factory/events";
 import { call, describe } from "./orchestrate";
 import { transformHistory } from "./transformers/transformHistory";
 import { __map_take } from "./utils/__map_take";
+import { assertExecuteFailure } from "./utils/assertExecuteFailure";
 import { getChatCompletionWithStreamingFunction } from "./utils/request";
 
 /**
@@ -166,10 +167,18 @@ export class MicroAgentica {
       ctx,
       this.operations_.array,
     );
-    if (executes.length
-      && this.props.config?.executor?.describe !== null
-      && this.props.config?.executor?.describe !== false) {
-      await describe(ctx, executes);
+    if (this.props.config?.throw === true) {
+      for (const execute of executes) {
+        assertExecuteFailure(execute);
+      }
+    }
+
+    // eslint-disable-next-line
+    if (executes.length && !!this.props.config?.executor?.describe) {
+      const func = typeof this.props.config.executor.describe === "function"
+        ? this.props.config.executor.describe
+        : describe;
+      await func(ctx, executes);
     }
 
     const completed: MicroAgenticaHistory[] = await Promise.all(

packages/core/src/structures/IMicroAgenticaConfig.ts

@@ -78,6 +78,19 @@ export interface IMicroAgenticaConfig {
    */
   retry?: number;
 
+  /**
+   * Whether to throw an exception when execution fails.
+   *
+   * If you set this property to `true`, the A.I. chatbot will throw
+   * an exception when {@link AgenticaExecuteHistory.success} is `false`.
+   *
+   * Otherwise, the execution failure will be handled silently without
+   * throwing an exception.
+   *
+   * @default false
+   */
+  throw?: boolean;
+
   /**
    * Backoff strategy.
    *

packages/core/src/structures/IMicroAgenticaExecutor.ts

@@ -55,6 +55,7 @@ export interface IMicroAgenticaExecutor {
    * @param ctx Context of the agent
    * @param executes List of function calling results
    * @returns List of prompts generated by the describer
+   * @default false
    */
   describe:
     | boolean

packages/core/src/utils/assertExecuteFailure.ts

@@ -0,0 +1,16 @@
+import type { AgenticaExecuteHistory } from "../histories/AgenticaExecuteHistory";
+
+export function assertExecuteFailure(failure: AgenticaExecuteHistory): void {
+  if (failure.success === true) {
+    return;
+  }
+  else if (failure.value instanceof Error) {
+    throw failure.value;
+  }
+  else if (typeof failure.value === "object" && failure.value !== null) {
+    const error: Error = new Error("Error from execute failure");
+    Object.assign(error, failure.value);
+    throw error;
+  }
+  throw failure.value;
+}

website/content/docs/core/micro.mdx

@@ -376,4 +376,49 @@ When you call `MicroAgentica.conversate()` function, the agent will start the [#
 
 If you want to archive the conversation state of current agent, store the returned prompts to your database with serialization to `IMicroAgenticaHistoryJson` format by calling `MicroAgenticaHistory.toJSON()` function. And then restore the conversation state by assigning the prompt histories to the `IMicroAgenticaProps.histories` property creating a new `Agentica` instance.
 
-By the way, waiting for the completion of internal agents' orchestration and giving prompt results to the user at once is not a good choice in the UX (User Experience) perspective. In that case, it would better to deliver the events to the user step by step with streaming. Enroll event listeners by calling `MicroAgentica.on()` function, and deliver it to the user.
+By the way, waiting for the completion of internal agents' orchestration and giving prompt results to the user at once is not a good choice in the UX (User Experience) perspective. In that case, it would better to deliver the events to the user step by step with streaming. Enroll event listeners by calling `MicroAgentica.on()` function, and deliver it to the user.
+
+
+
+
+## Error Handling
+<Tabs items={[
+  <code>src/main.ts</code>,
+  <code>IMicroAgenticaConfig</code>,
+]}>
+  <Tabs.Tab>
+```typescript filename="src/main.ts" showLineNumbers {12}
+import { MicroAgentica } from "@agentica/core";
+import OpenAI from "openai";
+
+const agent = new MicroAgentica({
+  vendor: {
+    api: new OpenAI({ apiKey: "********" }),
+    model: "gpt-4o-mini",
+  },
+  controllers: [...],
+  config: {
+    throw: true,
+  },
+});
+
+try {
+  await agent.conversate("I wanna buy MacBook Pro");
+} catch (error) {
+  console.error("Function execution failed:", error);
+}
+```
+  </Tabs.Tab>
+  <Tabs.Tab>
+    <RemoteSource
+      url="https://raw.githubusercontent.com/wrtnlabs/agentica/refs/heads/main/packages/core/src/structures/IMicroAgenticaConfig.ts"
+      filename="@agentica/core/IMicroAgenticaConfig"
+      showLineNumbers />
+  </Tabs.Tab>
+</Tabs>
+
+You can configure the `throw` property to control error handling behavior.
+
+When you set `IMicroAgenticaConfig.throw` to `true`, the agent will throw an exception when function execution fails (`AgenticaExecuteHistory.success === false`). This is useful when you want to handle execution failures explicitly in your application logic.
+
+By default, execution failures are handled silently without throwing exceptions. Set this property to `true` if you need to catch and handle execution errors in a try-catch block.