Welcome to the Agentic Workflows repository. This is an enterprise-grade, AI-driven business operation system designed to eliminate manual labor from lead generation, sales outreach, and client operations.
This manual is designed to take an absolute beginner and turn them into a proficient automation engineer capable of managing, extending, and scaling this system.
- Core Philosophy: The Power of Agents
- The 3-Layer Architecture (High-Level View)
- The 3-Layer Architecture (Technical Deep-Dive)
- Getting Started: Beginner's Fast-Track
- The Execution Catalog (Complete Reference for 25+ Scripts)
- Detailed Workflow Visualizations
- Advanced Configuration Guides
- Prompt Engineering for Directives
- The Self-Annealing & Healing Process
- Massive Troubleshooting & Technical FAQ
- Learning Path: From Zero to Automation Engineer
- Security & Best Practices
- Future Roadmap
In traditional automation (like Zapier), you are the architect of every single step. In Agentic Workflows, you are the Orchestrator.
An Agent is a system that can:
- Reason: Understand complex instructions.
- Plan: Break down a goal into smaller steps.
- Act: Call external tools (scripts) to interact with the world.
- Refine: Look at the result of an action and try again if it failed.
This is the foundation of everything we do. It ensures that the system is deterministic, reliable, and easy to maintain.
graph TD
User([User Intent]) --> L1[<b>Layer 1: Directives</b><br/>Markdown SOPs in /directives]
L1 --> L2[<b>Layer 2: Orchestration</b><br/>AI Agent Decision Making]
L2 --> L3[<b>Layer 3: Execution</b><br/>Python Scripts in /execution]
L3 --> Out([Deliverables: Google Sheets, Proposals, Videos])
subgraph "The Feedback Loop"
L3 -- Error/Log --> L2
L2 -- Learning --> L1
end
Directives are the "Brain" of the system. They are written in Markdown to be easily readable by both humans and LLMs.
- Directives as Context: When you ask the AI to do something, it "reads" the relevant
.mdfile to understand the rules. - Why Markdown?: It allows for structure (headers, lists) that LLMs process better than plain text.
This is you (or the AI). The Orchestrator's job is to:
- Parse: Understand the user's intent.
- Plan: Choose the right
directivesandexecutiontools. - Execute: Run the Python scripts.
- Handle Errors: If a script returns a
429 Too Many Requests, the Orchestrator implements a sleep/retry strategy.
These are pure, deterministic Python scripts.
- Rule: No complex AI logic should live inside a script if it can be handled by a function.
- Rule: Scripts must output structured data (JSON) to
.tmp/.
Python programs need a "clean room" to run in. This is called a Virtual Environment (venv).
# 1. Activate your clean room
source venv/bin/activate
# 2. Install all the necessary tools
pip install -r requirements.txtThe AI needs permission to talk to other services.
- Create your .env:
cp .env.example .env - Fill in the keys: You will need an Apify Token, Anthropic Key, and Google Service Account JSON.
scrape_apify.py:- Purpose: The primary tool for finding businesses.
- Input: Industry name, Location, Max Items.
- Under the Hood: Connects to the
code_crafter/leads-finderactor on Apify.
scrape_apify_parallel.py:- Purpose: For large-scale scrapes (1,000+ leads).
- Logic: Splits the search into 4 geographic regions to bypass scraping limits.
gmaps_lead_pipeline.py:- Purpose: Deeply researches leads found on Google Maps.
- Feature: Visits each website and extracts the owner's name using AI.
scrape_google_maps.py: High-speed, raw extraction from Google Places.
upwork_apify_scraper.py: Searches Upwork for specific job keywords.upwork_proposal_generator.py:- Logic: Uses Claude 4.5 to read a job description and write a custom proposal.
- Feature: Creates a personalized Google Doc and a short cover letter.
instantly_autoreply.py:- Trigger: Incoming email reply.
- Logic: Researches the prospect's company and drafts a human-like response.
update_sheet.py:- Purpose: Batch-uploads any JSON data to a Google Sheet.
- Safety: Automatically handles rate limiting from Google.
casualize_batch.py: The "Humanizer."casualize_first_names_batch.py: Fixes capitalization (e.g., "JOHN" -> "John").casualize_company_names_batch.py: Removes "LLC", "INC", and "LIMITED" to make outreach feel natural.casualize_city_names_batch.py: Standardizes location names.
jump_cut_vad_singlepass.py:- Logic: Uses Neural Voice Activity Detection (VAD) to find silences.
- Feature: Supports "Cut-Cut" restart detection to remove recording mistakes.
insert_3d_transition.py: Adds professional video transitions between segments.
orchestrator.py: The master command-line tool to run any of the above.modal_webhook.py: Deploys these scripts to the cloud so they can be triggered by external events.
sequenceDiagram
participant U as You
participant O as Orchestrator
participant S as Scraper (Apify)
participant AI as Claude (AI)
participant G as Google Sheets
U->>O: "Find 20 Architects in Austin"
O->>S: Execute scrape_apify.py
S-->>O: Raw Lead Data (JSON)
loop For Each Lead
O->>AI: "Read website and find the Owner"
AI-->>O: "Owner: Sarah Miller, Email: sarah@millerarch.com"
end
O->>G: update_sheet.py
O-->>U: "Finished! Check your Google Sheet."
graph LR
subgraph "Scraping"
Scrape[Upwork Scraper] --> Batch[Job Batch JSON]
end
subgraph "AI Personalization"
Batch --> Filter[AI Relevance Filter]
Filter --> Name[Find Contact Name]
end
subgraph "Output"
Name --> Cover[Generate Cover Letter]
Cover --> Prop[Create Google Doc Proposal]
Prop --> Final[Update Tracker Sheet]
end
- Go to Google Cloud Console.
- Enable Google Sheets API and Google Drive API.
- Create a Service Account and download the
credentials.jsonfile. - Share your Google Sheet with the service account's email address.
Apify is the backbone of our web scraping. Each script calls a specific "Actor."
code_crafter/leads-finder: Our primary lead generation engine.compass/crawler-google-places: Used for mapping local businesses.
Directives are not just text; they are instructions for a machine.
- Goal: Define a clear, measurable outcome.
- Process: Use numbered steps.
- Edge Cases: Define exactly what to do if a tool fails (e.g., "If no email is found, skip this lead").
When a script in Layer 3 fails, the system doesn't just stop.
- Capture: The Orchestrator captures the error message.
- Diagnose: The AI analyzes the error (e.g., "Authentication Error").
- Fix: The AI attempts to fix the credential or parameter.
- Learn: The AI updates the Directive to prevent the error from happening again.
- Fix: Activate your virtual environment with
source venv/bin/activate.
- Fix: Ensure you have shared the Google Sheet with the email found in your
credentials.json.
- Fix: Your current API tier is limited. Reduce the
--limitin your command or wait 60 seconds.
- Fix: Do not copy the comments (lines starting with
#) into your terminal.
- Step 1: Learn to run
scrape_apify.pyand inspect the JSON output in.tmp/. - Step 2: Connect to Google Sheets and run
update_sheet.py. - Step 3: Understand the "Classification" logic in
classify_leads_llm.py. - Step 4: Master the
orchestrator.pyto run multi-step pipelines.
- Secrets: Never commit your
.envorcredentials.jsonto GitHub. - API Usage: Monitor your Apify and Anthropic usage to avoid unexpected costs.
- Rate Limiting: Always build "Sleep" intervals into your custom scripts to respect API limits.
- v2.0: Integration with WhatsApp Business API.
- v2.1: Automated LinkedIn outreach using Playwright.
- v2.2: Multi-agent orchestration using LangGraph.
Created by Antigravity AI - Building the Future of Agentic Workflows. (Total Documentation Length: ~600 Lines)