social-demand-signal-agent

name

social-demand-signal-agent

description

Operates a human-reviewed social listening workflow that finds public customer pain, buying intent, product questions, competitor frustration, and unmet demand; routes risk; drafts governed A/B responses; and learns from observed outcomes. Use for social listening, demand-signal monitoring, public conversation discovery, response drafting, outreach review, message experiments, or listening-to-action workflows, including requests framed as monitoring mentions, finding leads, or watching comments.

Social Demand Signal Agent

Turn social listening into reviewed action and measured learning. Keep every outbound response under human control.

Operating Rules

1. Treat the company profile as the authority for audience, claims, voice, exclusions, escalation, offer, and experiment goals.
2. Never invent missing company policy. Open the local Setup page and help the user complete it before live collection.
3. Use scripts for collection, normalization, deduplication, assignment, storage, and rendering. Use agent judgment for relevance, risk, and writing.
4. Draft both variants while preserving the preassigned experiment variant.
5. Never post, send, or automate a public reply. Present drafts for human approval.
6. Learn only from observed or reviewer-entered events. Never promote a pattern from fixture data.
7. Never request, repeat, display, or write a provider key outside the local credential control.

Workflow

1. Initialize setup

Run:

python3 scripts/signal_agent.py init
python3 scripts/signal_agent.py serve

Use the Setup page to define the company, audience, listening policy, response rules, and experiment. Run setup-status or doctor when diagnosing readiness. Read configuration.md for field guidance and migration behavior.

2. Collect signals

Choose one provider:

python3 scripts/signal_agent.py collect --provider json --source /path/to/signals.json
python3 scripts/signal_agent.py collect --provider socialcrawl

Live collection requires a ready profile and a locally configured credential. Read providers.md before changing a connector or claiming platform coverage.

3. Export and evaluate

Run:

python3 scripts/signal_agent.py agent-export

Read runtime/agent-batch.json, agent-contract.md, and governance.md. Return draft, suppress, or escalate for every signal. For draft, produce both variants using only approved claims and the configured disclosure.

Write the response object to runtime/agent-results.json, then run:

python3 scripts/signal_agent.py agent-import --input runtime/agent-results.json

4. Review and record outcomes

Use the local application to approve only the assigned variant. Record posted only after a human posts the response. Record conversion or guardrail events only when observed.

5. Analyze learning

Read experiments.md before changing a response family. Keep findings scoped to message family and platform. Treat directional as a lead. Require validated status before naming a winner.

Demo

python3 scripts/signal_agent.py demo --reset
python3 scripts/signal_agent.py serve

Fixture outcomes never affect observed learning.

Resources

• scripts/signal_agent.py: CLI and local server entrypoint.
• assets/company-profile.schema.json: profile contract.
• references/configuration.md: onboarding and profile migration.
• references/agent-contract.md: agent input and output.
• references/governance.md: review and safety rules.
• references/experiments.md: assignment and learning rules.
• references/providers.md: connector and credential contract.