chnjinlei/hive
1
0
Fork 0
Code Issues Pull Requests Actions 41 Packages Projects Releases Wiki Activity

docs: use cases for first success

Browse Source
This commit is contained in:
Richard Tang
2026-02-10 17:42:05 -08:00
parent a2d21ec7bc
commit 7779bc5336
18 changed files with 812 additions and 188 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/agent_runtime.md
+172
View File
@@ -0,0 +1,172 @@
# Agent Runtime
Unified execution system for all Hive agents. Every agent — single-entry or multi-entry, headless or TUI — runs through the same runtime stack.
## Topology
```
AgentRunner.load(agent_path)
|
AgentRunner
(factory + public API)
|
_setup_agent_runtime()
|
AgentRuntime
(lifecycle + orchestration)
/ | \\
Stream A Stream B Stream C ← one per entry point
| | |
GraphExecutor GraphExecutor GraphExecutor
| | |
Node → Node → Node (graph traversal)
```
Single-entry agents get a `"default"` entry point automatically. There is no separate code path.
## Components
| Component | File | Role |
| --- | --- | --- |
| `AgentRunner` | `runner/runner.py` | Load agents, configure tools/LLM, expose high-level API |
| `AgentRuntime` | `runtime/agent_runtime.py` | Lifecycle management, entry point routing, event bus |
| `ExecutionStream` | `runtime/execution_stream.py` | Per-entry-point execution queue, session persistence |
| `GraphExecutor` | `graph/executor.py` | Node traversal, tool dispatch, checkpointing |
| `EventBus` | `runtime/event_bus.py` | Pub/sub for execution events (streaming, I/O) |
| `SharedStateManager` | `runtime/shared_state.py` | Cross-stream state with isolation levels |
| `OutcomeAggregator` | `runtime/outcome_aggregator.py` | Goal progress tracking across streams |
| `SessionStore` | `storage/session_store.py` | Session state persistence (`sessions/{id}/state.json`) |
## Programming Interface
### AgentRunner (high-level)
```python
from framework.runner import AgentRunner
# Load and run
runner = AgentRunner.load("exports/my_agent", model="anthropic/claude-sonnet-4-20250514")
result = await runner.run({"query": "hello"})
# Resume from paused session
result = await runner.run({"query": "continue"}, session_state=saved_state)
# Lifecycle
await runner.start() # Start the runtime
await runner.stop() # Stop the runtime
exec_id = await runner.trigger("default", {}) # Non-blocking trigger
progress = await runner.get_goal_progress() # Goal evaluation
entry_points = runner.get_entry_points() # List entry points
# Context manager
async with AgentRunner.load("exports/my_agent") as runner:
result = await runner.run({"query": "hello"})
# Cleanup
runner.cleanup() # Synchronous
await runner.cleanup_async() # Asynchronous
```
### AgentRuntime (lower-level)
```python
from framework.runtime.agent_runtime import AgentRuntime, create_agent_runtime
from framework.runtime.execution_stream import EntryPointSpec
# Create runtime with entry points
runtime = create_agent_runtime(
graph=graph,
goal=goal,
storage_path=Path("~/.hive/agents/my_agent"),
entry_points=[
EntryPointSpec(id="default", name="Default", entry_node="start", trigger_type="manual"),
],
llm=llm,
tools=tools,
tool_executor=tool_executor,
checkpoint_config=checkpoint_config,
)
# Lifecycle
await runtime.start()
await runtime.stop()
# Execution
exec_id = await runtime.trigger("default", {"query": "hello"}) # Non-blocking
result = await runtime.trigger_and_wait("default", {"query": "hello"}) # Blocking
result = await runtime.trigger_and_wait("default", {}, session_state=state) # Resume
# Client-facing node I/O
await runtime.inject_input(node_id="chat", content="user response")
# Events
sub_id = runtime.subscribe_to_events(
event_types=[EventType.CLIENT_OUTPUT_DELTA],
handler=my_handler,
)
runtime.unsubscribe_from_events(sub_id)
# Inspection
runtime.is_running # bool
runtime.event_bus # EventBus
runtime.state_manager # SharedStateManager
runtime.get_stats() # Runtime statistics
```
## Execution Flow
1. `AgentRunner.run()` calls `AgentRuntime.trigger_and_wait()`
2. `AgentRuntime` routes to the `ExecutionStream` for the entry point
3. `ExecutionStream` creates a `GraphExecutor` and calls `execute()`
4. `GraphExecutor` traverses nodes, dispatches tools, manages checkpoints
5. `ExecutionResult` flows back up through the stack
6. `ExecutionStream` writes session state to disk
## Session Resume
All execution paths support session resume:
```python
# First run (agent pauses at a client-facing node)
result = await runner.run({"query": "start task"})
# result.paused_at = "review-node"
# result.session_state = {"memory": {...}, "paused_at": "review-node", ...}
# Resume
result = await runner.run({"input": "approved"}, session_state=result.session_state)
```
Session state flows: `AgentRunner.run()` → `AgentRuntime.trigger_and_wait()` → `ExecutionStream.execute()` → `GraphExecutor.execute()`.
Checkpoints are saved at node boundaries (`sessions/{id}/checkpoints/`) for crash recovery.
## Event Bus
The `EventBus` provides real-time execution visibility:
| Event | When |
| --- | --- |
| `NODE_STARTED` | Node begins execution |
| `NODE_COMPLETED` | Node finishes |
| `TOOL_CALL_STARTED` | Tool invocation begins |
| `TOOL_CALL_COMPLETED` | Tool invocation finishes |
| `CLIENT_OUTPUT_DELTA` | Agent streams text to user |
| `CLIENT_INPUT_REQUESTED` | Agent needs user input |
| `EXECUTION_COMPLETED` | Full execution finishes |
In headless mode, `AgentRunner` subscribes to `CLIENT_OUTPUT_DELTA` and `CLIENT_INPUT_REQUESTED` to print output and read stdin. In TUI mode, `AdenTUI` subscribes to route events to UI widgets.
## Storage Layout
```
~/.hive/agents/{agent_name}/
sessions/
session_YYYYMMDD_HHMMSS_{uuid}/
state.json # Session state (status, memory, progress)
checkpoints/ # Node-boundary snapshots
logs/
summary.json # Execution summary
details.jsonl # Detailed event log
tool_logs.jsonl # Tool call log
runtime_logs/ # Cross-session runtime logs
```
docs/roadmap-developer-success.md
+107 -31
View File
@@ -78,32 +78,54 @@ The common denominator:
5. Can iterate on the agent
```
## Basic use cases (we shall have template for each one of these)
## Onboarding Experience
- Github issue triaging agent
- Tech&AI news digest agent
- Research report agent
- Teams daily digest and to-dos
- Discord autoreply bot
- Finance stock digest
- WhatsApp auto response agent
- Email followup agent
- Meeting time coordination agent
For "Developers who want to get a job done" and the "Individual product developer," they will likely want to try generating the agent themselves. see [## agent generation]
## Intermediate use cases
For others, they will likely want to try existing agents first to see how well the agent can work. see [## use existing agent]
### 1. Sales & Marketing
Marketing is often the most time-consuming "distraction" for a CEO. You provide the vision; they provide the volume.
## Agent Generation
- [Social Media Management](../examples/recipes/social_media_management/): Scheduling posts, replying to comments, and monitoring trends.
- [Newsletter Production](../examples/recipes/newsletter_production/): Taking your raw ideas or voice memos and turning them into a polished weekly email.
- [Ad Campaign Monitoring](../examples/recipes/ad_campaign_monitoring/): Checking daily spends on Meta/Google ads and flagging if the Cost Per Acquisition (CPA) spikes.
- [CRM Update Agent](../examples/recipes/crm_hygiene/): Ensuring every lead has a follow-up date and a status update.
[To be complete]
### 2. Customer Success
You shouldn't be the one answering "How do I reset my password?" but you should be the one closing $10k deals.
## Integration
- [Inquiry Triaging](../examples/recipes/inquiry_triaging/): Sorting the "tire kickers" from the "hot leads."
- [Onboarding Assistance](../examples/recipes/onboarding_assistance/): Helping new clients set up their accounts or sending out "Welcome" kits.
Happy path: In the goal setting, the agent do the job super well
### 3. Operations Automation
This is your right hand. They keep the gears greased so you don't get stuck in the "admin trap."
mid path: After negotiation, the agent explicitly told the user
- [Inbox Management](../examples/recipes/inbox_management/): Clearing out the spam and highlighting the three emails that actually need your brain.
- [Invoicing & Collections](../examples/recipes/invoicing_collections/): Sending out bills and—more importantly—politely chasing down the people who haven't paid them.
- [Data Keeper](../examples/recipes/data_keeper/): Pull data and reports from multiple data sources, and union them in one place.
- [Travel & Calendar Coordination](../examples/recipes/calendar_coordination/): Protecting your "Deep Work" time from getting fragmented by random 15-minute meetings.
Sad path: After negotiation and tried to build a one off integration for certain tools
### 4. The Technical & Product Maintenance
Unless you are a developer, tech debt will kill your productivity. A part-timer can keep the lights on.
## Agent Testing
- [Quality Assurance](../examples/recipes/quality_assurance/): Testing new features or links before they go live to ensure nothing is broken.
- [Documentation](../examples/recipes/documentation/): Turning your messy processes into clean Standard Operating Procedures (SOPs).
- [Basic Troubleshooting](../examples/recipes/basic_troubleshooting/): Handling "Level 1" tech support for your platform or website.
- [Issue Triaging](../examples/recipes/issue_triaging/): Categorizing and routing incoming bug reports by severity.
Interactive testing:
## Installation
Autonomous testing:
## How agent runtime works
Install the prer-requisites like python
Install quickstart
## use existing agent
If user would like to
@@ -115,36 +137,99 @@ These are what happen:
(automatically) Agent run, outcome happens and is recorded
(if failed) Tell the user where the logs are saved
## Agent generation (alternative to using existing agent)
For "Developers who want to get a job done" and the "Individual product developer," they will likely want to try generating the agent themselves. see [## agent generation]
For others, they will likely want to try existing agents first to see how well the agent can work. see [## use existing agent]
If user find somethign they can't fulfill with the framework, they can choose to contribute by share it in an issue or in the discord channel
## Agent Testing
Interactive testing: Run `hive tui` and test the agent in a tui
Autonomous testing: Run `hive run XXX --debug` and trigger the event source. Testing events, especially the scheduled event can be hard. It would be benificial if we provide some developer tools to finish them.
(after commercial ready stage) Sample agent testing without installation: We host some sample agents on cloud and provide them to the users to test directly without installation
## Integration
Users can't even finish testing without setting up the integration correctly.
Happy path: In the goal setting, the agent do the job super well
mid path: After negotiation, the agent explicitly told the user
Sad path: After negotiation and tried to build a one off integration for certain tools
## Agent Debugging
If any error / unexpected behavior happens during testing, the developer need to be able to debug the agent
## Logging
To make it easier for user to have a AI-assisted experience checking log and get reported the insight with high signal/noise ratio,
Hive uses a **three-level observability** for tracking agent execution:
| Level | What it captures | File |
|-------|------------------|------|
| **L1 (Summary)** | Run outcomes — success/failure, execution quality, attention flags | `summary.json` |
| **L2 (Details)** | Per-node results — retries, verdicts, latency, attention reasons | `details.jsonl` |
| **L3 (Tool Logs)** | Step-by-step execution — tool calls, LLM responses, judge feedback | `tool_logs.jsonl` |
## (Optional) How graph works
Developers need to understand node memory works, how tools are called. for them to fix and improve the agent they built. see `docs/key_concepts` for details
## **first success**
By here, the developer should already finish running one of their first agent and get a grasp of how the agent frameworks works. They can very well trying to use it for the real use cases, which often invoice updating the current agennt
Anything before the first success is not negotiateble something we need to ensure running as smooth as possible
## Iteration (building) - More like debugging
[To be complete]
After the MVP agent/sample agent runs. Developer want to iterate the agent by biggering the use cases.
## Iteration (production) - Evolution and inventiveness
[To be complete]
Afterthe MVP is deployed. Which taste and judgement are still came from the human developers, AI was a significen force multiplier for rapidly iterating and solving problems.
## Automomous
Core should remain the same, different deployment flag
For Aden cloud hive, the production evolution is fully automatic. Aden queen bee run a natural selection by deploying, evaluating and improving.
## Version Control
Iteration is not always improving everything. To help the developers, version control helps them getting back to the previous version , ike how git works. They run this command `hive git restore` to to
## Agent Personality
Developers want to put their own soul into the agent. What remain the same across the evolution is important. Developer success is not about having the agent constantly changing. It is about you know the goal and the personality of the agent will not chanage, and it just adapt to the environment to solve problems.
# Deployment
## (Optional) How agent runtime works
Developers need to understand how data are transfered during agent runtime, how memory works, how tools works. for them to fix and improve the agent they built. see ./agent_runtime.md for details
## Local Deployment
By default we support deployment through docker.
## Cloud Deployment
For users who want zero-ops deployment, easier integration and credential management, and logging, Aden cloud is ideal. Users who don’t want to manage infra get secure defaults, scaling, and observability out of the box—at the cost of less low-level control and some vendor lock-in.
## Deployment Strategy
Autonomous and interactive modes look different, but the core should remain the same, and the deployment strategy should also be consistent.
## Performance
Not a focus at the moment
Speed of run, hellucination
## How we collect data
Self-reported issues
Cloud observabiltiy product
## How guardrail is done
## Runtime guardrails
[To be complete]
## How we make reliability
Breakages still happens, even in the most best business process: Being reliable is to be adaptive and fix the problems
[To be complete]
@@ -153,12 +238,3 @@ Breakages still happens, even in the most best business process: Being reliable
## Developer trust
[To be complete]
## What Success Looks Like for Them
In short, the common ground is having the agent "used in prod."
## Deployment Strategy
How the developers deploy their agents. Autonomous and interactive agent might be different. Human in the loop might need hooks and sdks
examples/recipes/README.md
+27 -1
View File
@@ -22,6 +22,32 @@ Each recipe is a markdown file (or folder with a markdown file) containing:
## Available recipes
### Sales & Marketing
| Recipe | Description |
|--------|-------------|
| [marketing_agent](marketing_agent/) | Multi-channel marketing content generator with audience analysis and A/B copy variants |
| [social_media_management](social_media_management/) | Schedule posts, reply to comments, monitor trends |
| [newsletter_production](newsletter_production/) | Transform voice memos and ideas into polished emails |
| [ad_campaign_monitoring](ad_campaign_monitoring/) | Monitor ad spend and flag CPA spikes |
| [crm_hygiene](crm_hygiene/) | Ensure every lead has follow-up dates and status |
### Customer Success
| Recipe | Description |
|--------|-------------|
| [inquiry_triaging](inquiry_triaging/) | Sort tire kickers from hot leads |
| [onboarding_assistance](onboarding_assistance/) | Guide new clients through setup and welcome kits |
### Operations Automation
| Recipe | Description |
|--------|-------------|
| [inbox_management](inbox_management/) | Clear spam and surface emails that need your brain |
| [invoicing_collections](invoicing_collections/) | Send invoices and chase overdue payments |
| [data_keeper](data_keeper/) | Pull data from multiple sources into unified reports |
| [calendar_coordination](calendar_coordination/) | Protect Deep Work time and book travel |
### Technical & Product Maintenance
| Recipe | Description |
|--------|-------------|
| [quality_assurance](quality_assurance/) | Test features and links before they go live |
| [documentation](documentation/) | Turn messy processes into clean SOPs |
| [basic_troubleshooting](basic_troubleshooting/) | Handle Level 1 tech support |
| [issue_triaging](issue_triaging/) | Categorize and route bug reports by severity |
examples/recipes/ad_campaign_monitoring/README.md
+36
View File
@@ -0,0 +1,36 @@
# Recipe: Ad Campaign Monitoring
Checking daily spends on Meta/Google ads and flagging if the Cost Per Acquisition (CPA) spikes.
## Why
Ad platforms are designed to spend your money. Without daily oversight, a $50/day campaign can quietly become a $500 disaster. This agent watches your campaigns like a hawk, catching anomalies before they drain your budget and surfacing optimization opportunities you'd otherwise miss.
## What
- Monitor daily spend across all active campaigns
- Track CPA, ROAS, CTR, and conversion metrics
- Compare performance against historical benchmarks
- Identify underperforming ads and audiences
- Generate daily/weekly performance summaries
## Integrations
| Platform | Purpose |
|----------|---------|
| Meta Ads API | Facebook/Instagram campaign data |
| Google Ads API | Search/Display/YouTube campaign data |
| Google Analytics 4 | Conversion tracking and attribution |
| Google Sheets | Performance dashboards and reporting |
| Slack | Alerts and daily summaries |
## Escalation Path
| Trigger | Action |
|---------|--------|
| CPA spikes >30% above target | Alert with breakdown by ad set and pause recommendation |
| Daily budget exhausted before noon | Immediate alert — possible click fraud or viral ad |
| ROAS drops below profitability threshold | Pause campaign and notify with optimization suggestions |
| Ad rejected by platform | Alert with rejection reason and suggested fix |
| Competitor running aggressive campaign | Flag if detected through auction insights |
| Budget pacing off by >20% | Alert with projected monthly spend |
examples/recipes/basic_troubleshooting/README.md
+37
View File
@@ -0,0 +1,37 @@
# Recipe: Basic Troubleshooting
Handling "Level 1" tech support for your platform or website.
## Why
Most support tickets are the same 20 questions over and over: password resets, access issues, "how do I..." questions. You don't need to answer these — but someone does. This agent handles the repetitive tier-1 support so your users get fast answers and you get your time back.
## What
- Handle password resets and account access issues
- Answer common "how do I" questions from the knowledge base
- Walk users through basic setup and configuration
- Collect diagnostic information for complex issues
- Log all support interactions for pattern analysis
## Integrations
| Platform | Purpose |
|----------|---------|
| Intercom / Zendesk / Freshdesk | Support ticket management |
| Notion / Confluence | Knowledge base for answers |
| Slack | Internal escalation channel |
| Your product's API | Account status, password reset triggers |
| LogRocket / FullStory | Session replay for debugging |
| PagerDuty | Urgent escalation routing |
## Escalation Path
| Trigger | Action |
|---------|--------|
| Issue not resolved within 30 minutes | Escalate with full context gathered |
| User expresses frustration or anger | Immediate handoff to human with de-escalation note |
| Security-related issue (account compromise, data concern) | Escalate immediately, do not attempt to resolve |
| Bug discovered during troubleshooting | Create ticket and escalate to engineering |
| VIP or enterprise customer | Flag for priority handling regardless of issue |
| Same issue reported by 3+ users | Alert as potential systemic problem |
examples/recipes/calendar_coordination/README.md
+37
View File
@@ -0,0 +1,37 @@
# Recipe: Travel & Calendar Coordination
Protecting your "Deep Work" time from getting fragmented by random 15-minute meetings.
## Why
Your calendar is a battlefield. Everyone wants a slice of your time, and without protection, your days become a patchwork of 30-minute meetings with no room for actual work. This agent defends your schedule — booking travel, consolidating meetings, and protecting the focus time you need to think.
## What
- Block and protect "Deep Work" time slots
- Batch similar meetings together to reduce context switching
- Book travel (flights, hotels, ground transport)
- Handle meeting requests and rescheduling
- Prep briefing docs before important meetings
## Integrations
| Platform | Purpose |
|----------|---------|
| Google Calendar / Outlook | Calendar management |
| Calendly / Cal.com | External scheduling |
| TripIt / Google Flights / Kayak | Travel booking |
| Expensify / Ramp | Travel expense tracking |
| Notion / Google Docs | Meeting prep documents |
| Slack | Schedule alerts and confirmations |
## Escalation Path
| Trigger | Action |
|---------|--------|
| Someone tries to book over Deep Work time | Decline and offer alternatives, alert you if they push back |
| VIP requests meeting during protected time | Flag for your decision — worth the exception? |
| Flight cancelled or significantly delayed | Immediate alert with rebooking options |
| Double-booking conflict | Alert with suggested resolution |
| Meeting with no agenda 24h before | Prompt organizer for agenda, flag if none provided |
| Travel cost exceeds budget threshold | Queue for approval before booking |
examples/recipes/crm_update/README.md
+35
View File
@@ -0,0 +1,35 @@
# Recipe: CRM Update
Ensuring every lead has a follow-up date and a status update.
## Why
A messy CRM is a leaky pipeline. Leads without follow-up dates get forgotten. Deals without status updates go stale. This agent keeps your CRM clean and actionable — so when you open it, you see exactly what needs your attention today.
## What
- Audit leads missing follow-up dates or status updates
- Flag stale deals that haven't been touched in X days
- Merge duplicate contacts and companies
- Enrich records with missing data (email, phone, company info)
- Generate daily "pipeline hygiene" reports
## Integrations
| Platform | Purpose |
|----------|---------|
| HubSpot / Salesforce / Pipedrive | CRM management |
| Clearbit / Apollo / ZoomInfo | Data enrichment |
| Google Sheets | Hygiene reports and audits |
| Slack | Daily pipeline summary and action items |
| Zapier / Make | Cross-platform data sync |
## Escalation Path
| Trigger | Action |
|---------|--------|
| High-value deal stale >14 days | Alert with deal history and suggested re-engagement |
| Duplicate detected for active deal | Flag before merging — might be intentional |
| Lead data conflicts with enrichment | Queue for human verification |
| Pipeline value drops significantly week-over-week | Alert with analysis of what changed |
| Follow-up overdue for >5 leads | Daily digest with prioritized action list |
examples/recipes/data_keeper/README.md
+38
View File
@@ -0,0 +1,38 @@
# Recipe: Data Keeper
Pull data and reports from multiple data sources.
## Why
You can't steer the ship if you're the one manually copying and pasting numbers from Google Analytics into an Excel sheet. Every hour spent wrangling data is an hour not spent making decisions based on that data. This agent becomes your "Data DJ" — mixing sources, syncing sheets, and serving up the numbers you need when you need them.
## What
- Pull metrics from analytics, ads, CRM, and other platforms
- Consolidate data into unified dashboards and spreadsheets
- Generate daily/weekly/monthly reports automatically
- Track KPIs and flag anomalies or trends
- Keep data sources in sync (no more stale spreadsheets)
## Integrations
| Platform | Purpose |
|----------|---------|
| Google Analytics 4 | Website traffic and conversion data |
| Google Sheets / Excel | Report destination and dashboards |
| Meta Ads / Google Ads | Ad performance metrics |
| Stripe / QuickBooks | Revenue and financial data |
| HubSpot / Salesforce | Sales pipeline and CRM metrics |
| Slack | Report delivery and anomaly alerts |
| BigQuery / Snowflake | Data warehouse queries (if applicable) |
## Escalation Path
| Trigger | Action |
|---------|--------|
| Data source API fails or returns errors | Alert with error details and last successful sync time |
| KPI drops >20% week-over-week | Immediate alert with breakdown by segment |
| Data discrepancy between sources | Flag for investigation — which source is correct? |
| Report generation fails | Notify with error and offer manual trigger |
| Unusual spike in any metric | Alert with context — is this real or a tracking bug? |
| New data source requested | Queue for setup — may need credentials or API access |
examples/recipes/documentation/README.md
+37
View File
@@ -0,0 +1,37 @@
# Recipe: Documentation
Turning your messy processes into clean Standard Operating Procedures (SOPs).
## Why
Knowledge trapped in your head is a liability. When you're the only one who knows how things work, you become the bottleneck for everything. This agent captures your processes, cleans them up, and turns them into documentation anyone can follow — including your future self.
## What
- Watch you perform processes and document the steps
- Convert rough notes and recordings into structured SOPs
- Maintain and update existing documentation
- Identify undocumented processes that need capture
- Create quick-reference guides and checklists
## Integrations
| Platform | Purpose |
|----------|---------|
| Notion / Confluence / GitBook | Documentation hosting |
| Loom / Screen recording | Process capture |
| Otter.ai / Whisper | Meeting and explanation transcription |
| Slack | Documentation requests and updates |
| GitHub | Technical documentation and READMEs |
| Google Docs | Collaborative editing |
## Escalation Path
| Trigger | Action |
|---------|--------|
| Process has conflicting documentation | Flag discrepancy for clarification |
| SOP referenced but outdated >6 months | Queue for your review and update |
| Someone asks question not covered by docs | Note the gap, draft new section for approval |
| Critical process has no documentation | Alert as priority documentation needed |
| Documentation contradicts current practice | Flag for reconciliation — update docs or process? |
| External compliance requirement needs docs | Escalate with deadline and requirements |
examples/recipes/inbox_management/README.md
+35
View File
@@ -0,0 +1,35 @@
# Recipe: Inbox Management
Clearing out the spam and highlighting the three emails that actually need your brain.
## Why
Email is where productivity goes to die. The average CEO gets 120+ emails per day, but only a handful actually matter. This agent acts as your email bouncer — filtering the noise so you can focus on the messages that move the needle.
## What
- Filter and archive spam, newsletters, and low-priority messages
- Categorize emails by urgency and type (action needed, FYI, waiting on)
- Summarize long email threads into key points
- Draft responses for routine inquiries
- Surface the 3-5 emails that truly need your attention
## Integrations
| Platform | Purpose |
|----------|---------|
| Gmail API / Microsoft Graph | Email access and management |
| Google Calendar | Context for scheduling-related emails |
| Slack | Daily inbox briefing and urgent alerts |
| Notion | Email summary archive for reference |
| Your CRM | Cross-reference with known contacts and deals |
## Escalation Path
| Trigger | Action |
|---------|--------|
| Email from VIP contact (investor, key client, partner) | Surface immediately, never auto-respond |
| Legal or compliance language detected | Flag for your review — do not respond |
| Angry or escalation tone detected | Alert with suggested de-escalation response |
| Email requires decision with financial impact | Queue for your review with context |
| Unrecognized sender with urgent request | Flag as potential phishing or verify before acting |
examples/recipes/inquiry_triaging/README.md
+35
View File
@@ -0,0 +1,35 @@
# Recipe: Inquiry Triaging
Sorting the "tire kickers" from the "hot leads."
## Why
Not all leads are created equal. For every serious buyer, there are ten people who'll never purchase. Your time should go to the prospects most likely to close — this agent scores and routes inquiries so you only see the ones worth your attention.
## What
- Analyze incoming inquiries for buying signals
- Score leads based on company size, budget mentions, urgency, and fit
- Route hot leads to your calendar immediately
- Nurture warm leads with automated sequences
- Politely deflect poor-fit inquiries
## Integrations
| Platform | Purpose |
|----------|---------|
| HubSpot / Salesforce / Pipedrive | CRM and lead management |
| Intercom / Drift / Crisp | Live chat and inquiry capture |
| Calendly / Cal.com | Meeting scheduling for qualified leads |
| Clearbit / Apollo | Company enrichment and firmographics |
| Slack / Email | Hot lead alerts |
## Escalation Path
| Trigger | Action |
|---------|--------|
| Enterprise lead detected (>500 employees) | Immediate alert with company brief and suggested approach |
| Lead mentions competitor by name | Flag for competitive positioning response |
| Urgent language detected ("need this week", "ASAP") | Fast-track to your calendar |
| Lead asks question outside playbook | Queue for your personal response |
| High-value lead goes cold (no response in 48h) | Alert with re-engagement suggestions |
examples/recipes/invoicing_collections/README.md
+36
View File
@@ -0,0 +1,36 @@
# Recipe: Invoicing & Collections
Sending out bills and—more importantly—politely chasing down the people who haven't paid them.
## Why
Cash flow is oxygen. But chasing invoices is awkward and time-consuming. This agent handles the uncomfortable job of asking for money — sending invoices on time, following up persistently but politely, and only escalating when the situation requires your personal touch.
## What
- Generate and send invoices on schedule
- Track payment status across all outstanding invoices
- Send automated payment reminders (friendly → firm → final)
- Reconcile payments with bank transactions
- Report on AR aging and cash flow projections
## Integrations
| Platform | Purpose |
|----------|---------|
| QuickBooks / Xero / FreshBooks | Invoicing and accounting |
| Stripe / PayPal | Payment processing and status |
| Plaid / Mercury | Bank transaction reconciliation |
| Slack / Email | Collection alerts and summaries |
| Google Sheets | AR aging reports and forecasts |
## Escalation Path
| Trigger | Action |
|---------|--------|
| Invoice overdue >30 days | Escalate with payment history and suggested next steps |
| Large invoice (>$5k) goes overdue | Alert immediately with client context |
| Client disputes invoice | Flag for your review with dispute details |
| Payment bounces or fails | Alert with retry options |
| Client requests payment plan | Queue for your approval with suggested terms |
| Collections threshold reached (>60 days) | Recommend formal collection action |
examples/recipes/issue_triaging/README.md
+38
View File
@@ -0,0 +1,38 @@
# Recipe: Issue Triaging
Categorizing and routing incoming bug reports by severity and type.
## Why
Not all bugs are equal. A typo in the footer can wait; a checkout failure cannot. This agent sorts the incoming chaos — categorizing issues by severity, gathering reproduction steps, and routing them to the right person — so critical bugs get fixed fast and minor ones don't clog the queue.
## What
- Categorize incoming issues by type (bug, feature request, question)
- Assess severity based on impact and frequency
- Gather reproduction steps and environment details
- Route to appropriate team member or queue
- Track issue lifecycle from report to resolution
## Integrations
| Platform | Purpose |
|----------|---------|
| GitHub Issues / Linear / Jira | Issue tracking |
| Sentry / LogRocket / Datadog | Error context and logs |
| Slack | Triage notifications and discussion |
| Intercom / Zendesk | Customer-reported issue intake |
| Notion | Issue categorization rules and playbooks |
| PagerDuty | Critical issue escalation |
## Escalation Path
| Trigger | Action |
|---------|--------|
| Security vulnerability reported | Immediate escalation, mark as confidential |
| Data loss or corruption issue | P0 alert with all available context |
| Issue affecting >10% of users | Escalate as incident with scope estimate |
| Issue unsolvable within 30 minutes | Escalate with what was tried and ruled out |
| Customer-reported issue from enterprise account | Priority flag regardless of severity assessment |
| Same issue reported 5+ times in 24h | Alert as emerging pattern, consider incident |
| Issue requires architecture decision | Queue for tech lead review |
examples/recipes/marketing_agent/README.md
-156
View File
@@ -1,156 +0,0 @@
# Recipe: Marketing Content Agent
A multi-channel marketing content generator. Given a product description and target audience, this agent analyzes the audience, generates tailored copy for multiple channels, and produces A/B variants.
## Goal
```
Name: Marketing Content Generator
Description: Generate targeted marketing content across multiple channels
for a given product and audience.
Success criteria:
- Audience analysis is produced with demographics and pain points
- At least 2 channel-specific content pieces are generated
- A/B variants are provided for each piece
- All content aligns with the specified brand voice
Constraints:
- (hard) No competitor brand names in generated content
- (soft) Content should be under 280 characters for social media channels
```
## Input / Output
**Input:**
- `product_description` (str) — What the product is and does
- `target_audience` (str) — Who the content is for
- `brand_voice` (str) — Tone and style guidelines (e.g., "professional but approachable")
- `channels` (list[str]) — Target channels, e.g. `["email", "twitter", "linkedin"]`
**Output:**
- `audience_analysis` (dict) — Demographics, pain points, motivations
- `content` (list[dict]) — Per-channel content with A/B variants
## Workflow
```
[analyze_audience] → [generate_content] → [review_and_refine]
|
(conditional)
|
needs_revision == True → [generate_content]
needs_revision == False → (done)
```
## Nodes
### 1. analyze_audience
| Field | Value |
|-------|-------|
| Type | `llm_generate` |
| Input keys | `product_description`, `target_audience` |
| Output keys | `audience_analysis` |
| Tools | None |
**System prompt:**
```
You are a marketing strategist. Analyze the target audience for a product.
Product: {product_description}
Target audience: {target_audience}
Produce a structured analysis in JSON:
{{
"audience_analysis": {{
"demographics": "...",
"pain_points": ["..."],
"motivations": ["..."],
"preferred_channels": ["..."],
"messaging_angle": "..."
}}
}}
```
### 2. generate_content
| Field | Value |
|-------|-------|
| Type | `llm_generate` |
| Input keys | `product_description`, `audience_analysis`, `brand_voice`, `channels` |
| Output keys | `content` |
| Tools | None |
**System prompt:**
```
You are a marketing copywriter. Generate content for each channel.
Product: {product_description}
Audience analysis: {audience_analysis}
Brand voice: {brand_voice}
Channels: {channels}
For each channel, produce two variants (A and B).
Output as JSON:
{{
"content": [
{{
"channel": "twitter",
"variant_a": "...",
"variant_b": "..."
}}
]
}}
```
### 3. review_and_refine
| Field | Value |
|-------|-------|
| Type | `llm_generate` |
| Input keys | `content`, `brand_voice` |
| Output keys | `content`, `needs_revision` |
| Tools | None |
**System prompt:**
```
You are a senior marketing editor. Review the following content for brand
voice alignment, clarity, and channel appropriateness.
Content: {content}
Brand voice: {brand_voice}
If any piece needs revision, fix it and set needs_revision to true.
If everything looks good, return the content unchanged with needs_revision false.
Output as JSON:
{{
"content": [...],
"needs_revision": false
}}
```
## Edges
| Source | Target | Condition | Priority |
|--------|--------|-----------|----------|
| analyze_audience | generate_content | `on_success` | 0 |
| generate_content | review_and_refine | `on_success` | 0 |
| review_and_refine | generate_content | `conditional: needs_revision == True` | 10 |
The `review_and_refine → generate_content` loop has higher priority so it's checked first. If `needs_revision` is false, execution ends at `review_and_refine` (terminal node).
## Tools
This recipe uses no external tools — all nodes are `llm_generate`. To extend it, consider adding:
- A web search tool for competitive analysis in the `analyze_audience` node
- A URL shortener tool for social media content
- An image generation tool for visual content variants
## Variations
- **Single-channel mode**: Remove the `channels` input and hardcode to one channel for simpler output
- **With approval gate**: Add a `human_input` node between `review_and_refine` and the terminal to require human sign-off
- **With analytics**: Add a `function` node that logs generated content to a tracking system
examples/recipes/newsletter_production/README.md
+35
View File
@@ -0,0 +1,35 @@
# Recipe: Newsletter Production
Taking your raw ideas or voice memos and turning them into a polished weekly email.
## Why
Your audience wants to hear from you, not your ghostwriter. But you don't have 4 hours to craft the perfect newsletter. This agent captures your voice from quick inputs — voice memos, bullet points, Slack messages — and transforms them into publish-ready emails that sound like you.
## What
- Ingest raw content (voice memos, notes, bullet points)
- Draft newsletter in your voice and style
- Format with headers, links, and CTAs
- Schedule for optimal send time
- Track open rates and click-through for future optimization
## Integrations
| Platform | Purpose |
|----------|---------|
| Otter.ai / Whisper | Voice memo transcription |
| Notion / Google Docs | Draft storage and editing |
| Mailchimp / ConvertKit / Beehiiv | Newsletter distribution |
| Slack | Content intake and approvals |
| Google Analytics / UTM tracking | Performance measurement |
## Escalation Path
| Trigger | Action |
|---------|--------|
| Draft ready for review | Send preview link and summary for your approval |
| Unusually low open rate on last send | Alert with analysis and A/B test suggestions |
| Subscriber replies with question | Forward replies that need your expertise |
| Unsubscribe spike after send | Flag with content analysis — what went wrong? |
| Sponsor or partnership mention required | Queue for your review before sending |
examples/recipes/onboarding_assistance/README.md
+36
View File
@@ -0,0 +1,36 @@
# Recipe: Onboarding Assistance
Helping new clients set up their accounts or sending out "Welcome" kits.
## Why
First impressions stick. A smooth onboarding experience sets the tone for the entire customer relationship — but walking each new client through the same steps is a time sink. This agent delivers a white-glove experience at scale, making every customer feel personally welcomed.
## What
- Send personalized welcome emails and kits
- Guide clients through account setup step-by-step
- Answer common "getting started" questions
- Track onboarding completion and milestone progress
- Follow up on incomplete setups
## Integrations
| Platform | Purpose |
|----------|---------|
| Intercom / Customer.io | Onboarding email sequences |
| Notion / Loom | Tutorial content and documentation |
| Calendly | Onboarding call scheduling |
| Slack / Email | Progress updates and escalations |
| Your product's API | Track setup completion status |
| Typeform / Tally | Onboarding surveys and data collection |
## Escalation Path
| Trigger | Action |
|---------|--------|
| Client stuck on setup >48 hours | Alert with where they're stuck and offer to schedule call |
| Technical blocker during setup | Route to support with context already gathered |
| High-value client starts onboarding | Notify so you can send personal welcome |
| Client expresses frustration | Immediate flag for human intervention |
| Onboarding incomplete after 7 days | Escalate with churn risk assessment |
examples/recipes/quality_assurance/README.md
+37
View File
@@ -0,0 +1,37 @@
# Recipe: Quality Assurance (QA)
Testing new features or links before they go live to ensure nothing is broken.
## Why
Broken features kill trust. One bad deploy can undo months of goodwill with your users. This agent runs systematic checks before anything goes live — catching the broken links, form errors, and edge cases that would otherwise reach your customers first.
## What
- Run automated test suites before deploys
- Manually verify critical user flows (signup, checkout, core features)
- Check all links for 404s and broken redirects
- Test across browsers and device sizes
- Verify integrations are responding correctly
## Integrations
| Platform | Purpose |
|----------|---------|
| GitHub Actions / CircleCI | CI/CD pipeline integration |
| Playwright / Cypress / Selenium | Automated browser testing |
| BrowserStack / LambdaTest | Cross-browser testing |
| Checkly / Uptrends | Synthetic monitoring |
| Slack / PagerDuty | Test failure alerts |
| Linear / Jira | Bug ticket creation |
## Escalation Path
| Trigger | Action |
|---------|--------|
| Critical test fails (auth, checkout, data) | Block deploy, alert immediately with failure details |
| Flaky test (passes sometimes, fails others) | Flag for investigation but don't block |
| New feature breaks existing functionality | Alert with regression details and affected areas |
| Performance degradation detected | Flag with before/after metrics |
| Security scan finds vulnerability | Immediate escalation with severity and remediation |
| All tests pass but something "feels off" | Document observation and flag for human review |
examples/recipes/social_media_management/README.md
+34
View File
@@ -0,0 +1,34 @@
# Recipe: Social Media Management
Scheduling posts, replying to comments, and monitoring trends.
## Why
Consistency kills on social media — but it also kills your time. One "quick post" turns into an hour of tweaking copy, finding hashtags, and responding to comments. This agent maintains your social presence so you stay visible without staying glued to your phone.
## What
- Schedule posts across platforms (Twitter/X, LinkedIn, Instagram, Facebook)
- Reply to comments and DMs with on-brand responses
- Monitor trending topics and hashtags in your niche
- Track engagement metrics and surface what's working
## Integrations
| Platform | Purpose |
|----------|---------|
| Buffer / Hootsuite / Later | Post scheduling and publishing |
| Twitter/X API | Direct posting and engagement |
| LinkedIn API | Professional network management |
| Meta Graph API | Facebook/Instagram management |
| Slack | Notifications and escalations |
## Escalation Path
| Trigger | Action |
|---------|--------|
| Post goes viral (>10x normal engagement) | Alert with engagement stats and suggested follow-up content |
| Negative viral moment | Immediate alert — do NOT auto-respond, queue for human review |
| Influencer or press mentions you | Flag for personal response opportunity |
| Controversial topic trending in your space | Alert before posting scheduled content that might be tone-deaf |
| DM from verified account or known lead | Route directly to you |