Examples

These examples are meant to be adapted into real applications, not only read as API snippets.

1. Structured Extraction

Use this when your app needs predictable JSON rather than prose.

const chain = prompt.pipe(model).pipe(parser);
const result = await chain.invoke({ ticket: "Payment failed twice" });

Good fits:

• support ticket triage
• document metadata extraction
• moderation labels

2. Input Enrichment With RunnableMap

Use this when one raw input needs to become several prompt variables.

const inputMap = new RunnableMap({
  topic: new RunnableLambda(({ topic }) => topic.trim()),
  tone: new RunnableLambda(() => "concise")
});

Good fits:

• normalizing user input
• injecting defaults
• combining user data with app policy

3. Independent Branches With RunnableParallel

Use this when multiple calculations can happen from the same input without waiting on one another.

const parallel = new RunnableParallel({
  length: new RunnableLambda((text: string) => text.length),
  upper: new RunnableLambda((text: string) => text.toUpperCase())
});

Good fits:

• feature extraction
• side-by-side scoring
• parallel preprocessing

4. Tool-Based Agent

Use Agent + tool(...) when the model may need external information before it can answer.

Good fits:

• weather lookup
• CRM lookup
• calendar or ticket actions

Prefer a chain-only design until your task truly needs tool choice or a reasoning loop.

5. Choosing Between Chain And Agent

Scenario	Better Fit
summarize text into JSON	chain
classify support tickets	chain
answer using a fixed retrieved context	chain
decide whether to call weather or search	agent
execute multi-step tool workflows	agent

6. Workflow + Agent Together

Use this pattern when you want deterministic orchestration around an agent loop.

import { z } from "zod";
import { Agent, Workflow, tool } from "@ai-agent-framework/core";
import { openai } from "@ai-agent-framework/openai";

const searchTool = tool({
  name: "searchDocs",
  description: "Search internal docs for an answer",
  schema: z.object({ query: z.string() }),
  async execute({ query }) {
    return { query, hits: ["doc-1", "doc-2"] };
  }
});

const agent = new Agent({
  model: openai({ model: "gpt-4o-mini" }),
  tools: [searchTool],
  maxSteps: 8,
  hooks: {
    onStart(state) {
      console.log("agent started", { steps: state.steps });
    },
    onEnd(_state, result) {
      console.log("agent finished", { chars: result.length });
    }
  }
});

const workflow = new Workflow({
  steps: [
    {
      id: "normalize-input",
      run: (input: string) => input.trim()
    },
    {
      id: "agent-answer",
      run: async (normalized: string) => agent.run(normalized)
    },
    {
      id: "attach-metadata",
      run: (answer: string) => ({
        answer,
        generatedAt: Date.now()
      })
    }
  ]
});

const result = await workflow.run("  Find rollout risks for release  ");
console.log(result.output);
console.log(result.snapshots.length);

Why this works well:

• Workflow handles step orchestration and resume state
• Agent handles tool-choice and iterative reasoning
• hooks make instrumentation straightforward