MakersLounge - Find Your People

Overview

The Matcher Agent is an AI-powered system that intelligently groups contacts for networking events. It uses Claude (via the Anthropic API) in an agentic loop — meaning the AI can call tools, analyze results, and iterate until it produces optimal groups.

Key insight: Unlike a simple prompt→response flow, the agent makes multiple turns, using tools to explore data, propose solutions, verify results, and self-correct if needed.

How It Works

The agent follows a structured workflow:

Explore Data

Agent calls get_all_contacts to see all attendees with their skills, needs, and interests.

Analyze Patterns

Optionally searches for specific skills or needs using search_contacts.

Propose Groups

Creates groups with themes, reasoning, and specific member connections using propose_groups.

Verify

Calls verify_groups to check that everyone is placed exactly once.

Submit or Fix

If valid, submits final groups. If issues found, the agent self-corrects and re-proposes.

Available Tools

The agent has access to 6 tools that it can call during execution:

Tool	Purpose
`get_all_contacts`	Retrieves all contacts with their data (names, skills, needs, etc.)
`search_contacts`	Searches contacts by field value (e.g., find all designers)
`get_contact_by_name`	Gets full details for a specific contact
`propose_groups`	Submits proposed grouping with members, themes, and connections
`verify_groups`	Validates that all contacts are placed exactly once
`submit_final_groups`	Finalizes and returns the verified groups

Matching Logic

The agent follows these principles when creating groups:

Skill-Need Matching: Pairs people who HAVE skills with those who NEED them
Diversity: Creates groups with complementary perspectives
Even Distribution: Distributes people evenly across requested groups
Connection Mapping: Identifies 5-8 specific connections per group (who should talk to whom)
Theme Generation: Creates a short theme for each group

Group Output Structure

Each group returned by the agent contains:

{
  "members": ["Alice Chen", "Bob Smith", "Carol Davis"],
  "theme": "AI Product Builders",
  "reason": "This group combines AI expertise with product
    experience. Alice's ML background complements Bob's
    product skills, while Carol brings design thinking.",
  "connections": [
    {
      "from": "Alice Chen",
      "to": "Bob Smith",
      "reason": "Alice can help Bob with ML integration",
      "strength": 3
    },
    {
      "from": "Bob Smith",
      "to": "Carol Davis",
      "reason": "Bob needs design feedback on his product",
      "strength": 2
    }
    // ... more connections
  ]
}

Connection Strength

Strength 3: Strong match — highly complementary skills/needs
Strength 2: Moderate match — useful conversation potential
Strength 1: Light match — possible shared interests

Real-Time Streaming

The agent uses Server-Sent Events (SSE) to stream progress in real-time:

step — Phase changes (exploring, analyzing, proposing, etc.)
thinking — Agent's reasoning as it works
tool_call — When a tool is invoked
tool_result — Result of tool execution
group — A completed group
tokens — Token usage updates
complete — Final results

Rate Limit Handling

The agent includes automatic retry logic with exponential backoff:

Up to 3 retry attempts on rate limit errors
Base delay of 5 seconds, doubling each retry (5s → 10s → 20s)
User is notified of retries via streaming events
1 second delay between turns to avoid hitting limits

API Reference

Endpoint

POST /api/agents/matcher

Request Body

{
  "contacts": [
    { "name": "Alice", "skills": "ML, Python", "needs": "Design help" },
    { "name": "Bob", "skills": "Product", "needs": "Technical cofounder" }
    // ... more contacts
  ],
  "groupSize": 4,    // Number of groups to create
  "stream": true     // Enable SSE streaming (default: true)
}

Response (Non-streaming)

{
  "groups": [
    {
      "members": ["Alice", "Bob", "Carol"],
      "theme": "AI Product Team",
      "reason": "Complementary skills for building AI products",
      "connections": [...]
    }
    // ... more groups
  ]
}

Configuration

Max Duration: 180 seconds (3 minutes)
Max Turns: 20 agentic turns
Model: claude-sonnet-4-20250514
Max Tokens: 4096 per turn

Best Practices

Include skills and needs fields in your contact data for best results
Use descriptive text in contact fields (not just keywords)
Request fewer groups for better connection density
Minimum 2 contacts required, works best with 8-50 contacts

Matcher Agent Architecture