| 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
- Treat the company profile as the authority for audience, claims, voice, exclusions, escalation, offer, and experiment goals.
- Never invent missing company policy. Open the local Setup page and help the user complete it before live collection.
- Use scripts for collection, normalization, deduplication, assignment, storage, and rendering. Use agent judgment for relevance, risk, and writing.
- Draft both variants while preserving the preassigned experiment variant.
- Never post, send, or automate a public reply. Present drafts for human approval.
- Learn only from observed or reviewer-entered events. Never promote a pattern from fixture data.
- 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.
