Skip to main content
A brand intelligence agent that analyzes social media sentiment on X (Twitter), extracting engagement metrics, sentiment trends, and actionable recommendations.

​
Key Concepts

ConceptDescription
Sentiment ClassificationCategorizes tweets as positive, negative, neutral, or mixed
Engagement PatternsDetects viral advocacy, controversy, and influence concentration
Brand Health Score1-10 rating based on sentiment and engagement metrics
Theme ExtractionIdentifies recurring topics and pain points

​
Prerequisites

  • Python 3.12+
  • OpenAI API key
  • X (Twitter) API credentials

​
Setup

1

Clone the repository

git clone https://github.com/agno-agi/agno.git
cd agno
2

Create and activate virtual environment

uv venv --python 3.12
source .venv/bin/activate
3

Install dependencies

uv pip install -r cookbook/01_showcase/01_agents/social_media_analyst/requirements.in
4

Get X API credentials

  1. Go to the X Developer Portal
  2. Create a project and app
  3. Generate API keys and access tokens
5

Set environment variables

export OPENAI_API_KEY=your-openai-key

# Option 1: Bearer token (simpler)
export X_BEARER_TOKEN=your-bearer-token

# Option 2: Full OAuth credentials
export X_API_KEY=your-api-key
export X_API_SECRET=your-api-secret
export X_ACCESS_TOKEN=your-access-token
export X_ACCESS_SECRET=your-access-secret

​
Run the Agent

​
Brand Analysis

Analyze sentiment for a brand: 
python cookbook/01_showcase/01_agents/social_media_analyst/examples/brand_analysis.py
Demonstrates:
  • Retrieving tweets for a brand
  • Sentiment classification
  • Brand health scoring

​
Competitor Comparison

Compare sentiment across brands: 
python cookbook/01_showcase/01_agents/social_media_analyst/examples/competitor_compare.py
Demonstrates:
  • Multi-brand analysis
  • Comparative sentiment metrics
  • Competitive positioning insights
Analyze a trending topic: 
python cookbook/01_showcase/01_agents/social_media_analyst/examples/trending_topic.py

​
Agent Configuration

social_media_agent = Agent(
    name="Social Media Analyst",
    model=OpenAIResponses(id="gpt-5.2"),
    system_message=SYSTEM_MESSAGE,
    output_schema=SocialMediaReport,
    tools=[
        XTools(
            include_post_metrics=True,
            wait_on_rate_limit=True,
        ),
        ReasoningTools(add_instructions=True),
    ],
    add_datetime_to_context=True,
    add_history_to_context=True,
    num_history_runs=5,
    enable_agentic_memory=True,
    markdown=True,
)
ParameterPurpose
modelGPT for sentiment analysis and synthesis
output_schemaStructured report with sentiment data
XToolsX API integration for tweet retrieval
include_post_metricsGet likes, retweets, replies
wait_on_rate_limitHandle API rate limits gracefully
ReasoningToolsPlan analysis approach

​
How It Works

​
Analysis Workflow

1. Search X for brand/topic mentions
2. Retrieve tweets with engagement metrics
3. Classify sentiment per tweet
4. Detect engagement patterns
5. Extract thematic clusters
6. Identify risks and opportunities
7. Generate prioritized recommendations

​
Sentiment Classification

CategoryIndicators
PositivePraise, recommendations, satisfaction
NegativeComplaints, frustration, criticism
NeutralInformation sharing, questions, news
MixedContains both positive and negative

​
Brand Health Score

ScoreMeaning
9-10Overwhelmingly positive, strong advocacy
7-8Mostly positive, minor issues
5-6Mixed sentiment, notable concerns
3-4Predominantly negative, significant issues
1-2Crisis level negativity

​
Troubleshooting

Verify all four environment variables are set:
echo $X_API_KEY
echo $X_API_SECRET
echo $X_ACCESS_TOKEN
echo $X_ACCESS_SECRET
The agent is configured with wait_on_rate_limit=True. For high-volume analysis, consider spacing requests or using X API premium tiers.
Some brands may have fewer tweets. The agent will analyze available data and note limitations in the report.

​
Source Code