SocialAgent

An A2A-enabled social media monitoring and analytics agent.

What is SocialAgent?

SocialAgent monitors your social media accounts across multiple platforms, collects engagement data, and provides analytics — all accessible via the A2A (Agent-to-Agent) protocol. It has no UI; you interact with it through other A2A-capable agents like RockBot.

Supported Platforms

Platform	Status	API
Mastodon	✅ Implemented	REST API v1
Bluesky	✅ Implemented	AT Protocol
Threads	✅ Implemented	Threads Graph API v1.0 (with auto token refresh)

A2A Skills

Skill	Description
engagement-summary	Engagement metrics across all platforms (likes, reposts, replies, mentions, followers)
top-posts	Your most-engaged posts ranked by total engagement
recent-mentions	Recent mentions and replies
follower-insights	Top engagers and their interaction patterns
platform-comparison	Side-by-side engagement metrics across platforms
check-notifications	Unread notifications across all platforms
provider-status	Health and connectivity of configured providers

Getting Started

Prerequisites

• .NET 10 SDK
• Social media API credentials (see Configuration below)

Build & Run

# Build
dotnet build SocialAgent.slnx

# Run tests
dotnet test SocialAgent.slnx

# Run the agent (development mode — no auth required)
cd src/SocialAgent.Host
dotnet run

The agent starts on http://localhost:5000 by default (or as configured by ASPNETCORE_URLS).

A2A Endpoints

The agent speaks A2A protocol version 1.0.

• GET /.well-known/agent-card.json — Agent card (A2A 1.0 discovery)
• POST /a2a — JSON-RPC binding (SendMessage, GetTask, etc.)
• POST /a2a/message:send, GET /a2a/tasks/{id}, etc. — HTTP+JSON binding
• GET /health/ready — Readiness probe
• GET /health/live — Liveness probe

Configuration

Configure providers via appsettings.json, environment variables, or user secrets:

# Set Mastodon credentials via user secrets
cd src/SocialAgent.Host
dotnet user-secrets set "SocialAgent:Providers:Mastodon:Enabled" "true"
dotnet user-secrets set "SocialAgent:Providers:Mastodon:InstanceUrl" "https://mastodon.social"
dotnet user-secrets set "SocialAgent:Providers:Mastodon:AccessToken" "your-token"

# Set Bluesky credentials
dotnet user-secrets set "SocialAgent:Providers:Bluesky:Enabled" "true"
dotnet user-secrets set "SocialAgent:Providers:Bluesky:Handle" "you.bsky.social"
dotnet user-secrets set "SocialAgent:Providers:Bluesky:AppPassword" "your-app-password"

# Set Threads credentials (long-lived token; auto-refreshes ahead of expiry)
dotnet user-secrets set "SocialAgent:Providers:Threads:Enabled" "true"
dotnet user-secrets set "SocialAgent:Providers:Threads:AccessToken" "your-long-lived-token"

For Threads-specific setup (OAuth scopes, Meta App Review, IncludePostInsights tradeoffs, token-refresh behavior), see docs/providers/threads.md.

Database

• Development: SQLite (default, zero config)
• Production: PostgreSQL (set SocialAgent:DatabaseProvider to PostgreSQL and provide ConnectionStrings:SocialAgent)

Kubernetes Deployment

# Apply manifests
kubectl apply -f deploy/k8s/namespace.yaml
kubectl apply -f deploy/k8s/secret.yaml    # Edit with real credentials first!
kubectl apply -f deploy/k8s/configmap.yaml
kubectl apply -f deploy/k8s/deployment.yaml
kubectl apply -f deploy/k8s/service.yaml

The agent runs as a continuous Deployment (not CronJob) for A2A responsiveness.

Architecture

┌──────────────────────────────────────────────────────────────────────┐
│  SocialAgent.Host (ASP.NET Core)                                     │
│                                                                      │
│  ┌──────────────┐  ┌──────────────────────────────────────────────┐  │
│  │ A2A 1.0      │  │ Background Services                          │  │
│  │ (MS Agent    │  │ ┌───────────┐ ┌──────────┐ ┌──────────────┐ │  │
│  │  Framework + │  │ │ Mastodon  │ │ Bluesky  │ │   Threads    │ │  │
│  │  A2A SDK)    │  │ │ Provider  │ │ Provider │ │   Provider   │ │  │
│  └──────┬───────┘  │ └─────┬─────┘ └────┬─────┘ └──────┬───────┘ │  │
│         │           │       │            │              │         │  │
│         │           │ + ThreadsTokenRefreshService (auto refresh)│  │
│         │           └───────┼────────────┼──────────────┼─────────┘  │
│  ┌──────▼─────────────────  ▼            ▼              ▼─────────┐  │
│  │            Core (Domain Models & Interfaces)                   │  │
│  └─────────────────────────────┬──────────────────────────────────┘  │
│  ┌─────────────────────────────▼──────────────────────────────────┐  │
│  │       Data (EF Core — PostgreSQL / SQLite)                     │  │
│  └────────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────────┘

Adding a New Provider

1. Create src/SocialAgent.Providers.YourPlatform/
2. Implement ISocialMediaProvider
3. Add options class and ServiceCollectionExtensions
4. Register in Program.cs
5. Add configuration section

License

MIT