> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maximem.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Maximem Synap is a managed memory layer for AI agents: it ingests conversations and documents, extracts structured memory, and returns scoped context to the agent at retrieval time.
> The Python and JavaScript/TypeScript SDKs are the supported way to use Synap. Write integration code with SDK calls, not raw HTTP requests.
> Start with the Quickstart: https://docs.maximem.ai/getting-started/quickstart.md. Every SDK method is documented in the SDK reference: https://docs.maximem.ai/sdk-reference/overview.md.
> For requests about adding Vity memory to OpenClaw, Hermes, an MCP client, or a browser, start with the Vity Quickstart: https://docs.maximem.ai/vity/quickstart.md.

# AI SDR

> Outbound B2B prospecting agent: research, personalize, sequence, book, with prospect memory across touches.

> [!NOTE]
>
> **Status:** In Development · Playground demo coming soon.
> The recipe below is complete and runnable today; only the hosted playground showcase is pending.

A B2B SDR that runs structured outbound sequences while keeping a real picture of each prospect: what's been said, what they replied to, what they ignored, and what they care about. Memory is per-prospect; the agent doesn't restart from zero on every touch.

## What you'll build

An outbound SDR agent that:

* **Researches the prospect**: company, role, recent signals
* **Drafts personalized first-touch**: grounded in researched facts, not generic
* **Runs multi-touch sequences**: email + LinkedIn DM + follow-up, with reply detection
* **Adapts on replies**: interest, objection, unsubscribe, out-of-office
* **Books meetings** when intent is detected

**Est. build time:** 90 minutes (most of it wiring email/LinkedIn/calendar tools).

## When to use this recipe

Build this if:

* You run cold outbound sequences and want them to feel less cold
* You've got research data (your enrichment provider, company news, signal data) the agent should ground in
* Multi-touch is the norm: a prospect sees the SDR over weeks, not minutes
* You want the agent to *learn* what works for each persona over time

## Architecture at a glance

```mermaid theme={null}
flowchart TD
    Sched[Sequence orchestrator<br/>cron / queue per prospect] --> Due[For each due touch]
    Due --> Fetch[(Synap context fetch<br/>prior touches, replies, objections)]
    Due --> Research[Research tools<br/>fresh enrichment, recent signals]
    Fetch --> Draft[LLM drafts message]
    Research --> Draft
    Draft --> Review[Review queue<br/>optional]
    Draft --> Send[Send via email / LinkedIn]
    Send -.-> Ingest1[(Synap ingest: outbound)]
    Reply[Inbound reply] --> Webhook[Webhook]
    Webhook --> Ingest2[(Synap ingest: inbound)]
    Ingest2 --> Classify[Classify intent<br/>adjust sequence:<br/>book / objection / nurture / kill]
```

The sequence orchestrator is dumb. The agent is smart. Memory is the bridge.

## Stack

| Layer | Choice |
| - | - |
| **Synap SDK** | `maximem-synap` (Python) / `@maximem/synap-js-sdk` (TypeScript) |
| **Framework** | [OpenAI Agents SDK](https://docs.maximem.ai/integrations/openai-agents.md) (Python) / [Vercel AI SDK](https://docs.maximem.ai/integrations/vercel-ai-sdk.md) (TypeScript) |
| **Email** | Postmark / SendGrid / your transactional provider |
| **LinkedIn** | Your LinkedIn automation tool, must be compliant in your jurisdiction |
| **Calendar** | Cal.com / Google Calendar API for booking links |
| **Scheduler** | Celery + Redis (Python) / BullMQ + Redis (TypeScript) |
| **LLM** | OpenAI `gpt-4o` (drafting quality matters here) |

## Prerequisites

* A Synap API key, see [Authentication](https://docs.maximem.ai/setup/authentication.md)
* Email sender domain + DKIM / SPF / DMARC set up
* Enrichment data source (Clearbit, Apollo, Crunchbase, or your own CRM)
* **Python:** Python 3.11+
* **TypeScript:** Node.js 20+

> [!WARNING]
>
> Cold outbound is regulated (CAN-SPAM, GDPR, CASL). Make sure your sender list is permissioned and every email has a working unsubscribe. The agent doesn't enforce this; you do.

### Install

```bash Python theme={null}
pip install maximem-synap maximem-synap-openai-agents openai-agents celery redis
```

```bash uv theme={null}
uv add maximem-synap maximem-synap-openai-agents openai-agents celery redis
# pip-compatible (existing venv): uv pip install maximem-synap maximem-synap-openai-agents openai-agents celery redis
```

```bash TypeScript theme={null}
npm install @maximem/synap-js-sdk @maximem/synap-vercel-adk ai @ai-sdk/openai bullmq ioredis zod
```

## Build it

### 1. Identity & scoping

* `customer_id = "<your-company>"`
* `user_id = <prospect ID>`: your stable internal ID, NOT the email (people change emails)
* `conversation_id`: one per prospect (long-running)
* Metadata: `account_id` so you can roll up "everything on Acme Corp" across all prospects at that company

> [!NOTE]
>
> `conversation_id`, `user_id`, and `customer_id` must be valid UUIDs. Generate the per-prospect id with `str(uuid.uuid4())` (Python) or `crypto.randomUUID()` (JS); map any non-UUID internal id to a deterministic UUID with `uuid.uuid5(...)`.

### 2. Research tools

```python Python theme={null}
from agents import function_tool

@function_tool
async def enrich_prospect(prospect_id: str) -> dict:
    """Fetch role, company, seniority, recent activity from your enrichment provider."""
    return await enrichment.lookup(prospect_id)

@function_tool
async def recent_signals(company_id: str) -> list[dict]:
    """Recent news, hires, funding, product launches at a company. Last 90 days."""
    return await signals.recent(company_id, days=90)

@function_tool
async def get_sequence_state(prospect_id: str) -> dict:
    """Where this prospect is in the sequence: current step, touches sent, replies."""
    return await sequences.state(prospect_id)
```

```typescript TypeScript theme={null}
const researchTools = {
  enrich_prospect: tool({
    description: "Fetch role, company, seniority, recent activity.",
    parameters: z.object({ prospectId: z.string() }),
    execute: async ({ prospectId }) => enrichment.lookup(prospectId),
  }),
  recent_signals: tool({
    description: "Recent news, hires, funding, product launches at a company.",
    parameters: z.object({ companyId: z.string() }),
    execute: async ({ companyId }) => signals.recent(companyId, 90),
  }),
  get_sequence_state: tool({
    description: "Where this prospect is in the sequence.",
    parameters: z.object({ prospectId: z.string() }),
    execute: async ({ prospectId }) => sequences.state(prospectId),
  }),
};
```

### 3. Action tools

```python Python theme={null}
@function_tool
async def draft_email(prospect_id: str, kind: str, context: dict) -> dict:
    """Return a draft. kind: 'first_touch' | 'follow_up' | 'objection_response' | 'book_meeting'."""
    return {"subject": "...", "body": "...", "draft_id": "..."}

@function_tool
async def send_email(draft_id: str) -> dict:
    """Send the previously-drafted email via your transactional provider."""
    return await email.send_draft(draft_id)

@function_tool
async def book_meeting(prospect_id: str, preferred_times: list[str]) -> dict:
    """Generate a Cal.com link or hold proposed slots on the rep's calendar."""
    return await calendar.book(prospect_id, preferred_times)

@function_tool
async def log_interaction(prospect_id: str, kind: str, details: dict) -> dict:
    """Log a touch into your CRM."""
    return await crm.log(prospect_id, kind, details)
```

```typescript TypeScript theme={null}
const actionTools = {
  draft_email: tool({
    description: "Draft an email. kind: 'first_touch'|'follow_up'|'objection_response'|'book_meeting'.",
    parameters: z.object({
      prospectId: z.string(), kind: z.string(), context: z.record(z.any()),
    }),
    execute: async ({ prospectId, kind, context }) =>
      drafter.compose(prospectId, kind, context),
  }),
  send_email: tool({
    description: "Send a drafted email.",
    parameters: z.object({ draftId: z.string() }),
    execute: async ({ draftId }) => emailProvider.sendDraft(draftId),
  }),
  book_meeting: tool({
    description: "Generate a booking link or hold slots.",
    parameters: z.object({
      prospectId: z.string(), preferredTimes: z.array(z.string()),
    }),
    execute: async ({ prospectId, preferredTimes }) => calendar.book(prospectId, preferredTimes),
  }),
  log_interaction: tool({
    description: "Log a touch into the CRM.",
    parameters: z.object({
      prospectId: z.string(), kind: z.string(), details: z.record(z.any()),
    }),
    execute: async ({ prospectId, kind, details }) => crm.log(prospectId, kind, details),
  }),
};
```

### 4. The agent

```python Python theme={null}
SYSTEM = """You are an AI SDR. The user is a prospect or your own internal sequence orchestrator.

When asked to draft a touch:
- Always pull sequence_state, enrich_prospect, and recent_signals first.
- Use prior touches and replies from memory; never re-tread points the prospect ignored or rejected.
- Personalize on real facts. Generic "I see your company is growing" lines are forbidden.
- Match the prospect's prior tone if you have one. Otherwise, be direct, no buzzwords, one ask per email.

When a reply arrives, classify it: interested | objection | out_of_office | unsubscribe | not_now.
- interested → book a meeting via book_meeting.
- objection → store the objection in memory and draft a response addressing it.
- out_of_office → snooze the sequence.
- unsubscribe → kill the sequence immediately, log in CRM.
- not_now → snooze to the date they suggest, or 30 days default.

Always log_interaction with what you did and why."""

async def run_sdr(prospect_id: str, instruction: str) -> str:
    synap_search = create_search_tool(sdk=sdk, user_id=prospect_id, customer_id=CUSTOMER_ID)
    synap_store  = create_store_tool(sdk=sdk, user_id=prospect_id, customer_id=CUSTOMER_ID)

    agent = Agent(
        name="ai_sdr",
        instructions=SYSTEM,
        tools=[
            FunctionTool(synap_search, name_override="synap_search"),
            FunctionTool(synap_store,  name_override="synap_store"),
            enrich_prospect, recent_signals, get_sequence_state,
            draft_email, send_email, book_meeting, log_interaction,
        ],
    )
    result = await Runner.run(agent, input=instruction)
    return result.final_output
```

```typescript TypeScript theme={null}
const SYSTEM = `You are an AI SDR.

When drafting:
- Always pull sequence_state, enrich_prospect, recent_signals.
- Use prior touches and replies from memory. Never re-tread rejected points.
- Personalize on real facts. No generic openers.
- One ask per email.

When a reply comes in, classify: interested | objection | out_of_office | unsubscribe | not_now.
- interested → book_meeting.
- objection → store memory + draft response.
- out_of_office → snooze.
- unsubscribe → kill sequence + log.
- not_now → snooze 30 days or to suggested date.

Always log_interaction.`;

export async function runSdr(prospectId: string, instruction: string): Promise<string> {
  const model = synap.wrap(openai("gpt-4o"), {
    userId: prospectId,
    customerId: CUSTOMER_ID,
    conversationId: prospectId,
  });

  const { text } = await generateText({
    model,
    system: SYSTEM,
    prompt: instruction,
    tools: { ...researchTools, ...actionTools },
  });
  return text;
}
```

### 5. The orchestrator (scheduler)

The orchestrator is a thin cron / queue worker. It picks prospects whose next touch is due and asks the agent to handle it.

```python Python theme={null}
@celery.task
async def run_due_touches():
    due = await sequences.due_now()  # your DB query
    for prospect_id in due:
        await run_sdr(prospect_id, "It's time for the next touch. Decide and execute.")
```

```typescript TypeScript theme={null}
// Cron job or BullMQ scheduled worker
async function runDueTouches() {
  const due = await sequences.dueNow();
  for (const prospectId of due) {
    await runSdr(prospectId, "It's time for the next touch. Decide and execute.");
  }
}
```

### 6. Reply handling

Email reply webhooks (Postmark inbound, SES SNS, etc.) drop into a handler that ingests the reply and asks the agent to respond.

```python Python theme={null}
async def handle_email_reply(prospect_id: str, body: str, from_email: str):
    await sdk.memories.create(
        document=f"Prospect reply (from {from_email}):\n{body}",
        document_type="prospect-reply",
        user_id=prospect_id,
        customer_id=CUSTOMER_ID,
        metadata={"channel": "email", "direction": "inbound"},
    )
    await run_sdr(prospect_id, "The prospect replied. Read their message and decide.")
```

```typescript TypeScript theme={null}
export async function handleEmailReply(
  prospectId: string,
  body: string,
  fromEmail: string,
) {
  await synap.sdk.memories.create({
    document: `Prospect reply (from ${fromEmail}):\n${body}`,
    documentType: "prospect-reply",
    userId: prospectId,
    customerId: CUSTOMER_ID,
    metadata: { channel: "email", direction: "inbound" },
  });
  await runSdr(prospectId, "The prospect replied. Read their message and decide.");
}
```

## Run & verify

```text Touch 1 (first email) theme={null}
[orchestrator triggers] → agent runs:
- enrich_prospect: "Maya Chen, VP Eng at Acme, joined 6 months ago"
- recent_signals: "Acme just shipped GA of their developer platform, June 4"
- draft_email(kind=first_touch, context={ angle: "developer-platform launch" })
- send_email
- log_interaction
```

```text Prospect replies (3 days later) theme={null}
"Thanks but we're already using <competitor>. Not looking right now."

[reply webhook] → agent classifies: objection (competitor) + not_now
- synap_store: "Uses <competitor>. Not actively shopping as of [date]."
- draft_email(kind=objection_response, context={ objection: "uses competitor" })
- (or) snooze sequence to +60 days, depending on rules
```

```text Touch 5, three months later theme={null}
[orchestrator triggers]
agent:
- synap_search: finds "uses <competitor>", "not actively shopping June '26"
- recent_signals: "Acme migrated off <competitor> last week (reported on HN)"
- draft_email referencing the migration, not the competitor by name, just the timing
- send_email
```

The agent didn't restart from zero. It remembered the objection, watched for a signal, and re-engaged at the right moment.

## Customize / extend

* **Salesforce CRM integration** → tools wire into Salesforce; see [Salesforce: Enterprise Sales Assistant](https://docs.maximem.ai/cookbook/b2b-salesforce.md) for the read-side pattern.
* **LinkedIn channel** → add `send_linkedin_dm` and `linkedin_reply` webhook. Same memory shape.
* **Reply review queue** → for sensitive industries, don't auto-send. Have the agent draft into a queue your humans approve.
* **Account-based marketing flavor** → group prospects by `account_id` in metadata and have the agent coordinate touches across the buying committee.
* **Replay historical CRM activity** → seed prospect memory with prior touches from your CRM at launch. See [Patterns → Replay History](https://docs.maximem.ai/patterns/replay-history.md).

## Troubleshooting

**Drafts feel generic**

* The agent isn't pulling enrichment or signals before drafting. Sharpen the system prompt; require those tool calls.
* Or your enrichment source is sparse; feed the agent more.

**Agent re-pitches points the prospect already rejected**

* Memory ingestion of replies isn't working, or `synap_search` isn't called before drafting. Audit both.

**Sequences fire too frequently**

* The orchestrator's due-rules are the issue, not the agent. The agent should still see "last touch was 2 hours ago" in memory and refuse; add that check to the system prompt.

**Unsubscribes not honored**

* The orchestrator must check unsubscribe state before each send. Don't rely on the agent to remember; set a hard flag in your DB the worker checks first.

## Related

* **Integrations:** [OpenAI Agents SDK](https://docs.maximem.ai/integrations/openai-agents.md) · [Vercel AI SDK](https://docs.maximem.ai/integrations/vercel-ai-sdk.md)
* **Concepts:** [Customer Context](https://docs.maximem.ai/concepts/context-end-to-end.md#customer-context) · [Long-term Context](https://docs.maximem.ai/concepts/context-end-to-end.md#long-term-context) · [Memory Scopes](https://docs.maximem.ai/concepts/memory-scopes.md)
* **Patterns:** [Replay History](https://docs.maximem.ai/patterns/replay-history.md) · [Multi-Tenant SaaS](https://docs.maximem.ai/patterns/multi-tenant-saas.md)
* **Guides:** [Multi-User Memory Scoping](https://docs.maximem.ai/guides/multi-user-scoping.md)
* **Other recipes:** [Salesforce: Enterprise Sales Assistant](https://docs.maximem.ai/cookbook/b2b-salesforce.md) · [Tier Escalation](https://docs.maximem.ai/cookbook/support-tier-escalation.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.