Forem: Akhil

Struggling to make LangGraph agents work in a strict NestJS & TypeScript environment? I spent my weekend fighting through the documentation gap so you don't have to. Here’s the complete guide to building a modular, tool-using AI agent from scratch.

Akhil — Sat, 04 Oct 2025 23:30:08 +0000

Akhil

Oct 4 '25

How to Build a Modular AI Agent with LangGraph in NestJS & TypeScript

#typescript #nestjs #langgraph #node

Comments

6 min read

How to Build a Modular AI Agent with LangGraph in NestJS & TypeScript

Akhil — Sat, 04 Oct 2025 23:14:01 +0000

The world of AI is buzzing with the concept of autonomous agents. From simple tool-users to complex systems that can plan and execute tasks, developers are eager to build the next generation of intelligent applications. LangChain, with its powerful LangGraph library, has emerged as a key player in this space.

However, if you're a developer working in the Node.js ecosystem with professional frameworks like NestJS and a love for strict TypeScript, you might have felt a bit lost. The documentation, while excellent, often focuses on Python or simpler JavaScript examples, leaving us to piece together the patterns for a robust, modular, and type-safe implementation.

After a journey of trial, error, and discovery, I'm here to share the guide I wish I had. We're going to build a real, working AI agent from scratch, strictly following the latest LangGraph patterns in a NestJS environment.

What We're Building: Triage Panda 🐼

To make this practical, we'll use our agent, Triage Panda, as the example. Its job is to act as an autonomous software engineering assistant that automatically triages new GitHub issues. When a new issue is created, the agent reads it, decides on appropriate labels, uses tools to apply them, and posts a comment back to GitHub.

This requires a stateful, multi-step workflow...a perfect use case for LangGraph.

The Architectural Blueprint: Engine vs. Specialist 🏗️

The key to building a scalable and reusable agent is to separate the generic logic from the task-specific logic. We'll achieve this with a two-part architecture:

The Generic AgentService (The Engine): This is our core, reusable class. It knows how to run an agentic loop (Think -> Act -> Observe) but knows nothing about GitHub, Slack, or any other specific task. It's a pure orchestrator.
The Specialist GithubAgentService (The Mission Commander): This class knows what the mission is. It's responsible for preparing the specific tools (e.g., GitHub tools) and prompts for a given task, and then telling the generic Engine to start.

This design allows us to easily add a GitlabAgentService or SlackAgentService later without ever touching our core agent engine.

Step 1: Building the Tools of the Trade 🛠️

An agent is only as good as its tools. Using the latest tool helper from @langchain/core/tools and Zod for schema validation, we can define our tools in a clean and type-safe way. We'll create a GithubService class to act as a factory for these.

Here’s how we define a tool to fetch a GitHub issue. The description is the most critical part, as it's the instruction manual the LLM reads to decide when to use the tool.

// backend/src/modules/github/domain/services/github.service.ts
import { tool } from '@langchain/core/tools';
import { z } from 'zod';

@Injectable()
export class GithubService {

  private getTools(): DynamicStructuredTool[] {
    // The `tool` helper function from LangChain is used to wrap any function
    // into a tool that the AI agent can understand and call.
    const getIssueByNumberTool = tool(
      // The first argument is the actual async function to execute when the tool is called.
      async (input: { owner: string; repo: string; issueNumber: number }) => {
        // ... findIssueByNumber is the custom class method
        const issue = await this.findIssueByNumber(
          input.owner,
          input.repo,
          input.issueNumber,
        );
        return JSON.stringify(issue);
      },
      // The second argument is a configuration object that "describes" the tool to the LLM.
      {
        name: 'get_github_issue_by_number',
        description:
          'Fetches details for a single GitHub issue. Use this as the first step to get the context of the issue.',
        schema: z.object({
          owner: z.string().describe('The owner of the repository.'),
          repo: z.string().describe('The name of the repository.'),
          issueNumber: z.number().describe('The number of the issue to fetch.'),
        }),
      },
    );

    // ... definitions for postCommentTool and addLabelsTool

    return [getIssueByNumberTool, /* ...other tools */];
  }
}

Step 2: The Reusable Agent Engine (`AgentService`) ⚙️

This is the core of our architecture. It's a generic service that takes any set of tools and messages, compiles a StateGraph on the fly, and runs the agentic loop until a final answer is produced.

Notice how this service has no mention of "GitHub"; it's completely reusable.

// backend/src/modules/agent/domain/services/agent.service.ts
import { Injectable, InternalServerErrorException, Logger } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { ChatGoogleGenerativeAI } from '@langchain/google-genai';
import { AIMessage, BaseMessage } from '@langchain/core/messages';
import { Tool } from '@langchain/core/tools';
import { StateGraph, MessagesAnnotation, END, START } from '@langchain/langgraph';
import { ToolNode } from '@langchain/langgraph/prebuilt';
import { Runnable } from '@langchain/core/runnables';

interface AgentResult {
  response: string;
  fullHistory: BaseMessage[];
}

@Injectable()
export class AgentService {
  private static readonly logger = new Logger(AgentService.name);
  // ... static properties for model name, etc.

  constructor(private readonly configService: ConfigService) {}

  public async invoke(tools: Tool[], messages: BaseMessage[]): Promise<AgentResult> {
    const model = this.createModel(tools);
    const graph = this.buildGraph(tools, model);

    const finalState: typeof MessagesAnnotation.State = await graph.invoke(
      {messages},
      {recursionLimit: AgentService.MAX_RECURSION_LIMIT},
    );

    const lastMessage = finalState.messages[finalState.messages.length - 1];
    this.validateAgentResponse(lastMessage);

    return {
      response: lastMessage.content as string,
      fullHistory: finalState.messages,
    };
  }


  private createModel(tools: DynamicStructuredTool[]): Runnable {
    const LLM_API_KEY = this.configService.get<string>('llm.geminiApiKey')!

    // The .bindTools() method attaches our tool definitions to the LLM,
    // allowing it to decide when to call them.
    return new ChatGoogleGenerativeAI({
      model: AgentService.LLM_MODEL_NAME,
      temperature: AgentService.DEFAULT_TEMPERATURE,
      apiKey: LLM_API_KEY,
    }).bindTools(tools)
  }

  private buildGraph(
    tools: DynamicStructuredTool[],
    model: Runnable,
  ): typeof StateGraph.prototype.compile extends () => infer R ? R : never {
    // The ToolNode is a pre-built node from LangGraph that knows how to execute tools.
    const toolNode = new ToolNode(tools)

    // This is our "Think" node. It calls the LLM to get the next action.
    const callModel = async (
      state: typeof MessagesAnnotation.State,
    ): Promise<Partial<AgentState>> => {
      const response = (await model.invoke(state.messages)) as AIMessage
      return {messages: [response]}
    }

    // This is our "Router". It evaluates the LLM's response to determine the next step.
    const shouldContinue = (
      state: typeof MessagesAnnotation.State,
    ): 'tools' | '__end__' => {
      const {messages} = state
      const lastMessage = messages[messages.length - 1] as AIMessage
      if (messages.length > AgentService.MAX_MESSAGE_COUNT) {
        return END
      }
      // If the LLM's last message contains a tool call, we route to the 'tools' node.
      if (lastMessage.tool_calls?.length) {
        return 'tools'
      }
      return END
    }

    return new StateGraph(MessagesAnnotation)
      .addNode('agent', callModel)
      .addNode('tools', toolNode)
      .addEdge(START, 'agent')
      .addEdge('tools', 'agent')  // After executing tools, always go back to the "agent" to think again.
      // The conditional edge is the router. After the "agent" node, call `shouldContinue`
      // to decide whether to go to the "tools" node or to the special "END" node.
      .addConditionalEdges('agent', shouldContinue)
      .compile()
  }

  private validateAgentResponse(message: unknown): void {
    // ... validation logic
  }
}

Step 3: The Specialist (`GithubAgentService`) 🐙

With the powerful generic engine in place, our GithubAgentService becomes incredibly simple and focused. Its only job is to prepare the "mission briefing": get the right tools and craft the right prompt.

// backend/src/modules/github/domain/services/github-agent.service.ts
import { Injectable, Logger } from '@nestjs/common';
import { BaseMessage, HumanMessage, SystemMessage } from '@langchain/core/messages';
import { AgentService } from 'src/modules/agent/domain/services/agent.service';
import { GithubTool } from 'src/modules/github/tools/github.tool'; // Our tool factory

@Injectable()
export class GithubAgentService {
  private static logger = new Logger(GithubAgentService.name);

  constructor(
    private readonly agentService: AgentService, // Inject the generic engine
  ) {}

    public async startTriage(
    owner: string,
    repo: string,
    issueNumber: number,
    tools: DynamicStructuredTool[],
  ): Promise<void> {
    GithubAgentService.logger.log(
      `Starting triage for ${owner}/${repo} #${issueNumber}`,
    )

    const systemPrompt = `
          You are an expert GitHub issue triaging agent. Your goal is to fully triage the issue provided.
            1. First, call the 'get_github_issue' tool to fetch the issue content.
            2. Analyze the issue's title and body to determine appropriate labels and a helpful summary comment.
            3. Call the 'add_github_labels' and 'post_github_comment' tools to apply your analysis.
            4. Once all tools have been successfully called, respond with a final confirmation message summarizing your actions.
          `

    const userPrompt = `Please triage issue #${issueNumber} in the repository ${owner}/${repo}.`

    const messages: BaseMessage[] = [
      new SystemMessage(systemPrompt),
      new HumanMessage(userPrompt),
    ]

    try {
      const result = await this.agentService.invoke(tools, messages)
      GithubAgentService.logger.log(
        `Triage complete for issue #${issueNumber}. Final response: "${result.response}"`,
      )
    } catch (error) {
      GithubAgentService.logger.error(
        `Triage failed for issue #${issueNumber}`,
        error,
      )
    }
  }
}

Step 4: The Invoker (`GithubService`) 🐙

When it gets triggered by the GitHub webhook URL, its only job is to further invoke the GitHub agent by passing the tools and the initial state.

// backend/src/modules/github/domain/services/github.service.ts
@Injectable()
export class GithubService {
  private static logger = new Logger(GithubService.name);

  constructor(
    private readonly agentService: GithubAgentService,, // Inject the github agent service
  ) {}

    public handleWebhook(
    signature: string,
    rawBody: Buffer | undefined,
    payload: GithubWebhookPayload,
  ): GithubWebhook {
    this.verifySignature(signature, rawBody)

    const event = payload.action

    if (event !== 'opened') {
      this.logger.log(`Ignoring action: ${event}`)
      return {status: 'ignored', reason: `Action was ${event}, not 'opened'`}
    }

    const owner = payload.repository.owner.login
    const repo = payload.repository.name
    const issueNumber = payload.issue.number

    this.logger.log(
      `Webhook processed for issue #${issueNumber} in ${owner}/${repo}`,
    )

    void this.agentService.startTriage(
      owner,
      repo,
      issueNumber,
      this.getTools(),
    )
    return {status: 'processing'}
  }

 // getTools method created in step #1
 private getTools(): DynamicStructuredTool[] { ... }

}

Conclusion & What's Next 🚀

We've successfully built a simple but powerful and most importantly modular AI agent in a professional NestJS and TypeScript environment. This architecture provides a solid foundation for building much more complex applications in the future. By separating the generic engine from the specialist logic, we can easily add new capabilities without rewriting our core workflow.

In our next blog post, we'll dive into observability. We'll integrate Langfuse, an open-source tracing tool, to visualize our agent's every thought and action, making debugging and analysis a breeze.

The full source code for our Triage Panda agent can be found on GitHub. Feel free to explore it, open issues (and watch the agent triage them!), and contribute.

d-akhil-kumar / triage-panda

🐼 AI-Powered GitHub Issue Triage Agent 🤖

🐼 triage-panda – AI-Powered GitHub Issue Triage Agent 🤖

An autonomous AI agent 🐼 built with NestJS and LangGraph to automatically triage and manage GitHub issues. This project leverages the power of Large Language Models (LLMs) to understand, categorize, prioritize, and comment on new issues, streamlining the workflow for development teams.

✨ Core Features

This agent uses a stateful, cyclical workflow to perform its tasks. When a new issue is created in a configured repository, the agent will:

Webhook Trigger: Automatically activate when a new issue is created via a GitHub webhook.
Multi-Step Tool Use:
- First, it fetches the issue content using the get_github_issue_by_number tool.
- It analyzes this content to decide on appropriate labels and a summary comment.
- Finally, it uses the add_github_labels and post_github_comment tools to apply its analysis back to GitHub.
AI-Powered Decisions: Uses Google's Gemini model to reason about the issue and decide which tools to use…

View on GitHub

Happy building! Let me know your thoughts, questions, and what you're building with this stack in the comments below.

🚀 Will deleting the package-lock.json makes me cool 😎?

Akhil — Wed, 17 Sep 2025 16:49:55 +0000

🚀 npm Dependencies Demystified: The Great `package-lock` Mystery

As developers, we've all been there: a teammate runs npm install and suddenly their app breaks, even though it works on my machine™ . It's a classic programming horror story. The villain? Often an unexpected plot twist in dependency version resolution, brought to you by disrespecting the package-lock.json file.

Let's pull back the curtain and solve this mystery once and for all. 👇

📦 Semver Basics: A Tale of Three Symbols (`^`, `~`, and The Silent')

Think of your dependencies like a subscription service for code. The version number is your subscription plan.

Exact version ("express": "4.17.1") You're signing up for a fixed plan. No changes, ever. You'll always get 4.17.1 and nothing else. It's the most stable, but you'll miss out on security patches and bug fixes unless you manually update.

Tilde ~ (Patch Updates) 🩹
```
"express": "~4.17.1"
```
This is like a "same minor version, but give me the latest bug fixes" plan. You'll get any new patch versions, but you're staying within the 4.17.x family. So, 4.17.1 could update to 4.17.3, but it will never jump to 4.18.0.
Caret ^ (Minor + Patch Updates) 🚀
```
"express": "^4.17.1"
```
This is the "latest and greatest, but within the same major version" plan. You get all the new features and fixes as long as they don't break compatibility. 4.17.1 could update to 4.18.2 or 4.19.0, but it will never jump to a scary 5.0.0 (which could have breaking changes).

So remember:

~ = "Patch me up!"
^ = "Rocket me to the next minor version!"

🔒 The `package-lock.json`: Your Project's DNA

When you run npm install, npm takes a snapshot of your entire dependency family tree, including every single nested version. This snapshot is saved in the package-lock.json file.

Imagine package.json is your grocery list: "I need milk (^1.0.0) and bread (~2.0.0)".
The package-lock.json is the receipt from your last shopping trip: "I bought Milk@1.2.5 from this specific brand, and Bread@2.0.3 from that other brand."

✅ With package-lock.json: Everyone on your team gets the exact same groceries from the last trip. Predictability and consistency are guaranteed.

❌ Without package-lock.json: Every time you go to the store, you'll get the "latest milk" and "latest bread," which might be different brands (different versions) from what your teammates got. This is where the "it worked on my machine" ghost appears.

👻 An Example Scenario: The Disappearing Dependency Trick

Let's say your package.json has:

{
  "dependencies": {
    "A": "^1.0.0",
    "B": "^2.0.0"
  }
}

First Install:
You run npm install. At that moment, A@1.0.0 needs a dependency called X, which resolves to X@1.0.5. Your other dependency, B@2.0.0, also needs X, but it resolves to X@2.0.3.

Your dependency tree looks like this:

A → X@1.0.5
B → X@2.0.3

This precise, exact tree is locked into your package-lock.json.

A Week Later (The Mystery Begins):
New versions of X are released: X@1.0.6 and X@2.0.4.

If you were to delete your package-lock.json and run npm install again, npm will ignore your "receipt" and get the latest groceries according to your "shopping list" (package.json).

Your new tree:

A → X@1.0.6
B → X@2.0.4

Same package.json, different result! The app might now be broken because a new version of X introduced a bug or a breaking change. This is why deleting the lockfile is a developer's version of a high-risk stunt.

🤝 The Golden Rules: Stay Sane, Stay Consistent

Always commit package-lock.json to your repo. This is the secret handshake that guarantees everyone on the team is on the same page.
Use npm ci in CI/CD pipelines. ci stands for "clean install." It's like a drill sergeant: it installs exactly what's in your lockfile and fails if the two don't match. No surprises, no funny business.
Treat your package.json and package-lock.json as a single unit. They are yin and yang, the plan and the result.

🎯 TL;DR: The Final Verdict

^ → "I want the latest non-breaking features."
~ → "I just want bug fixes for this specific version."
package-lock.json → "I want to replicate this exact installation on any machine, anywhere, anytime."
Deleting the lockfile → "I like living dangerously and want to risk breaking my app for fun."

So, will deleting the package.lock file make you cool? Not really. It just makes you a chaotic agent of uncertainty. Keep your lockfile. Use npm ci. And save yourself from the eternal headache of "but it worked yesterday!" 😅

Managing Multiple GitHub Accounts (Work + Personal) on the Same Machine

Akhil — Thu, 04 Sep 2025 18:46:08 +0000

Managing Multiple GitHub Accounts

As developers, it’s common to juggle two GitHub accounts — one for work (e.g., akhil@<COMPANY_NAME>.com) and one for personal projects (e.g., akhil@gmail.com).

The challenge?

Git commits end up with the wrong email.
git push gets rejected because the wrong GitHub account is used.
Constantly logging in/out is frustrating.

In this post, I’ll walk you through how to configure Git + SSH to cleanly separate accounts so that your work and personal projects never interfere with each other.

🔎 The Problem I Faced

On my work laptop:

Git was configured with my work email globally.
My repos were cloned using HTTPS, which always authenticated via my company GitHub account.

When I tried pushing code to my personal GitHub repo, I got this error:

remote: Permission to d-akhil-kumar/log-panda.git denied to akhil-kumar-company-git.
fatal: unable to access 'https://github.com/d-akhil-kumar/log-panda.git/': The requested URL returned error: 403

GitHub was picking the wrong account (akhil-kumar-company-git from work), while I needed my personal account (d-akhil-kumar).

✅ The Solution: Separate SSH Keys and Git Configs

1. Generate a Personal SSH Key

I already had a company (default) SSH key (~/.ssh/id_rsa), so I created a new one for my personal account:

ssh-keygen -t ed25519 -C "your-personal-email@example.com" -f ~/.ssh/id_ed25519_personal

Now I have:

~/.ssh/id_rsa → company key
~/.ssh/id_ed25519_personal → personal key

2. Add Keys to the SSH Agent

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_rsa              # company
ssh-add ~/.ssh/id_ed25519_personal # personal

3. Add the Public Key to GitHub

Copy the personal key:

cat ~/.ssh/id_ed25519_personal.pub

Go to GitHub → Settings → SSH and GPG keys → New SSH key and paste it.

4. Configure SSH for Multiple Accounts

Edit (or create) ~/.ssh/config:

# Company GitHub
Host github.com-company
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_rsa

# Personal GitHub
Host github.com-personal
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_ed25519_personal

This tells SSH which key to use based on the alias (github.com-company or github.com-personal).

5. Update Git Remotes

Inside a personal repo, update the remote URL:

git remote set-url origin git@github.com-personal:your-username/your-repo.git

For a company repo:

git remote set-url origin git@github.com-company:company-org/repo-name.git

Check with:

git remote -v

6. Test the Connection

For personal:

ssh -T git@github.com-personal

For company:

ssh -T git@github.com-company

Both should greet you with the correct account username 🎉

7. Set Git Commit Identity Per Repo

Inside a personal repo:

git config user.name "Your Name"
git config user.email "your-personal-email@example.com"

Inside a company repo:

git config user.name "Your Name"
git config user.email "your-work-email@<COMPANY_NAME>.com"

Now, commits show up under the right account.

⚡ Bonus: Auto-Switch Identities

If you keep repos in separate folders (~/work/ and ~/personal/), Git can auto-switch your email:

Edit ~/.gitconfig:

[user]
    name = Your Name
    email = your-personal-email@example.com

[includeIf "gitdir:~/work/"]
    path = ~/.gitconfig-company

Create ~/.gitconfig-company:

[user]
    name = Your Name
    email = your-work-email@<COMPANY_NAME>.com

Now you never need to run git config manually again. 🚀

🎯 Final Result

Personal repos → push with personal GitHub account and personal email
Company repos → push with company GitHub account and company email
No more 403 errors or wrong commit authorship

🙌 Conclusion

Managing multiple GitHub accounts doesn’t have to be painful.
With separate SSH keys and smart Git config, you can seamlessly switch between personal and work repos without conflicts.

💡 Have you set up multiple GitHub accounts on your machine? Did you use SSH, HTTPS, or another trick? Let me know in the comments!

Forem: Akhil

Struggling to make LangGraph agents work in a strict NestJS & TypeScript environment? I spent my weekend fighting through the documentation gap so you don't have to. Here’s the complete guide to building a modular, tool-using AI agent from scratch.

How to Build a Modular AI Agent with LangGraph in NestJS & TypeScript

How to Build a Modular AI Agent with LangGraph in NestJS & TypeScript

What We're Building: Triage Panda 🐼

The Architectural Blueprint: Engine vs. Specialist 🏗️

Step 1: Building the Tools of the Trade 🛠️

Step 2: The Reusable Agent Engine (AgentService) ⚙️

Step 3: The Specialist (GithubAgentService) 🐙

Step 4: The Invoker (GithubService) 🐙

Conclusion & What's Next 🚀

d-akhil-kumar / triage-panda

🐼 AI-Powered GitHub Issue Triage Agent 🤖

🐼 triage-panda – AI-Powered GitHub Issue Triage Agent 🤖

✨ Core Features

🚀 Will deleting the package-lock.json makes me cool 😎?

🚀 npm Dependencies Demystified: The Great package-lock Mystery

📦 Semver Basics: A Tale of Three Symbols (^, ~, and The Silent')

🔒 The package-lock.json: Your Project's DNA

👻 An Example Scenario: The Disappearing Dependency Trick

🤝 The Golden Rules: Stay Sane, Stay Consistent

🎯 TL;DR: The Final Verdict

Managing Multiple GitHub Accounts (Work + Personal) on the Same Machine

Managing Multiple GitHub Accounts

🔎 The Problem I Faced

✅ The Solution: Separate SSH Keys and Git Configs

1. Generate a Personal SSH Key

2. Add Keys to the SSH Agent

3. Add the Public Key to GitHub

4. Configure SSH for Multiple Accounts

5. Update Git Remotes

6. Test the Connection

7. Set Git Commit Identity Per Repo

⚡ Bonus: Auto-Switch Identities

🎯 Final Result

🙌 Conclusion

Step 2: The Reusable Agent Engine (`AgentService`) ⚙️

Step 3: The Specialist (`GithubAgentService`) 🐙

Step 4: The Invoker (`GithubService`) 🐙

🚀 npm Dependencies Demystified: The Great `package-lock` Mystery

📦 Semver Basics: A Tale of Three Symbols (`^`, `~`, and The Silent')

🔒 The `package-lock.json`: Your Project's DNA