@hexabot-ai/agentic 3.0.1-alpha.0

package/examples/defs-bindings-agent/actions/ai-agent.ts

@@ -0,0 +1,110 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { createOpenAI } from '@ai-sdk/openai';
+import { stepCountIs, tool, ToolLoopAgent, type ToolSet } from 'ai';
+import { z } from 'zod';
+
+import { defineAction } from '../../../src';
+import type { AgentBindings } from '../bindings';
+import type { AgentExampleContext } from '../context';
+
+import { caculateScore } from './caculate-score';
+
+const actionRegistry = {
+  caculate_score: caculateScore,
+} as const;
+const inputSchema = z.strictObject({
+  prompt: z.string(),
+  system: z.string().optional(),
+});
+const outputSchema = z.strictObject({
+  steps: z.array(z.unknown()).optional(),
+  text: z.string(),
+  tool_calls: z.array(z.unknown()).optional(),
+  tool_results: z.array(z.unknown()).optional(),
+});
+const settingSchema = z.strictObject({
+  api_key: z.string().optional(),
+  max_steps: z.int().positive().default(2),
+  model: z.string().default('gpt-4o'),
+  provider: z.literal('openai').default('openai'),
+});
+
+type AiAgentInput = z.infer<typeof inputSchema>;
+type AiAgentOutput = z.infer<typeof outputSchema>;
+type AiAgentSettings = z.infer<typeof settingSchema>;
+
+const resolveTools = (
+  bindings: AgentBindings,
+  context: AgentExampleContext,
+): ToolSet => {
+  const mountedTools = bindings.tools ?? {};
+  const tools: ToolSet = {};
+
+  for (const [toolName, toolDefinition] of Object.entries(mountedTools)) {
+    const actionName = toolDefinition.action as keyof typeof actionRegistry;
+    const action = actionRegistry[actionName];
+
+    if (!action) {
+      throw new Error(
+        `Unsupported tool action "${String(toolDefinition.action)}" mounted in bindings.tools.${toolName}`,
+      );
+    }
+
+    tools[toolName] = tool({
+      description: `Workflow tool "${toolName}" delegates to action "${action.name}".`,
+      inputSchema: action.inputSchema,
+      execute: async (payload) =>
+        action.run(payload, context, toolDefinition.settings as any),
+    });
+  }
+
+  return tools;
+};
+
+export const aiAgent = defineAction<
+  AiAgentInput,
+  AiAgentOutput,
+  AgentExampleContext,
+  AiAgentSettings,
+  AgentBindings
+>({
+  name: 'ai_agent',
+  description:
+    'Runs a Vercel AI SDK ToolLoopAgent and resolves workflow-mounted tools through action bindings.',
+  supportedBindings: ['tools'],
+  inputSchema,
+  outputSchema,
+  settingSchema,
+  execute: async ({ input, settings, context, bindings }) => {
+    const apiKey = settings.api_key ?? process.env.OPENAI_API_KEY;
+
+    if (!apiKey) {
+      throw new Error(
+        'Missing OpenAI API key. Set settings.api_key or OPENAI_API_KEY.',
+      );
+    }
+
+    const provider = createOpenAI({ apiKey });
+    const model = provider(settings.model);
+    const tools = resolveTools(bindings, context);
+    const agent = new ToolLoopAgent({
+      ...(input.system ? { instructions: input.system } : {}),
+      model,
+      stopWhen: stepCountIs(settings.max_steps),
+      tools,
+    });
+    const result = await agent.generate({ prompt: input.prompt });
+
+    return {
+      steps: result.steps,
+      text: result.text,
+      tool_calls: result.toolCalls,
+      tool_results: result.toolResults,
+    };
+  },
+});

package/examples/defs-bindings-agent/actions/caculate-score.ts

@@ -0,0 +1,49 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { z } from 'zod';
+
+import { defineAction } from '../../../src';
+import type { AgentExampleContext } from '../context';
+
+const inputSchema = z.strictObject({
+  x: z.number(),
+});
+const outputSchema = z.strictObject({
+  formula: z.string(),
+  result: z.number(),
+});
+const settingSchema = z.strictObject({
+  bias: z.number().default(0),
+  multiplier: z.number().default(1),
+});
+
+type CaculateScoreInput = z.infer<typeof inputSchema>;
+type CaculateScoreOutput = z.infer<typeof outputSchema>;
+type CaculateScoreSettings = z.infer<typeof settingSchema>;
+
+export const caculateScore = defineAction<
+  CaculateScoreInput,
+  CaculateScoreOutput,
+  AgentExampleContext,
+  CaculateScoreSettings
+>({
+  name: 'caculate_score',
+  description: 'Calculates a score with score = multiplier * x + bias.',
+  inputSchema,
+  outputSchema,
+  settingSchema,
+  execute: async ({ input, settings }) => {
+    const result = settings.multiplier * input.x + settings.bias;
+
+    console.log(`[workflow] Calculating score for x=${input.x}`);
+
+    return {
+      formula: `${settings.multiplier} * ${input.x} + ${settings.bias}`,
+      result,
+    };
+  },
+});

package/examples/defs-bindings-agent/actions/index.ts

@@ -0,0 +1,15 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import type { Action } from '../../../src';
+
+import { aiAgent } from './ai-agent';
+import { caculateScore } from './caculate-score';
+
+export const defsBindingsActions: Record<string, Action> = {
+  ai_agent: aiAgent,
+  caculate_score: caculateScore,
+};

package/examples/defs-bindings-agent/bindings.ts

@@ -0,0 +1,20 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { z } from 'zod';
+
+import type { InferWorkflowBindings } from '../../src';
+
+export const bindingKinds = {
+  tools: {
+    schema: z.record(z.string(), z.unknown()),
+    multiple: true,
+    actionPolicy: 'required' as const,
+    supportedBindings: ['tools'],
+  },
+};
+
+export type AgentBindings = InferWorkflowBindings<typeof bindingKinds>;

package/examples/defs-bindings-agent/context.ts

@@ -0,0 +1,32 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import {
+  BaseWorkflowContext,
+  WorkflowEventEmitter,
+  type WorkflowEventEmitterLike,
+} from '../../src';
+
+export type AgentExampleContextState = {
+  request_id: string;
+};
+
+export class AgentExampleContext extends BaseWorkflowContext<AgentExampleContextState> {
+  public eventEmitter: WorkflowEventEmitterLike<WorkflowEventEmitter>;
+
+  constructor(
+    state: AgentExampleContextState,
+    eventEmitter: WorkflowEventEmitterLike<WorkflowEventEmitter> = new WorkflowEventEmitter(),
+  ) {
+    super(state);
+    this.eventEmitter = eventEmitter;
+  }
+
+  log(message: string, payload?: unknown): void {
+    const suffix = payload === undefined ? '' : ` ${JSON.stringify(payload)}`;
+    console.log(`[workflow] ${message}${suffix}`);
+  }
+}

package/examples/defs-bindings-agent/workflow.ts

@@ -0,0 +1,67 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+import { Workflow, WorkflowEventEmitter } from '../../src';
+
+import { defsBindingsActions } from './actions';
+import { bindingKinds } from './bindings';
+import { AgentExampleContext } from './context';
+
+const workflowPath = path.join(__dirname, 'workflow.yml');
+
+async function main() {
+  const yamlSource = fs.readFileSync(workflowPath, 'utf8');
+  const workflow = Workflow.fromYaml(yamlSource, {
+    actions: defsBindingsActions,
+    bindingKinds,
+  });
+  const emitter = new WorkflowEventEmitter();
+  const context = new AgentExampleContext(
+    {
+      request_id: 'request-1',
+    },
+    emitter,
+  );
+
+  emitter.on('hook:step:start', ({ step }) =>
+    context.log(`hook:step:start:${step.name}`),
+  );
+  emitter.on('hook:step:success', ({ step }) =>
+    context.log(`hook:step:success:${step.name}`),
+  );
+  emitter.on('hook:workflow:finish', ({ output }) =>
+    context.log('hook:workflow:finish', output),
+  );
+
+  const runner = await workflow.buildAsyncRunner();
+  const result = await runner.start({
+    inputData: {},
+    context,
+  });
+
+  if (result.status === 'finished') {
+    console.log('Final workflow outputs:', result.output);
+
+    return;
+  }
+
+  if (result.status === 'suspended') {
+    console.log(
+      `Workflow suspended at step ${result.step.id} for reason "${result.reason}"`,
+      result.data,
+    );
+
+    return;
+  }
+
+  console.error('Workflow failed:', result.error);
+}
+
+// OPENAI_API_KEY=... pnpm dlx ts-node packages/agentic/examples/defs-bindings-agent/workflow.ts
+void main();

package/examples/defs-bindings-agent/workflow.yml

@@ -0,0 +1,28 @@
+---
+defs:
+  calculate:
+    kind: tools
+    action: caculate_score
+    description: "LLM Tool to calculate the score"
+    settings:
+      multiplier: 2
+      bias: 1
+  my_agent:
+    kind: task
+    action: ai_agent
+    inputs:
+      prompt: "Caculate the score for x=10"
+      system: "You are a helpful assistant"
+    settings:
+      provider: "openai"
+      model: "gpt-4o"
+      max_steps: 2
+    bindings:
+      tools:
+        - calculate
+
+flow:
+  - do: my_agent
+
+outputs:
+  result: "=$output.my_agent.text"

package/examples/full/actions/await-user-input.ts

@@ -0,0 +1,46 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { z } from 'zod';
+
+import { defineAction } from '../../../src';
+import { SettingsSchema } from '../../../src/dsl.types';
+import type { ExampleContext } from '../context';
+
+const inputSchema = z.object({
+  prompt: z.string(),
+  allow_attachments: z.boolean().optional(),
+});
+const outputSchema = z.object({
+  text: z.string().optional(),
+  attachments: z.array(z.string()).optional(),
+});
+const settingsSchema = SettingsSchema;
+
+type AwaitUserInput = z.infer<typeof inputSchema>;
+type AwaitUserOutput = z.infer<typeof outputSchema>;
+type AwaitUserSettings = z.infer<typeof settingsSchema>;
+
+export const awaitUserInput = defineAction<
+  AwaitUserInput,
+  AwaitUserOutput,
+  ExampleContext,
+  AwaitUserSettings
+>({
+  name: 'await_user_input',
+  description: 'Placeholder action for human-in-the-loop pauses.',
+  inputSchema,
+  outputSchema,
+  settingSchema: settingsSchema,
+  execute: async ({ input, context }) => {
+    context.log('Would ask user to reply', { prompt: input.prompt });
+
+    return {
+      text: 'Sample user reply for the demo run.',
+      attachments: input.allow_attachments ? ['file-attachment-id'] : [],
+    };
+  },
+});

package/examples/full/actions/call-llm.ts

@@ -0,0 +1,133 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { z } from 'zod';
+
+import { defineAction } from '../../../src';
+import { SettingsSchema } from '../../../src/dsl.types';
+import type { ExampleContext } from '../context';
+
+const inputSchema = z.record(z.any());
+const outputSchema = z
+  .object({
+    intent: z.string().optional(),
+    confidence: z.number().optional(),
+    summary: z.string().optional(),
+    missing_fields: z.array(z.string()).optional(),
+    needs_human: z.boolean().optional(),
+    synthesis: z.string().optional(),
+    questions: z.array(z.string()).optional(),
+    message: z.string().optional(),
+    links: z.array(z.string()).optional(),
+    email: z.string().optional(),
+    cta: z.string().optional(),
+  })
+  .passthrough();
+const settingsSchema = SettingsSchema;
+
+type CallLlmInput = z.infer<typeof inputSchema>;
+type CallLlmOutput = z.infer<typeof outputSchema>;
+type CallLlmSettings = z.infer<typeof settingsSchema>;
+
+const asString = (value: unknown, fallback: string): string => {
+  if (typeof value === 'string' && value.trim().length > 0) {
+    return value;
+  }
+
+  return fallback;
+};
+
+export const callLlm = defineAction<
+  CallLlmInput,
+  CallLlmOutput,
+  ExampleContext,
+  CallLlmSettings
+>({
+  name: 'call_llm',
+  description:
+    'Mock LLM that returns deterministic data for the example workflow.',
+  inputSchema,
+  outputSchema,
+  settingSchema: settingsSchema,
+  execute: async ({ input }) => {
+    if ('system_prompt' in input) {
+      const query = asString(input.user_query, 'customer request');
+      const normalized = query.toLowerCase();
+      const intent =
+        normalized.includes('buy') || normalized.includes('price')
+          ? 'sales'
+          : normalized.includes('support') ||
+              normalized.includes('bug') ||
+              normalized.includes('error')
+            ? 'support'
+            : 'research';
+
+      return {
+        intent,
+        confidence: intent === 'support' ? 0.92 : 0.88,
+        summary: query.slice(0, 120),
+        missing_fields: [],
+        needs_human: false,
+      };
+    }
+
+    if (
+      'news_snippets' in input ||
+      'memory_summary' in input ||
+      'meetings' in input
+    ) {
+      const intent = asString(input.intent, 'request');
+      const profile = (input.profile as { company?: string }) ?? {};
+      const company = asString(profile.company, 'the customer');
+
+      return {
+        synthesis: `Brief for ${company} (${intent}): combined recent context, meetings, and user clarification.`,
+        questions: ['Any extra constraints or deadlines?'],
+      };
+    }
+
+    if ('troubleshooting_guide' in input) {
+      const question = asString(input.question, 'your issue');
+
+      return {
+        message: `Here is a support reply for ${question}.\n\n- Step 1: Restart.\n- Step 2: Apply guide specifics.`,
+        links: ['https://example.com/faq/diagnostics'],
+      };
+    }
+
+    if ('product_brief' in input) {
+      const companyNews = Array.isArray(input.company_news)
+        ? input.company_news
+        : [];
+      const lead =
+        companyNews.length > 0
+          ? companyNews[0]
+          : 'We have great news to share.';
+
+      return {
+        email: `Thanks for your interest. ${lead}`,
+        cta: 'Schedule a call this week.',
+      };
+    }
+
+    if ('stakeholder' in input) {
+      const stakeholder = input.stakeholder as { name?: string };
+      const question = asString(input.question, 'the request');
+      const name = asString(stakeholder?.name, 'Stakeholder');
+
+      return {
+        message: `${name}, quick update about ${question}. Research brief attached.`,
+      };
+    }
+
+    const summary = asString(
+      input.summary,
+      'Here is a concise summary of your request.',
+    );
+
+    return { message: summary };
+  },
+});

package/examples/full/actions/create-ticket.ts

@@ -0,0 +1,46 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { z } from 'zod';
+
+import { defineAction } from '../../../src';
+import { SettingsSchema } from '../../../src/dsl.types';
+import type { ExampleContext } from '../context';
+
+const inputSchema = z.object({
+  user_id: z.string(),
+  transcript: z.unknown().optional(),
+  summary: z.string().optional(),
+  clarification: z.string().optional(),
+});
+const outputSchema = z.object({
+  ticket_id: z.string(),
+  status: z.string(),
+});
+const settingsSchema = SettingsSchema;
+
+type CreateTicketInput = z.infer<typeof inputSchema>;
+type CreateTicketOutput = z.infer<typeof outputSchema>;
+type CreateTicketSettings = z.infer<typeof settingsSchema>;
+
+export const createTicket = defineAction<
+  CreateTicketInput,
+  CreateTicketOutput,
+  ExampleContext,
+  CreateTicketSettings
+>({
+  name: 'create_ticket',
+  description: 'Mocks creating a support ticket with the supplied context.',
+  inputSchema,
+  outputSchema,
+  settingSchema: settingsSchema,
+  execute: async ({ input, context }) => {
+    const ticket_id = `tkt-${input.user_id}-${Date.now()}`;
+    context.log('Created ticket', { ticket_id, summary: input.summary });
+
+    return { ticket_id, status: 'open' };
+  },
+});

package/examples/full/actions/decision-router.ts

@@ -0,0 +1,83 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { z } from 'zod';
+
+import { defineAction } from '../../../src';
+import { SettingsSchema } from '../../../src/dsl.types';
+import type { ExampleContext } from '../context';
+
+const inputSchema = z.object({
+  intent: z.string(),
+  priority: z.string().optional(),
+  confidence: z.number().optional(),
+  needs_human: z.boolean().optional(),
+});
+const outputSchema = z.object({
+  route: z.enum([
+    'draft_support_reply',
+    'craft_sales_pitch',
+    'escalate_to_human',
+    'send_generic_summary',
+  ]),
+  explanation: z.string(),
+});
+const settingsSchema = SettingsSchema;
+
+type DecisionRouterInput = z.infer<typeof inputSchema>;
+type DecisionRouterOutput = z.infer<typeof outputSchema>;
+type DecisionRouterSettings = z.infer<typeof settingsSchema>;
+
+export const decisionRouter = defineAction<
+  DecisionRouterInput,
+  DecisionRouterOutput,
+  ExampleContext,
+  DecisionRouterSettings
+>({
+  name: 'decision_router',
+  description: 'Routes work based on intent, priority, and confidence.',
+  inputSchema,
+  outputSchema,
+  settingSchema: settingsSchema,
+  execute: async ({ input, context }) => {
+    const confidence = input.confidence ?? 0;
+
+    if (input.needs_human) {
+      return {
+        route: 'escalate_to_human',
+        explanation: 'User requested human help.',
+      };
+    }
+
+    if (input.intent === 'support' && confidence > 0.6) {
+      return {
+        route: 'draft_support_reply',
+        explanation: 'Confident support intent.',
+      };
+    }
+
+    if (input.intent === 'sales') {
+      return {
+        route: 'craft_sales_pitch',
+        explanation: 'Sales intent detected.',
+      };
+    }
+
+    if (input.priority === 'high') {
+      return {
+        route: 'escalate_to_human',
+        explanation: 'High priority requires escalation.',
+      };
+    }
+
+    context.log('Falling back to generic summary');
+
+    return {
+      route: 'send_generic_summary',
+      explanation: 'No specific branch matched.',
+    };
+  },
+});

package/examples/full/actions/get-calendar-events.ts

@@ -0,0 +1,55 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { z } from 'zod';
+
+import { defineAction } from '../../../src';
+import { SettingsSchema } from '../../../src/dsl.types';
+import type { ExampleContext } from '../context';
+
+const inputSchema = z.object({
+  user_email: z.string(),
+  range: z.string().optional(),
+});
+const outputSchema = z.object({
+  events: z.array(
+    z.object({
+      title: z.string(),
+      when: z.string(),
+    }),
+  ),
+});
+const settingsSchema = SettingsSchema;
+
+type GetCalendarEventsInput = z.infer<typeof inputSchema>;
+type GetCalendarEventsOutput = z.infer<typeof outputSchema>;
+type GetCalendarEventsSettings = z.infer<typeof settingsSchema>;
+
+export const getCalendarEvents = defineAction<
+  GetCalendarEventsInput,
+  GetCalendarEventsOutput,
+  ExampleContext,
+  GetCalendarEventsSettings
+>({
+  name: 'get_calendar_events',
+  description: 'Provides a short list of upcoming meetings.',
+  inputSchema,
+  outputSchema,
+  settingSchema: settingsSchema,
+  execute: async ({ input, context }) => {
+    context.log('Pulling calendar events', {
+      user_email: input.user_email,
+      range: input.range,
+    });
+
+    return {
+      events: [
+        { title: 'Product sync', when: 'Tomorrow 10:00' },
+        { title: 'Stakeholder update', when: 'Friday 14:00' },
+      ],
+    };
+  },
+});