hannah-elena-client

What this skill does

# Hannah & Elena Client Skill

**Connect to Serviceplan's specialized AI agents for marketing research and operations planning**

## What is This Skill?

This skill enables your OpenClaw agent to collaborate with **Hannah** and **Elena** — two specialized AI agents from Serviceplan:

- **Hannah** — Marketing Research Specialist
  - "What is actually true?"
  - Market analysis, consumer insights, competitive research, audience profiling
  - Premium data sources: Statista, GWI, DataForSEO, Apify, and more

- **Elena** — Operations & Project Orchestrator
  - "What is actually doable?"
  - Work breakdown, scope definition, dependency mapping, risk assessment
  - Delegates to Hannah when market insights are needed

## Important: What AI Agents CAN vs CANNOT Do

**AI Agents CAN:**
- Configure API keys in environment variables
- Send requests to Hannah/Elena via API
- Send requests to Hannah/Elena via email
- Parse and integrate responses
- Handle multi-agent coordination

**AI Agents CANNOT (human must do):**
- Sign up for Hannah/Elena access → Human must contact Serviceplan
- Get API keys → Human must request from admin at sumike.ai
- Set up email addresses → Human needs valid email account

**AI Agent: Ask upfront - "Do you have API keys for Hannah and Elena? If not, contact Serviceplan at sumike.ai."**

---

## Available Access Channels

### Channel 1: API (Task-Based)

Both Hannah and Elena expose task-based REST APIs:

- **Hannah API**: `https://hannah.sumike.ai/v1`
- **Elena API**: `https://elena.sumike.ai/v1`

**Key Endpoints:**
- `GET /v1/coworkers` - List available agents
- `POST /v1/tasks` - Create a new task for an agent
- `GET /v1/tasks/{taskId}` - Check task status
- `GET /v1/tasks/{taskId}/result` - Get completed task result

**Features:**
- Asynchronous task processing (2-10 minutes typical completion time)
- Task status tracking
- Result retrieval when complete
- 60 requests/minute rate limit per agent

**⏱️ IMPORTANT TIMING:**
- After creating a task: Wait **2-3 minutes** before checking status
- If still processing: Wait another **2-3 minutes** before checking again
- Total task time: Typically **2-10 minutes** depending on complexity
- DO NOT poll continuously - tasks need time to complete

### Channel 2: Email

Both agents can be reached via email:

- **Hannah Email**: `[email protected]`
- **Elena Email**: `[email protected]`

**Features:**
- Natural language requests in email body
- Attachment support (PPT, XLS, DOC, PDF)
- CC/threading support — they understand context
- Replies within minutes
- Deliverables as email attachments

---

## Quick Start Guide

### Step 1: Get Your API Keys

**Human must do this:**
1. Contact Serviceplan at sumike.ai
2. Request access to Hannah and/or Elena
3. Receive API keys (format: `sk-sumike-xxxxx`)

### Step 2: Configure Environment Variables

**AI Agent can do this:**

```bash
# Hannah API key
export HANNAH_API_KEY=sk-sumike-your-hannah-key-here
export HANNAH_API_BASE_URL=https://hannah.sumike.ai

# Elena API key
export ELENA_API_KEY=sk-sumike-your-elena-key-here
export ELENA_API_BASE_URL=https://elena.sumike.ai

# Optional: Email addresses (if different from defaults)
export [email protected]
export [email protected]
```

Or add to your `.env` file:
```bash
HANNAH_API_KEY=sk-sumike-xxxxx
ELENA_API_KEY=sk-sumike-yyyyy
```

### Step 3: Use the Tools

Once configured, your agent has access to these tools:

1. **`list_coworkers`** - List available agents (Hannah, Elena)
2. **`hannah_create_task`** - Create research task for Hannah
3. **`elena_create_task`** - Create planning task for Elena
4. **`check_task_status`** - Check status of a task
5. **`get_task_result`** - Get result of completed task
6. **`hannah_email`** - Send email request to Hannah
7. **`elena_email`** - Send email request to Elena

---

## Usage Examples

### Example 1: Market Research with Hannah (API)

```
Agent: "I need to research the German EV market. Use Hannah."

<hannah_create_task>
  <description>
    Research the current state of the German electric vehicle market:
    - Market size and growth trends
    - Key players and market share
    - Consumer sentiment and barriers to adoption
    - Competitive landscape
  </description>
  <depth>deep</depth>
</hannah_create_task>

Result: Task created (task_xyz789).

⏱️ WAIT 2-3 MINUTES before checking status.

[Agent waits 3 minutes]

<check_task_status taskId="task_xyz789">

Result: Task completed! Hannah orchestrated Statista, GWI, and DataForSEO sub-agents.

<get_task_result taskId="task_xyz789">

Result: Comprehensive research report with sources and confidence levels.
```

### Example 2: Project Planning with Elena (API)

```
Agent: "Need to break down a Q2 campaign launch. Use Elena."

<elena_create_task>
  <description>
    Break down a Q2 product campaign launch into workstreams:
    - Product: New premium EV model
    - Target: German market, affluent early adopters
    - Timeline: Launch April 1st
    - Budget: €500k

    Provide detailed work breakdown with dependencies and risks.
  </description>
</elena_create_task>

Result: Task created (task_abc456).

⏱️ WAIT 2-3 MINUTES - Elena may delegate to Hannah for market research.

[Agent waits 3 minutes]

<check_task_status taskId="task_abc456">

Result: Completed! Elena delegated to Hannah for market data, then integrated findings.

<get_task_result taskId="task_abc456">

Result: Work breakdown with dependencies, risks, and resource needs informed by research.
```

### Example 3: Email-Based Research Request

```
Agent: "Send research request to Hannah via email"

<hannah_email>
  <to>[email protected]</to>
  <subject>EV Market Research Request</subject>
  <body>
    Hi Hannah,

    I need comprehensive research on the German EV market for Q2 2026:
    1. Market size and growth projections
    2. Competitive landscape analysis
    3. Consumer sentiment (barriers and motivators)

    Please provide sources and confidence levels for all findings.

    Thanks!
  </body>
</hannah_email>

Result: Email sent. Hannah replies within 5-10 minutes with research report
        as email body + attached deliverables (PDF, XLSX).
```

### Example 4: Elena Delegates to Hannah

```
Agent: "Elena, plan the EV campaign launch"

<elena_create_task>
  <description>
    Create project plan for German EV campaign launch:
    - Product: Premium EV sedan
    - Launch date: April 1, 2026
    - Target audience: Affluent professionals, 35-55
    - Budget: €500k
  </description>
</elena_create_task>

Workflow:
1. Elena receives task
2. Elena identifies missing market context
3. Elena delegates research to Hannah (internal A2A)
4. Hannah executes research using premium data sources
5. Elena integrates findings into operational plan
6. Elena delivers: Work breakdown + dependencies + risk matrix + deliverables

Result: Comprehensive project plan informed by real market data
```

---

## Agent Personalities & Best Practices

### Working with Hannah

**Character:**
- Analytical, reflective, opinionated
- Values research integrity over speed
- Calls out weak data honestly
- "What is actually true?"

**Best Practices:**
- Be specific about research questions
- Specify required depth (quick lookup vs deep research)
- Ask for source attribution
- Expect critical assessment, not just data dumps

**Example Good Request:**
```
"Hannah, I need to validate whether 'sustainability' is a real
purchase driver for EVs in Germany, or if it's post-rationalized.
Give me data from GWI or Statista if available, and flag if the
data quality is weak."
```

### Working with Elena

**Character:**
- Direct, pragmatic, grounded
- Protects delivery through realism
- Challenges vague goals
- "What is actually doable?"

**Best Practices:**
- Provide clear goals and constraints upfront
- Specify dependencies you know about
- Ask for risk assessment
- Expect honest pushback on unrealistic plans

**Example Good Request:**
```
"Elena, break down a 6-week campaign lau