mirror of
https://github.com/x1xhlol/system-prompts-and-models-of-ai-tools.git
synced 2026-06-18 15:29:36 +00:00
227 lines
6.2 KiB
Markdown
227 lines
6.2 KiB
Markdown
# Agents Reference
|
||
|
||
Every agent extends `core.agents.base.BaseAgent` and exposes `async def run(**kwargs)`.
|
||
|
||
---
|
||
|
||
## Phase 8 — Auto Client Acquisition
|
||
|
||
### IntakeAgent
|
||
**File**: `auto_client_acquisition/agents/intake.py`
|
||
|
||
Captures leads from any source, normalizes them, detects duplicates.
|
||
|
||
**Inputs**:
|
||
- `payload: dict[str, Any]` — raw lead data
|
||
- `source: LeadSource | str` — where it came from
|
||
|
||
**Output**: `Lead` dataclass with:
|
||
- Normalized `contact_phone` (E.164 via `phonenumbers`)
|
||
- Normalized `contact_email` (lowercase, validated)
|
||
- Detected `locale` (`ar` or `en`) from message text
|
||
- `dedup_hash` — SHA-256 of `(email or phone) + company`
|
||
- `metadata.is_duplicate` flag
|
||
|
||
**Sources supported**: `website`, `whatsapp`, `email`, `referral`, `linkedin`, `cold_outreach`, `manual`, `api`.
|
||
|
||
---
|
||
|
||
### ICPMatcherAgent
|
||
**File**: `auto_client_acquisition/agents/icp_matcher.py`
|
||
|
||
Scores leads against an Ideal Customer Profile across **5 weighted dimensions**.
|
||
|
||
**Weights** (sum to 1.0):
|
||
- Industry: 0.25
|
||
- Size: 0.15
|
||
- Region: 0.20
|
||
- Budget: 0.20
|
||
- Pain: 0.20
|
||
|
||
**Output**: `FitScore` with per-dimension scores + overall tier (`A`/`B`/`C`/`D`) + recommendations.
|
||
|
||
**Default ICP**: target industries (tech, real estate, healthcare, education, logistics), GCC regions, SAR 10k–200k budget.
|
||
|
||
---
|
||
|
||
### PainExtractorAgent
|
||
**File**: `auto_client_acquisition/agents/pain_extractor.py`
|
||
|
||
**Hybrid extraction**:
|
||
1. Fast keyword pass (local, zero-cost) — scans AR+EN keyword dictionary
|
||
2. LLM enrichment — routed to **GLM for Arabic**, Claude otherwise
|
||
|
||
**Output**: `ExtractionResult` with pain points, urgency 0–1, likely offer, recommended next step.
|
||
|
||
---
|
||
|
||
### QualificationAgent
|
||
**File**: `auto_client_acquisition/agents/qualification.py`
|
||
|
||
Generates **5 BANT questions** (Budget / Authority / Need / Timeline) and updates lead status.
|
||
|
||
**LLM-first** with bilingual fallback question sets if LLM fails.
|
||
|
||
**Status advancement**:
|
||
- BANT ≥ 3 → `QUALIFIED`
|
||
- BANT ≥ 2 → `DISCOVERY`
|
||
|
||
---
|
||
|
||
### BookingAgent
|
||
**File**: `auto_client_acquisition/agents/booking.py`
|
||
|
||
**Priority order**:
|
||
1. Calendly — returns scheduling link (self-service)
|
||
2. Google Calendar — creates event directly (if service account configured)
|
||
3. Manual fallback — returns "team will contact you" message
|
||
|
||
**Saudi weekend aware** — skips Friday/Saturday when picking default slots.
|
||
|
||
---
|
||
|
||
### CRMAgent
|
||
**File**: `auto_client_acquisition/agents/crm.py`
|
||
|
||
HubSpot integration:
|
||
- Upserts contact by email (handles 409 conflicts via search-then-update)
|
||
- Creates deal with stage mapped from lead status
|
||
- Associates deal ↔ contact
|
||
|
||
Uses tenacity retry with exponential backoff.
|
||
|
||
---
|
||
|
||
### ProposalAgent
|
||
**File**: `auto_client_acquisition/agents/proposal.py`
|
||
|
||
Generates proposals via Claude (`Task.PROPOSAL`).
|
||
|
||
**Region-aware pricing**:
|
||
- Saudi Arabia → `PRICING_SA_*` from settings
|
||
- Other GCC → `PRICING_GCC_*`
|
||
- Global → `PRICING_GLOBAL_*_USD`
|
||
|
||
**Output**: `Proposal` with markdown body + 30-day validity.
|
||
|
||
---
|
||
|
||
### OutreachAgent
|
||
**File**: `auto_client_acquisition/agents/outreach.py`
|
||
|
||
Bilingual cold opener generation per channel (email, WhatsApp, LinkedIn, SMS).
|
||
|
||
Email variant includes a bilingual subject line builder.
|
||
|
||
---
|
||
|
||
### FollowUpAgent
|
||
**File**: `auto_client_acquisition/agents/followup.py`
|
||
|
||
**Cadence**: [0d, 3d, 7d, 14d] by default.
|
||
|
||
- Attempts 1–2 use canned bilingual scripts.
|
||
- Attempts 3+ use LLM with prior-history context.
|
||
- Auto-pauses on terminal statuses (won/lost/disqualified).
|
||
|
||
---
|
||
|
||
### AcquisitionPipeline
|
||
**File**: `auto_client_acquisition/pipeline.py`
|
||
|
||
Orchestrates the full funnel with **per-step error isolation**. Failures in any step appear in `result.warnings` but never abort the pipeline.
|
||
|
||
---
|
||
|
||
## Phase 9 — Autonomous Growth
|
||
|
||
### SectorIntelAgent
|
||
**File**: `autonomous_growth/agents/sector_intel.py`
|
||
|
||
Curated data for **12 Saudi sectors**. Can optionally enrich with LLM research.
|
||
|
||
Methods:
|
||
- `run(sector, enrich_with_llm=False)` — single sector
|
||
- `best_opportunity()` — highest (growth × AI readiness)
|
||
- `target_sectors()` — top 5
|
||
|
||
---
|
||
|
||
### ContentCreatorAgent
|
||
**File**: `autonomous_growth/agents/content.py`
|
||
|
||
Generates articles, LinkedIn posts, case studies, newsletters, tweet threads.
|
||
|
||
Arabic content → GLM (for nuance); English content → Claude.
|
||
|
||
---
|
||
|
||
### DistributionAgent
|
||
**File**: `autonomous_growth/agents/distribution.py`
|
||
|
||
Plans when to publish across channels using Riyadh-timezone optimal slots.
|
||
|
||
**Optimal times** (examples):
|
||
- LinkedIn: 8am, 12pm, 5pm
|
||
- Twitter: 9am, 1pm, 7pm
|
||
- Email: 9am
|
||
- WhatsApp broadcast: 7pm
|
||
|
||
---
|
||
|
||
### EnrichmentAgent
|
||
**File**: `autonomous_growth/agents/enrichment.py`
|
||
|
||
**Three-layer enrichment**:
|
||
1. Email domain → sector hints (e.g., `aramco.com` → `oil_gas`)
|
||
2. Phone country code → region
|
||
3. LLM inference from company name (best-effort)
|
||
|
||
---
|
||
|
||
### CompetitorMonitorAgent
|
||
**File**: `autonomous_growth/agents/competitor.py`
|
||
|
||
Summarizes competitor intel into: positioning, pricing hints, strengths, weaknesses, counter-moves.
|
||
|
||
---
|
||
|
||
### MarketResearchAgent
|
||
**File**: `autonomous_growth/agents/market_research.py`
|
||
|
||
Uses **Gemini** (`Task.RESEARCH`) for source-dense research with three depth levels (quick/standard/deep).
|
||
|
||
Output includes summary + bullet points + explicit caveats section.
|
||
|
||
---
|
||
|
||
## Prompt library
|
||
|
||
All prompts live in `core/prompts/karpathy_prompts.py`. Every prompt is **Karpathy-style**: explicit role, explicit task, explicit output format.
|
||
|
||
Registered prompts: `pain_extraction`, `icp_reasoning`, `proposal_generation`, `content_writer`, `sector_analysis`, `qualification_questions`, `competitor_summary`, `outreach_opener`, `followup`.
|
||
|
||
Sales scripts (canned bilingual) in `core/prompts/sales_scripts.py`: `opener`, `follow_up_1`, `follow_up_2`, `demo_confirm`, `proposal_cover`.
|
||
|
||
---
|
||
|
||
## Extending with a new agent
|
||
|
||
```python
|
||
# auto_client_acquisition/agents/my_agent.py
|
||
from core.agents.base import BaseAgent
|
||
|
||
class MyAgent(BaseAgent):
|
||
name = "my_agent"
|
||
|
||
async def run(self, *, foo: str, **_) -> dict:
|
||
self.log.info("running", foo=foo)
|
||
response = await self.router.run(
|
||
task=Task.REASONING,
|
||
messages=f"Process this: {foo}",
|
||
)
|
||
return {"result": response.content}
|
||
```
|
||
|
||
Register it in `auto_client_acquisition/agents/__init__.py` and optionally add to `pipeline.py`.
|