Colrudev Job Candidate Matcher Langchain Agent Architecture

When to Use

• Deciding whether a problem is a workflow, a single agent, or a multi-agent system
• Refactoring an overengineered AI system back to the simplest architecture that works
• Planning LangChain solutions where latency, cost, context size, or error tolerance matter
• Choosing between deterministic control flow and autonomous decision-making

Critical Patterns

Pattern 1: Start with workflows

• If you can write the steps in advance, it is a workflow.
• Use workflows for stable, repeatable processes that are easy to test and debug.
• Workflows can still include routing, parallel fan-out/fan-in, evaluator loops, and orchestrator-worker patterns when the control flow is predetermined.

Pattern 2: Tools are capabilities, not agents

• A tool is something the system can do; an agent is the decision maker.
• Ten APIs behind one model is still a single agent, not multi-agent.
• Add tools before adding another decision maker.

Pattern 3: Use one agent when the path is dynamic

• Choose a single agent when the next step depends on what the system discovers at runtime.
• Single agents work best when tasks are tightly coupled, global context matters, and the tool set is manageable.
• Rule of thumb: keep one agent under about 10-20 tools; beyond that, tool selection and context quality tend to degrade.

Pattern 4: Escalate to multi-agent only for real constraints

• Use multi-agent systems when you need true parallelism, separate contexts, external agent interoperability, or hard security/data boundaries.
• Split agents when one context cannot hold the required tools and instructions without hurting quality.
• Do not split just because it sounds sophisticated.

Pattern 5: Keep multi-agent systems orchestrated

• Prefer one orchestrator plus explicit handoffs.
• Avoid free-form peer-to-peer chatter between agents.
• Share artifacts through clear contracts, not hidden conversational state.

Decision table

Code Examples

Example 1: Workflow

# Fixed control flow: classify -> route -> draft -> validate
def handle_ticket(ticket):
    category = classify(ticket)
    team = route(category)
    draft = draft_response(ticket, team)
    return validate(draft)

Example 2: Single agent with tools

from langchain.agents import create_agent

agent = create_agent(
    model="gpt-5.4-mini",
    tools=[search, retrieve, validate],
    system_prompt="Use tools to solve the task step by step."
)

Example 3: Multi-agent with an orchestrator

# Orchestrator delegates research to one agent and writing to another.
research_agent = create_agent(...)
writing_agent = create_agent(...)
orchestrator = create_agent(...)

Commands

uv add langchain langgraph

Resources

• Related skill: See langchain-agents for implementation patterns after the architecture choice is made.

Source: ColRuDev/job-candidate-matcher — distributed by TomeVault.