DEV Community: Manav

Building a Multi-Agent AI for Company LinkedIn Pages - Part 10: Wiring All the Agents Together

Manav — Wed, 12 Aug 2026 06:30:07 +0000

In the previous articles, we built every agent individually.

Each one had a single responsibility. The Orchestrator classified the topic. The Research Agent gathered information. The Examples Agent found supporting examples. The Critic Agent questioned the research. The Brief Agent structured everything. The Hook Agent generated opening lines. The Draft Agent wrote complete posts. Finally, the Writing Critic Agent evaluated those drafts.

Now it's time to connect everything together.

That's why we write the main.py file.

Unlike the previous articles, we aren't introducing a new agent here. Instead, we're wiring every existing agent into a single pipeline where the output of one agent becomes the input of the next.

User Topic 
    │ 
    ▼
Orchestrator 
    │ 
    ▼ 
 Research 
    │ 
    ▼ 
 Examples 
    │ 
    ▼ 
  Critic 
    │ 
    ▼ 
  Brief 
    │ 
    ▼ 
  Hook 
    │ 
    ▼ 
  Draft 
    │ 
    ▼ 
Writing Critic 
    │ 
    ▼ 
Final Result

Before writing the main() function, we import every agent we've built so far.

from agents.writing_critic import rate_drafts 
from agents.draft import generate_drafts 
from agents.hook import generate_hooks 
from agents.brief import create_brief 
from agents.critic import be_critique 
from agents.examples import get_examples 
from agents.research import research_agent 
from agents.orchestrator import classify_topic

The order of these imports almost mirrors the order of execution. Every stage depends on the output produced by the previous one.

Now let's break down the main() function before looking at the complete code.

It starts by taking a topic from the user and passing it to the Orchestrator Agent. If classification fails, the pipeline stops immediately.

Every step after that follows the same pattern:

Run the agent.
Validate its output.
Stop if it fails.
Otherwise pass the result to the next agent.

This makes the pipeline predictable and prevents downstream agents from working with incomplete data.

if classified_topic is None: return

The same idea is repeated throughout the pipeline.

Research must return chunks.

Examples must return examples.

The Brief Agent must return a valid ContentBrief.

The Draft Agent must return two drafts.

If any step fails, we stop immediately instead of allowing later agents to produce unreliable output.

if len(research) == 0: return

Once every agent succeeds, the final stage is the Writing Critic Agent.

Instead of generating more content, it evaluates both drafts, scores them across multiple dimensions, and recommends the stronger draft.

print("Scoring the drafts...")
scoring = rate_drafts(hooks, drafts)

Putting everything together gives us the complete orchestration function.

def main(topic): 
   print("Classifying topic...") 
   classified_topic = classify_topic(topic) 
   if classified_topic is None: 
      print("Failed to classify topic") 
      return 
   print("Researching...") 
   research = research_agent(classified_topic) 
   if len(research) == 0: 
      print("Failed to research") 
      return 
   print("Fetching suitable examples...") 
   examples = get_examples(classified_topic, research) 
   if len(examples) == 0: 
      print("Failed to fetch examples") 
      return 
   print("Flagging mistakes...") 
   critic = be_critique(classified_topic, research, examples) 
   if len(critic) == 0: 
      print("Failed to flag mistakes") 
      return 
   print("Creating a brief...") 
   brief = create_brief(classified_topic, research, examples, critic)
   if brief is None: 
      print("Failed to create brief") 
      return 
   print("Generating 5 Hooks...") 
   hooks = generate_hooks(brief) 
   if len(hooks) < 3: 
      print("Failed to generate enough hooks") 
      return 
   print("Generating 2 drafts...") 
   drafts = generate_drafts(hooks, brief) 
   if len(drafts) == 0: 
      print("Failed to generate drafts") 
      return 
   print("Scoring the drafts...") 
   scoring = rate_drafts(hooks, drafts) 
   if scoring is None: 
      print("Failed to generate score") 
      return print(scoring) 
   print("Feel free to suggest any changes!")

   if __name__ == "__main__":
      topic = input("Enter your topic") main(topic)

At this point, we've successfully wired every agent into a single end-to-end pipeline. From a single topic, the system can classify the request, gather research, find supporting examples, critique the evidence, build a structured brief, generate multiple hooks, write complete drafts, and score them automatically.

Right now, everything still runs from the terminal. In the next article, we'll expose this entire pipeline through a FastAPI backend, allowing any frontend application to generate LinkedIn posts with a single API request.

GitHub Repo: https://github.com/Manav-N4/linkedin-agent#linkedin-agent

Building a Multi-Agent AI for Company LinkedIn Pages - Part 9: Building the Writing Critic Agent

Manav — Fri, 07 Aug 2026 06:45:34 +0000

Our system can now understand a topic, gather research, find supporting examples, identify weak assumptions, structure everything into a content brief, generate multiple hooks, and write two complete LinkedIn post drafts.

But generating two drafts creates a new problem.

Which one is actually better?

That's why we built the Writing Critic Agent.

Unlike the earlier Critic Agent, which evaluates the research before any writing begins, the Writing Critic Agent evaluates the finished LinkedIn drafts. It doesn't rewrite or improve them. Instead, it scores each draft so the user can confidently choose the stronger one.

5 Hooks
     │
     ▼
2 Drafts
     │
     ▼
Writing Critic Agent
     │
     ▼
Scores + Recommendation

Before we start writing code, let's define the system prompt.

I wanted the Writing Critic Agent to judge the drafts the same way a real LinkedIn reader would. Instead of checking grammar or rewriting sentences, it scores each draft across three dimensions:

Originality: Does it sound fresh or like another generic AI-generated LinkedIn post?
Promise fulfilment: Does the post actually deliver what the hook promised?
Shareability: Would someone realistically save, comment on, or repost it?

It also compares both drafts and recommends which one should be used.

SYSTEM_PROMPT = """
Evaluate 2 LinkedIn drafts.

Score each draft on:
- Originality
- Promise fulfilment
- Shareability

Compare both drafts.

Return valid JSON.
"""

The production prompt is much longer, but I've shortened it here to highlight the core rules.

Unlike the Draft Agent, this agent doesn't require the Content Brief anymore. At this stage, we only need the generated hooks and the two drafts because those are the outputs being evaluated.

user_message = (
    f"Hooks: {hooks}\n\nDRAFTS:\n"
    + "\n---\n".join(drafts)
)

Instead of returning a list, the Writing Critic Agent returns a structured JSON object. Each draft receives individual scores and explanations, followed by a comparison section that recommends the stronger draft.

{
    "draft_0": {...},
    "draft_1": {...},
    "comparison": {...}
}

Since downstream code expects a valid JSON object, we parse the response inside a try and except block. If parsing fails, the function returns None instead of crashing the pipeline.

try:
    parsed = json.loads(refined_response)
except json.JSONDecodeError:
    print("LLM did not return valid JSON:")
    print(raw_response)
    return None

Before writing the function, let's break down what happens.

The function takes the generated hooks and two LinkedIn drafts as input, builds the user message, calls the LLM, strips markdown fences, parses the JSON response, and finally returns the structured evaluation.

def rate_drafts(hooks: list[str], drafts: list[str]) -> dict | None:
    user_message = (
        f"Hooks: {hooks}\n\nDRAFTS:\n"
        + "\n---\n".join(drafts)
    )
    raw_response = call_llm(SYSTEM_PROMPT, user_message)
    refined_response = strip_json_fences(raw_response)
    try:
        parsed = json.loads(refined_response)
    except json.JSONDecodeError:
        print("LLM did not return valid JSON:")
        print(raw_response)
        return None
    return parsed

At this point, every individual agent has been built and tested independently. Each one has a single responsibility, from understanding the topic to scoring the final drafts.

In the next article, we'll wire all these agents together into a complete multi-agent pipeline that takes a topic as input and automatically generates, evaluates, and returns ready-to-publish LinkedIn posts.

Github Repo: https://github.com/Manav-N4/linkedin-agent#linkedin-agent

Building a Multi-Agent AI for Company LinkedIn Pages - Part 8: Building the Draft Agent

Manav — Wed, 05 Aug 2026 09:45:33 +0000

Our system can now understand the topic, gather research, find supporting examples, identify weaknesses, structure everything into a content brief, and generate multiple hook options.

But hooks alone aren't enough. We still need complete LinkedIn posts that the user can actually choose between.

That's why we built the Draft Agent.

Unlike the previous agents, the Draft Agent doesn't work with raw research. Instead, it takes the Content Brief and the five generated hooks, then turns them into two complete LinkedIn post drafts.

Content Brief
      │
      ├───────────┐
      │           │
      ▼           ▼
   Hook Agent   5 Hooks
        │         │
        └────┬────┘
             ▼
        Draft Agent
             │
             ▼
       Draft A + Draft B

Instead of generating a single post, I wanted to generate two completely different writing styles. One optimized for fast consumption on LinkedIn, and another that tells a stronger story.

Draft A: Short, punchy and highly skimmable.
Draft B: Narrative driven with a beginning, middle and end.

Before writing any code, let's define the system prompt.

I want the Draft Agent to choose the best hook from the five options, use it as the opening line for both drafts, and make sure both posts stay faithful to the content brief while having completely different writing styles.

SYSTEM_PROMPT = """
Generate exactly 2 LinkedIn drafts.

Draft A:
- Punchy
- Short paragraphs
- Mobile friendly

Draft B:
- Narrative
- Story driven
- Lesson at the end

Use the same hook for both drafts.

Return valid JSON.
"""

The production prompt is much longer, but I've shortened it here to highlight the core rules.

Unlike the Hook Agent, this agent combines two different inputs. The structured brief and all five generated hooks are passed together so the model has both the planning context and multiple opening options.

brief_dict = brief.model_dump()

user_message = (
    "\n".join(
        f"{key}:{value}"
        for key, value in brief_dict.items()
    )
    + "\n\nHOOKS:\n"
    + "\n---\n".join(hooks)
)

Just like the previous agents, we retry generation up to three times if the model returns malformed JSON.

for attempt in range(max_retries):

Since downstream agents expect exactly two drafts, we validate the response before returning it.

if len(parsed) == 2:
    return parsed

Before writing the function, let's break down what happens.

The function takes the ContentBrief and five generated hooks as input. It converts the brief into a dictionary, builds the user message by appending the hooks, sends everything to the LLM, strips markdown fences, parses the JSON response, and validates that exactly two drafts were returned.

def generate_drafts(hooks: list[str], brief: ContentBrief, max_retries = 3) -> list[str]:
    brief_dict = brief.model_dump()
    user_message = (
        "\n".join([f"{key}:{value}" for key, value in brief_dict.items()])
        + "\n\nHOOKS:\n"
        + "\n---\n".join(hooks)
    )
    for attempt in range(max_retries):
        raw_response = call_llm(SYSTEM_PROMPT, user_message)
        refined = strip_json_fences(raw_response)
        try:
            parsed = json.loads(refined)
            if len(parsed) == 2:
                return parsed
        except json.JSONDecodeError:
            print(f"Draft attempt {attempt + 1} failed, retrying...")
    return []

At this point, our system can understand a topic, gather research, find supporting examples, critique weak arguments, structure everything into a content brief, generate multiple hooks, and finally generate two complete LinkedIn post drafts.

But generating multiple drafts introduces another question.

Which one is actually better?

In the next article, we'll build the Writing Critic Agent, which scores both drafts on originality, promise fulfilment, and shareability before recommending the stronger one.

Github Repo: https://github.com/Manav-N4/linkedin-agent#linkedin-agent

Building a Multi-Agent AI for Company LinkedIn Pages - Part 7: Building the Hook Agent

Manav — Mon, 03 Aug 2026 11:31:34 +0000

Our system can now classify a topic, conduct research, back it with examples, identify weak assumptions and unsupported claims, and structure everything into a content brief before handing it over to the writing agents.

Before the writing agents generate a full post, we need an opening that's compelling enough to stop people from scrolling.

That's why we built the Hook Agent.

Unlike the previous agents, it doesn't consume the topic, research, examples or critique directly. Instead, it only takes the ContentBrief generated by the Brief Agent.

Content Brief
      │
      ▼
Hook Agent
      │
      ▼
5 Hook Variations

Most of us aren't satisfied with the first hook we get. Instead of generating just one opening, I generate five different hook variations.

The Draft Agent can later use any one of these to generate complete posts. One hook format doesn't work for all posts, so we use different types of hook variations like Bold Claim, Statistic, Confession, Question, One-liner.

Before we start writing a single line of code, let's start with the system prompt. I explicitly instruct it to generate exactly five hooks, define the hook formats with examples, enforce a fixed ordering, and return valid JSON.

SYSTEM_PROMPT = """
Generate exactly 5 hooks.

Formats:
- Bold claim
- Stat
- Confession
- Question
- One-liner

Return valid JSON.
"""

The production prompt is much longer, but I've shortened it here to highlight the core rules.

So the JSON response returns hooks in the exact order which makes them easy to compare and lets downstream agents reference them deterministically. For example, hooks[0] is always the bold claim.

0 -> Bold Claim

1 -> Stat

2 -> Confession

3 -> Question

4 -> One-liner

Instead of manually constructing the prompt, I convert the ContentBrief object into a dictionary using model_dump() and serialize it into a structured user message.

brief_dict = brief.model_dump()

user_message = "\n".join(
    f"{k}: {v}"
    for k, v in brief_dict.items()
)

Just like the Critic Agent, the Hook Agent retries generation up to three times if the model returns malformed JSON or fewer than five hooks.

for attempt in range(max_retries):

Before returning the response, I validate that exactly five hooks were generated. I'd rather return no hooks than fewer than five. The Draft Agent expects all five hook formats, so partial output is treated as a failure.

if len(parsed) == 5:
    return parsed

Before writing code, let's breakdown what happens in the function. It takes a ContentBrief object as input, converts it into a dictionary using model_dump(), builds the user message, calls the LLM, strips markdown fences, parses the JSON response, and validates that exactly five hooks were returned.

def generate_hooks(brief: ContentBrief, max_retries = 3) -> list[str]:
    brief_dict = brief.model_dump()
    user_message = "\n".join([f"{key}:{value}" for key, value in brief_dict.items()])
    for attempt in range(max_retries):
        raw_response = call_llm(SYSTEM_PROMPT, user_message)
        refined = strip_json_fences(raw_response)
        try:
            parsed = json.loads(refined)
            if len(parsed) == 5:
                return parsed
        except json.JSONDecodeError:
            print(f"Hook attempt {attempt + 1} failed, retrying...")
    return []

At this point, our system can understand a topic, gather supporting research, find real-world examples, critique them, structure everything into a content brief, and generate five structured hook variations before writing a single post.

In the next article, we'll build the Draft Agent, which takes one of these hooks and turns it into complete LinkedIn post drafts for the user to choose from.

Github Repo: https://github.com/Manav-N4/linkedin-agent#linkedin-agent

Building a Multi-Agent AI for Company LinkedIn Pages - Part 6: Building the Brief Agent

Manav — Sat, 01 Aug 2026 15:09:23 +0000

Our system can now classify the topic, do the research, back it with examples and identify weak assumptions, unsupported claims, and irrelevant examples before handing everything over to the writing agents. But handing all of that information directly to the writing agents forces them to make too many decisions at once.

That's why we built the Brief Agent.

The Brief Agent takes topic, research chunks, examples and critique points as input and structures them into a single content brief so the writing agents don't have to decide which example to use, which angle to take, which statistic to highlight, or what nuance should be acknowledged.

Topic
   │
Research Chunks
   │
Examples
   │
Critique Points
   │
   ▼
Brief Agent
   │
   ▼
Content Brief

Before we start writing code, let's write the system prompt. I explicitly instructed the agent not to rewrite the research, examples or critique. Its job is to make decisions, organise the information, and return a structured JSON object.

SYSTEM_PROMPT = """
Create a structured content brief.

Choose:
- best angle
- strongest statistic
- best example
- important nuance
- suggested structure
- hook direction

Return valid JSON.
"""

The production prompt is much longer, but I've shortened it here to highlight the core rules.

Until now agents were responsible for gathering information. The Brief Agent is the one responsible for planning what needs to be done with this information and structuring it well for the writing agents.

Since every downstream writing agent depends on this output, I wanted to guarantee that the structure is always consistent. That's where Pydantic comes in.

class ContentBrief(BaseModel):
    angle: str
    key_stat: str
    best_example: str
    nuance_to_acknowledge: str
    suggested_structure: str
    hook_direction: str

Think of it like the contract between the Brief Agent and the Writing Agents.

user_message = (
        f"TOPIC: {cleaned_topic}\n\n"
        "RESEARCH_CHUNKS:\n"
        + "\n---\n".join(research_chunks)
        + "\n\nEXAMPLES:\n"
        + "\n---\n".join(example)
        + "\n\nCRITIQUE_POINTS:\n"
        + "\n---\n".join(critique)
    )

The user message consists of the topic, research chunks, examples and critique points. Instead of every writing agent collecting this context again, the Brief Agent packages everything into a single input.

Topic
   │
Research
   │
Examples
   │
Critique Points
   │
   ▼
Build user_message
   │
   ▼
call_llm()
   │
   ▼
strip_json_fences()
   │
   ▼
json.loads()
   │
   ▼
Pydantic Validation
   │
   ▼
ContentBrief

So, before we code the whole function, let's breakdown what exactly happens. The function first cleans the topic, builds a user message containing every previous agent's output, calls the LLM with the system prompt, strips markdown fences, parses the JSON, and finally validates it using the ContentBrief model before returning it.

def create_brief(topic:str, research_chunks: list[str], example: list[str], critique: list[str]) -> ContentBrief|None:
    cleaned_topic = clean_topic(topic)
    user_message = (
        f"TOPIC: {cleaned_topic}\n\n"
        "RESEARCH_CHUNKS:\n"
        + "\n---\n".join(research_chunks)
        + "\n\nEXAMPLES:\n"
        + "\n---\n".join(example)
        + "\n\nCRITIQUE_POINTS:\n"
        + "\n---\n".join(critique)
    )
    raw_response = call_llm(SYSTEM_PROMPT, user_message)
    refined_response = strip_json_fences(raw_response)
    try:
        parsed = json.loads(refined_response)
    except json.JSONDecodeError:
        print("LLM did not return valid JSON:")
        print(raw_response)
        return None
    try:
        return ContentBrief.model_validate(parsed)
    except ValidationError as e:
        print("LLM returned JSON but it doesn't match expected structure:")
        print(e)
        return None

At this point, our system can understand a topic, gather supporting research, find real-world examples, critically evaluate everything and structure all of it in a brief before handing it over to writing agents.

In the next article, we'll build the Hook Agent responsible for generating multiple hook directions from the structured brief before the full post is written.

Github Repo: https://github.com/Manav-N4/linkedin-agent#linkedin-agent

Building a Multi-Agent AI for Company LinkedIn Pages - Part 5: Building the Critic Agent

Manav — Fri, 31 Jul 2026 13:04:51 +0000

Our system can now classify the topic, do the research and back it with examples. Before handing everything over to the writing agents, we first need to identify weak assumptions, unsupported claims, and irrelevant examples.

That's why we built the Critic Agent.

One important thing to note is that the Critic Agent doesn't rewrite any part of the research chunks or examples. Nor does it invent new data points, it just points out what isn't right.

Research Agent
↓

Finds information

Examples Agent
↓

Finds supporting evidence

Critic
![ ](https://dev-to-uploads.s3.us-east-2.amazonaws.com/uploads/articles/lr2n5pih6uygoyyqiqep.png) Agent
↓

Finds weaknesses

Before we start writing code, let's write the system prompt. I want the agent to be harsh. Even if the research appears strong, I still want the agent to think like a skeptical reviewer and identify potential weaknesses. The mistakes shouldn't be more about writing style or grammar, it should focus on questioning accuracy of facts stated, relevance of examples, checking if the topic, research and examples are co-related to each other. Also reinforce the fact that it shouldn't make any changes to the research chunks or examples, but flag mistakes in them.

Unlike the Examples Agent, the Critic Agent takes topic, research chunks and examples as in the user message.

user_message = f"TOPIC: {cleaned_topic}\n\nRESEARCH_CHUNKS:\n" + "\n---\n".join(research_chunks)
user_message2 = f"{user_message}\n\nExamples:\n" + "\n---\n".join(example)

Sometimes LLMs don't return valid JSON. I've wrapped the call in a retry loop so the agent gets up to three attempts before failing.

Transient formatting issues are surprisingly common with LLMs, so retrying is often simpler than failing the entire pipeline.

for attempt in range(max_retries):

I wanted to make sure empty lists are rejected as the Critic Agent should atleast return one critique point. So, returning valid but empty critiques isn't useful.

if len(parsed) > 0:
   return parsed

Before writing the final code, let's breakdown what the function does. It takes topic, research chunks, examples and max retries ie 3 retries as input. The topic is cleaned followed by the user message which consists of topic, research chunks and examples.

Then we write rest of the code within the loop where we call the LLM to generate response and strip fences to make the JSON valid.

As always, we parse the JSON and make sure that it atleast returns 1 critique point in try and except blocks to handle exceptions.

def be_critique(topic:str, research_chunks: list[str], example: list[str], max_retries = 3) -> list[str]:
    cleaned_topic = clean_topic(topic)
    user_message = f"TOPIC: {cleaned_topic}\n\nRESEARCH_CHUNKS:\n" + "\n---\n".join(research_chunks)
    user_message2 = f"{user_message}\n\nExamples:\n" + "\n---\n".join(example)
    for attempt in range(max_retries):
        raw_response = call_llm(SYSTEM_PROMPT, user_message2)
        refined = strip_json_fences(raw_response)
        try:
            parsed = json.loads(refined)
            if len(parsed) > 0:
                return parsed
        except json.JSONDecodeError:
            print(f"Critic attempt {attempt + 1} failed, retrying...")
    return []

At this point, our system can understand a topic, gather supporting research, find real-world examples, and critically evaluate everything before any writing begins.

In the next article we'll build the Brief Agent to structure all the research chunks, examples and critique points in a proper way before handing it over to the writing agents.

Github Repo: https://github.com/Manav-N4/linkedin-agent#linkedin-agent

Building a Multi-Agent AI for Company LinkedIn Pages - Part 4: Building the Examples Agent

Manav — Thu, 30 Jul 2026 16:22:49 +0000

In the previous article, we built the Research Agent which can now gather relevant information, but raw facts still don't make compelling LinkedIn posts. Facts explain an idea. Examples make people remember it.

That's why we need the Examples Agent.

So, the Examples Agent takes the research chunks as input and returns exactly three examples. I chose to limit it to only 3 examples to give downstream agents enough variety without creating noise.

Instead of performing another web search, the Examples Agent works entirely from the research collected by the Research Agent. This keeps the pipeline grounded in the same context instead of introducing new information midway through the workflow.

Topic
      │
      ▼
Research Chunks
      │
      ▼
Read Context
      │
      ▼
Extract Examples
      │
      ▼
Generate Missing Examples
      │
      ▼
Return 3 Examples

Before we write any code, let's write the system prompt.

I wanted the Examples Agent to first look for existing examples within the research chunks before generating new ones.

Also instead of generic examples, it should look forward to using names of real companies and places and people. The example should clearly convey what exactly happened and why it's relevant to the post and make sure the output is a valid JSON that returns 3 examples.

SYSTEM_PROMPT = """
Find or generate 3 concrete examples
that support the topic.

Rules:
- Prefer examples from research.
- Only generate when necessary.
- Explain who, what happened,
  and why it's relevant.
- Return valid JSON.
"""

The production prompt is much longer, but I've shortened it here to highlight the core rules.

Let's breakdown function before writing the code. It should take topic and research chunks as input. Then clean the topic using clean_topic() function.

Rather than asking the LLM for examples with only the topic, we also pass the research chunks gathered in the previous step. This gives the model concrete context to work with and reduces unnecessary hallucinations.

user_message = f"TOPIC: {cleaned_topic}\n\nRESEARCH_CHUNKS:\n" + "\n---\n".join(research_chunks)

Let's pass system prompt and user_message to call_llm() function and as we built in Part 2, strip_json_fences() removes markdown code fences so the response can be parsed as valid JSON.

As a standard practice we would parse the JSON in a try and except block to handle exceptions.

try:
        parsed = json.loads(refined_response)
    except json.JSONDecodeError:
        print("LLM did not return valid JSON:")
        print(raw_response)
        return []

As you noticed, we are returning [], if the model returns malformed JSON, the agent gracefully returns an empty list instead of stopping the entire pipeline.

def get_examples(topic: str, research_chunks: list[str]) -> list[str]:
    cleaned_topic = clean_topic(topic)
    user_message = f"TOPIC: {cleaned_topic}\n\nRESEARCH_CHUNKS:\n" + "\n---\n".join(research_chunks)
    raw_response = call_llm(SYSTEM_PROMPT, user_message)
    refined_response = strip_json_fences(raw_response)
    print(f"REFINED: {repr(refined_response)}")
    try:
        parsed = json.loads(refined_response)
    except json.JSONDecodeError:
        print("LLM did not return valid JSON:")
        print(raw_response)
        return []
    return parsed

We now have the topic, supporting research, and real-world examples. But before we start writing, we should first evaluate whether our ideas are actually worth turning into a post.

In the next article, we'll build the Critic Agent that challenges our assumptions, identifies weak angles, and helps improve the quality of the content before a single draft is generated.

Building a Multi-Agent AI for Company LinkedIn Pages - Part 3: Building the Research Agent

Manav — Wed, 29 Jul 2026 14:06:07 +0000

In the previous article, we built an Orchestrator Agent that can consistently classify a topic and return structured output that every downstream agent can rely on.

But classification alone isn't enough. LLMs shouldn't be limited to only their training knowledge. Every other agent built later depends on the factual information collected by the Research Agent.

Before we write a single line of code, let's first understand what the Research Agent takes as input and what it returns as output.

The Research Agent takes topic as input and searches the web, filters the results and scrapes the webpages. It splits the scraped text into chunks and embeds those chunks as vectors and stores them in ChromaDB.

When the user searches for a topic, that topic is converted into an embedding. ChromaDB then compares this query vector with every stored chunk and returns the chunks whose vectors are closest in semantic meaning.

Topic
   │
   ▼
Search Web
   │
   ▼
Filter Results
   │
   ▼
Scrape Pages
   │
   ▼
Chunk Content
   │
   ▼
Generate Embeddings
   │
   ▼
Store in ChromaDB
   │
   ▼
Semantic Search
   │
   ▼
Relevant Context

I'll use Serper to query Google Search and retrieve the top organic results. For each result, I only keep the title and URL.

Make sure to read through Requests and read until Response Content and BeautifulSoup only the Quick Start section, before we start writing the code.

load_dotenv()

def search_web(query:str) -> list[dict]:
    url = "https://google.serper.dev/search"
    api_key = os.getenv("SERPER_API_KEY")
    headers = {
        "X-API-KEY": api_key,
        "Content-Type": "application/json"
    }

    body = {
        "q": query
    }       
    r = requests.post(url, headers=headers, json=body)
    r_json = r.json()
    results = r_json["organic"]
    return [{"title": result["title"], "link": result["link"]} for result in results]

While building this agent, I came across a concept called Retrieval-Augmented Generation (RAG).

Think of it like an open-book exam.

Normally, an LLM answers from memory. With RAG, it first opens the right pages of a book (or knowledge base), reads the relevant information, and then answers your question based on both its knowledge and what it just retrieved.

That's exactly what our Research Agent is doing. To make that retrieval reliable, we first need to decide which webpages are worth indexing.

I prefer to omit social media sites as most of these pages are difficult to scrape consistently or don't expose their primary content as plain HTML, so I excluded them from the first version.

So, the is_scrapeable() function ensures the URL doesn't contain any of the restricted domains defined in SKIP_DOMAINS

SKIP_DOMAINS = ["instagram.com", "facebook.com", "reddit.com", "youtube.com", "x.com"]

def is_scrapeable(url: str) -> bool:
    return not any(domain in url for domain in SKIP_DOMAINS)

Now that we know which page to scrape and which one to avoid, let's write the scrape_page() function which takes a URL, downloads the webpage, and uses BeautifulSoup to extract all the text inside paragraph tags. It returns this combined text.

def scrape_page(url:str) -> str:
    try:
        response = requests.get(url, timeout=10)
    except requests.exceptions.RequestException as e:
        print("Failed to fetch page:", e)
        return ""
    soup = BeautifulSoup(response.text, "html.parser")
    if response:
        paras = soup.find_all("p")          
        return " ".join([p.get_text() for p in paras])
    else:
        return ""

Once we are done scraping the sites, we don't embed the whole page, we break them down into chunks. A webpage usually contains multiple ideas. Embedding the entire page into a single vector dilutes its meaning. Chunking lets each embedding represent a smaller, more focused piece of information, making retrieval much more accurate.

chunks = [" ".join(words[i:i+200]) for i in range(0, len(words), 200)]

Now we have to write the embed_and_store() function that converts each chunk into a dense vector using SentenceTransformer. Then save the text chunks, vectors and a unique ID into the chromaDB collection.

Make sure to go through ChromaDB Embedding Functions and ChromaDB Clients only the Persistent Client section before writing any code.

model = SentenceTransformer("all-MiniLM-L6-v2")
client = chromadb.PersistentClient(path="data/chroma")
collection = client.get_or_create_collection("research")

def embed_and_store(text: str, url: str) -> None:
    words = text.split()
    chunks = [" ".join(words[i:i+200]) for i in range(0, len(words), 200)]
    embeddings = model.encode(chunks)
    collection.add(
        documents = chunks,
        embeddings = embeddings.tolist(),
        ids = [f"{url}_chunk_{i}" for i in range(len(chunks))]
    )

Now we write the query_search() function which converts the user's original topic into a vector. ChromaDB compares the query embedding against every stored embedding and returns the chunks with the highest semantic similarity.

def query_research(topic: str, n_results: int = 3) -> list[str]:
    query = model.encode([topic]).tolist() 
    if n_results > collection.count():
        n_results = min(n_results, collection.count()) 
    res = collection.query(query_embeddings=query, n_results=n_results)
    return res["documents"][0]

Finally, we write the main research_agent() function which ties everything together:

Searches Google for the topic.
Loops through the search results.
Checks if the link is scrapeable.
Scrapes the text from the webpage.
Embeds and stores the text in the database.
Stops scraping once it has successfully processed 3 pages to save time and resources.
Runs a search on the database it just built to return the text chunks most relevant to the original topic.

For this project, scraping three high-quality articles provided enough context while keeping latency and API usage low.

Google Search
       │
       ▼
 Page 1   Page 2   Page 3
      │      │      │
      ▼      ▼      ▼
   Scrape Text
      │
      ▼
 Chunk Text
      │
      ▼
 Generate Embeddings
      │
      ▼
 Store in ChromaDB
      │
      ▼
 User Query
      │
      ▼
 Semantic Search
      │
      ▼
 Top 3 Chunks

This is the retrieval stage of our RAG pipeline. Instead of just searching Google, the agent reads the top articles, splits them into semantic chunks, stores them in a searchable vector database, and returns only the passages most relevant to the user's query.

def research_agent(topic: str) -> list[str]:
    results = search_web(topic)
    pages_scraped = 0
    for result in results:
        if is_scrapeable(result["link"]):
            text = scrape_page(result["link"])
            if text:
                embed_and_store(text, result["link"])
                pages_scraped += 1
                if pages_scraped == 3:
                    break
    return query_research(topic)

The Research Agent can now gather relevant information, but raw facts still don't make compelling LinkedIn posts.

In the next article, I'll build the Examples Agent that finds real-world examples to support the research.

Github Repo: https://github.com/Manav-N4/linkedin-agent#linkedin-agent

Building a Multi-Agent AI for Company LinkedIn Pages — Part 2: Building the Orchestrator Agent

Manav — Tue, 28 Jul 2026 12:16:14 +0000

In the previous article, I broke down the problem into independent responsibilities instead of expecting one agent to do everything.

If every agent is independent of eachother, how do they communicate with eachother? Who decides what runs next?

That's where the Orchestrator Agent acts like a traffic controller, managing how agents pass context to eachother and maintaining order in which they run.

linkedin-agent/
├── agents/
│   ├── orchestrator.py     
│   ├── research.py          
│   ├── examples.py          
│   ├── critic.py            
│   ├── brief.py             
│   ├── hook.py              
│   ├── draft.py             
│   └── writing_critic.py    
├── core/
│   ├── llm.py               
│   ├── models.py            
│   └── utils.py            
├── data/
│   └── chroma/
├── main.py                 
├── api.py                   
├── requirements.txt        
└── .env

Each agent has it's own file. The core folder has:

llm.py wraps all interactions with Ollama through a single call_llm() function.
models.py stores shared Pydantic schemas used across agents.
utils.py has function clean_topic() to remove extra spaces from topic user has entered.
main.py runs the agent pipeline and api.py has the fastAPI server.

The Orchestrator Agent has one job: understand the topic, classify it, decide the best content angle, and return structured output for the Research Agent.

For every llm call we are making we need a SYSYTEM_PROMPT ie the prompt we write to define how the agent has to work and a user_message which has all context from previous agents.

So, lets start by writing a SYSTEM_PROMPT for the Orchestrator Agent.

SYSTEM_PROMPT = """
You are the orchestrator agent for WanderMesh.

Your job is to analyze a topic and return:

- domain
- content_type
- angle
- reasoning

Rules:
- Return only valid JSON.
- Choose one domain from a predefined list.
- Choose one content type.
- Choose one content angle.
- Explain your reasoning briefly.
"""

I've shortened the prompt for readability. The production version also includes domain-specific categories, output constraints, and a few-shot example to improve classification consistency.

Rather than asking the model an open-ended question, I constrained its output to a fixed structure. That made the downstream pipeline far more predictable.

One issue I ran into early was that the model didn't always return valid JSON. Sometimes it wrapped the response in markdown code fences, sometimes it produced trailing commas, and occasionally it returned smart quotes instead of standard JSON quotes.

Since every downstream agent expected valid JSON, I needed a preprocessing step before parsing the response.

While testing with smaller local models like gemma2:2b, I found they occasionally ignored formatting instructions and returned malformed JSON despite being explicitly asked for valid JSON.

To help fix the JSON format I wrote the strip_json_fences() function.

If you're still getting comfortable with Python, I highly recommend CS50 Python. I learned a lot by reading the notes first and then implementing everything myself.

def strip_json_fences(raw:str) -> str:
    raw = raw.strip()
    if raw.startswith("```

json"):
        raw = raw.removeprefix("

```json").strip()
    elif raw.startswith("```

"):
        raw = raw.removeprefix("

```").strip()
    if raw.endswith("```

"):
        raw = raw.removesuffix("

```").strip()
    raw = re.sub(r',\s*]', ']', raw)
    raw = re.sub(r',\s*}', '}', raw)
    raw = raw.replace('\u201c', '\\"').replace('\u201d', '\\"')
    raw = raw.replace('\u2018', "'").replace('\u2019', "'")
    return raw

Even valid JSON isn't enough. The model might forget a field, rename one, or return an unexpected structure. Before handing the output to the next agent, I wanted to validate that it matched exactly what the pipeline expected.

Further reading: If you're new to Pydantic, the official documentation on Models and Fields is an excellent place to understand the validation features used here.

Now lets create a Pydantic Object for the Orchestrator Agent. For now, I'm only validating the structure, not restricting the possible values. That keeps the orchestrator flexible while the rest of the pipeline is still evolving.

class OrchestratorOutput(BaseModel):
    domain: str
    angle: str
    reasoning: str
    content_type: str

Now lets write the main function for classifying topic. Before writing the code lets fundamentally breakdown what this function should do.

Topic
   │
   ▼
clean_topic()
   │
   ▼
call_llm()
   │
   ▼
strip_json_fences()
   │
   ▼
json.loads()
   │
   ▼
Pydantic Validation
   │
   ▼
OrchestratorOutput

It should take topic as input and return Pydantic Object as output for Research Agent to use.

The topic should first be cleaned using the clean_topic(), removing extra spaces if any and checking if the user hasn't entered an empty string.

Then we pass the cleaned topic and SYSTEM_PROMPT to the call_llm() function and then remove json fences from it using strip_json_fences() function to return valid JSON.

Finally, the JSON is parsed and validated. If anything goes wrong, the function returns None instead of passing invalid data further down the pipeline.

As a standard practice we parse JSON and validate the parsed JSON in try and except blocks to handle Errors if something breaks.

def classify_topic(topic:str) -> OrchestratorOutput|None:
    cleaned_topic = clean_topic(topic)
    raw_response = call_llm(SYSTEM_PROMPT, cleaned_topic)
    refined_response = strip_json_fences(raw_response)
    try:
        parsed = json.loads(refined_response)
    except json.JSONDecodeError:
        print("LLM did not return valid JSON:")
        print(raw_response)
        return None
    try:
        return OrchestratorOutput.model_validate(parsed)
    except ValidationError as e:
        print("LLM returned JSON but it doesn't match expected structure:")
        print(e)
        return None

At this point, the orchestrator can consistently classify a topic and return structured output that every downstream agent can rely on.

In the next article, I'll build the Research Agent, the component responsible for gathering factual information before any content is generated.

Github Repo: https://github.com/Manav-N4/linkedin-agent#linkedin-agent

Building a Multi-Agent AI for Company LinkedIn Pages — Part 1: Breaking Down the Problem

Manav — Mon, 27 Jul 2026 11:34:16 +0000

As someone who posts on LinkedIn everyday, I've a fair idea on how it's to post on LinkedIn, what works and what doesn't. Recently, I started managing a company's LinkedIn page and quickly realized that it was a completely different problem.

I used the same writing style as the one on my personal LinkedIn. It didn't work well as people don't relate top company pages the way they do with personal accounts. Company pages have to sound consistent. Every post represents a brand, they need supporting evidence and has to fit a positioning rather than a personal opinion.

If one were to use chatGPT or Claude for the job, it alone had to do all the work, from research to generating hooks, drafts, maintaining the brand voice and would require constant iteration prompts to get the desired result.

So, before writing a single line of code or setting up the project, I fundamentally broke down the problem.

I need to take the topic from the user as input, then the agent needs to do the research, back the research with examples and then create a brief using which it can generate a few hook variations and post drafts, which the user can choose from, where the agent scores the drafts to help user choose the draft from given options.

But what if the user didn't like the output? That's when I thought that I need to reduce the probability of the user not liking the post.

At this point all of this was too much for one agent.

That's when I thought of building a multi-agent system, where each agent would pick up a task. This makes the pipeline easy to debug and helps me maintain separate code for each agent.

Another architectural decision was separating validation from generation. Instead of immediately moving from research to writing, I added a validation stage that could identify weak reasoning or inconsistencies before the writing process even began. The generated drafts would then go through another evaluation step, where they were scored before being presented to the user.

Throughout the building of this multi-agent LinkedIn system we would be using Python and its libraries like PyTorch and Pydantic for writing the agents, wiring them, fine tuning the models and validating output.

The project also uses RAG with ChromaDB so the system works with relevant retrieved context instead of relying entirely on the model's internal knowledge.

Currently I've built the agent pipeline, fastAPI backend.

At the time of writing this, I'm working on the Streamlit interface before moving toward deployment, reliability improvements and eventually making the system work for multiple brands.

In the next article, I'll break down the orchestrator, the component responsible for deciding how every other agent in the system works together.

Github Repo: https://github.com/Manav-N4/linkedin-agent#linkedin-agent