Build a Social Media Intelligence Agent with Agno, X Tools, and Exa

In this tutorial, we will build a multi-agent intelligence system. It will monitor X (Twitter), perform sentiment analysis, and generate reports using Agno framework. We will be using the following components:

Agno - The fastest framework for building agents.
X Tools - Provides real-time, structured data directly from Twitter/X API with engagement metrics
Exa Tools - Deliver semantic web search for broader context discovery across blogs, forums, and news
GPT-5 Mini - OpenAI’s new model. Well suited for contextually-aware sentiment analysis and strategic pattern detection

This system will combine direct social media data with broader web intelligence, to provide comprehensive brand monitoring that captures both immediate social sentiment and emerging discussions before they reach mainstream attention.

What You’ll Build

Your social media intelligence system will:

Track brand and competitor mentions across X and the broader web
Perform weighted sentiment analysis that accounts for influence and engagement
Detect viral content, controversy signals, and high-influence discussions
Generate executive-ready reports with strategic recommendations
Serve insights via AgentOS API for integration with your applications

Prerequisites and Setup

Before we get started, we need to setup our environment:

Install Python, Git and get your API keys:

Install Python >= 3.9 and Git
Get API keys for:
- X (Twitter) Developer Account (Apply here)
- OpenAI API (Get key)
- Exa API (Sign up)

Setup your Python environment:

mkdir social-intel && cd social-intel
python3 -m venv venv
source venv/bin/activate     # If you are on Windows, use: venv\Scripts\activate

Install our Python dependencies:

# Install dependencies
pip install "agno[infra]" openai exa_py python-dotenv

4. Create a new project with [AgentOS](/agent-os/introduction):

```bash
ag infra create              # Choose: [1] agent-infra-docker (default)
# Infra Name: social-intel

Set your environment variables:

export OPENAI_API_KEY=sk-your-openai-api-key-here
export X_API_KEY=your-x-api-key
export X_API_SECRET=your-x-api-secret
export X_ACCESS_TOKEN=your-access-token
export X_ACCESS_TOKEN_SECRET=your-access-token-secret
export X_BEARER_TOKEN=your-bearer-token
export EXA_API_KEY=your-exa-api-key

Our environment is now ready. Let’s start building!

Step 1: Choose Your AI Model

Which model should I use?: You can choose any model from our supported providers. Normally models are chosen based on costs and performance. In this case, we will be using OpenAI’s GPT-5 Mini. Why GPT-5 Mini?

Cost-effective: Better price/performance ratio than other GPT models
Tool usage: Excellent at deciding when and how to use tools
Complex reasoning: Can follow detailed analysis methodologies
Structured output: Reliable at generating formatted reports

Let’s first create the file where we will define our agent:

mkdir -p app
touch app/social_media_agent.py

Now let’s add the basic imports and model setup:

from pathlib import Path
from dotenv import load_dotenv
from agno.models.openai import OpenAIChat

# Load infrastructure secrets
load_dotenv(dotenv_path=Path(__file__).resolve().parents[1] / "infra" / "secrets" / ".env")

# Choose the AI model for your agent
model = OpenAIChat(id="gpt-5-mini")
print(f"Model selected: {model.id}")

We can now test our model setup:

# Quick test to verify model works
if __name__ == "__main__":
    test_response = model.invoke("Explain social media sentiment analysis in one sentence.")
    print(f"Model test: {test_response}")

This confirms your model is working, before we add more complexity. Which tools should I use? We are adding XTools because we need direct Twitter/X data with engagement metrics, and ExaTools because we need broader web context that social media alone can’t provide.

2a. Add XTools for Twitter/X Data

Why XTools? Direct access to Twitter/X with engagement metrics is crucial for understanding influence patterns and viral content.

from agno.tools.x import XTools

# Configure X Tools for social media data
x_tools = XTools(
    include_post_metrics=True,    # Critical: gets likes, retweets, replies for influence analysis
    wait_on_rate_limit=True,      # Handles API limits gracefully
)

print("XTools configured with post metrics enabled")

What include_post_metrics=True gives you:

Like counts (engagement volume)
Retweet counts (viral spread)
Reply counts (conversation depth)
Author verification status (influence weighting)

2b. Add ExaTools for Web Intelligence

Why ExaTools? Social media discussions often reference broader conversations happening across the web. ExaTools finds this context.

from agno.tools.exa import ExaTools

# Configure Exa for broader web intelligence
exa_tools = ExaTools(
    num_results=10,               # Comprehensive but not overwhelming
    include_domains=["reddit.com", "news.ycombinator.com", "medium.com"],
)

print("ExaTools configured for web search")

Why these specific domains?

Reddit: Early discussion indicators, community sentiment
HackerNews: Tech industry insights, developer opinions
Medium: Thought leadership, analysis articles

Step 3: Define Intelligence Strategy

Why do we need instructions? We need to describe the strategy that the agent should take to collect and analyze content. Without clear instructions, the agent won’t know how to use the tools effectively or what kind of analysis to provide.

3a. Define the Data Collection Strategy

from textwrap import dedent

# Define how the agent should gather data
data_collection_strategy = dedent("""
    DATA COLLECTION STRATEGY:
    - Use X Tools to gather direct social media mentions with full engagement metrics
    - Use Exa Tools to find broader web discussions, articles, and forum conversations
    - Cross-reference findings between social and web sources for comprehensive coverage
""")

print("Data collection strategy defined")

3b. Define the Analysis Framework

# Define how the agent should analyze the data
analysis_framework = dedent("""
    ANALYSIS FRAMEWORK:
    - Classify sentiment as Positive/Negative/Neutral/Mixed with detailed reasoning
    - Weight analysis by engagement volume and author influence (verified accounts = 1.5x)
    - Identify engagement patterns: viral advocacy, controversy, influence concentration
    - Extract cross-platform themes and recurring discussion points
""")

print("Analysis framework defined")

3c. Define the Intelligence Synthesis

# Define how to turn analysis into actionable insights
intelligence_synthesis = dedent("""
    INTELLIGENCE SYNTHESIS:
    - Detect crisis indicators through sentiment velocity and coordination patterns
    - Identify competitive positioning and feature gap discussions
    - Surface growth opportunities and advocacy moments
    - Generate strategic recommendations with clear priority levels
""")

print("Intelligence synthesis defined")

3d. Define the Report Format

# Define the expected output structure
report_format = dedent("""
    REPORT FORMAT:

    ### Executive Dashboard
    - **Brand Health Score**: [1-10] with supporting evidence
    - **Net Sentiment**: [%positive - %negative] with trend analysis
    - **Key Drivers**: Top 3 positive and negative factors
    - **Alert Level**: Normal/Monitor/Crisis with threshold reasoning

    ### Quantitative Metrics
    | Sentiment | Posts | % | Avg Engagement | Influence Score |
    |-----------|-------|---|----------------|-----------------|
    [Detailed breakdown with engagement weighting]

    ### Strategic Recommendations
    **IMMEDIATE (≤48h)**: Crisis response, high-impact replies
    **SHORT-TERM (1-2 weeks)**: Content strategy, community engagement
    **LONG-TERM (1-3 months)**: Product positioning, market strategy
""")

print("Report format defined")

3e. Define Analysis Principles

# Define the quality standards for analysis
analysis_principles = dedent("""
    ANALYSIS PRINCIPLES:
    - Evidence-based conclusions with supporting metrics
    - Actionable insights that drive business decisions
    - Cross-platform correlation analysis
    - Influence-weighted sentiment scoring
    - Proactive risk and opportunity identification
""")

print("Analysis principles defined")

3f. Combine Into Complete Instructions

# Combine all instruction components
complete_instructions = f"""
You are a Senior Social Media Intelligence Analyst specializing in cross-platform
brand monitoring and strategic analysis.

CORE METHODOLOGY:

{data_collection_strategy}

{analysis_framework}

{intelligence_synthesis}

{report_format}

{analysis_principles}
"""

print(f"Complete instructions created: {len(complete_instructions)} characters")

Step 4: Create the Complete Agent

Now let’s put all the pieces together - model, tools, and instructions - to create your complete social media intelligence agent.

4a. Create the Agent

from agno.agent import Agent

# Combine model, tools, and instructions into a complete agent
social_media_agent = Agent(
    name="Social Media Intelligence Analyst",
    model=model,                 # The GPT-5 mini model we chose
    tools=tools,                 # The X and Exa tools we configured
    instructions=complete_instructions,  # The strategy we defined
    markdown=True,               # Enable rich formatting for reports
    show_tool_calls=True,        # Show transparency in data collection
)

print(f"Agent created: {social_media_agent.name}")

For detailed information about each Agent parameter, see the Agent Reference Documentation.

4b. Create the Analysis Function

def analyze_brand_sentiment(query: str, tweet_count: int = 20):
    """
    Execute comprehensive social media intelligence analysis.

    Args:
        query: Brand or topic search query (e.g., "Tesla OR @elonmusk")
        tweet_count: Number of recent tweets to analyze
    """

    # Create a detailed prompt for the agent
    analysis_prompt = f"""
    Conduct comprehensive social media intelligence analysis for: "{query}"

    ANALYSIS PARAMETERS:
    - Twitter Analysis: {tweet_count} most recent tweets with engagement metrics
    - Web Intelligence: Related articles, discussions, and broader context via Exa
    - Cross-Platform Synthesis: Correlate social sentiment with web discussions
    - Strategic Focus: Brand positioning, competitive analysis, risk assessment

    METHODOLOGY:
    1. Gather direct social media mentions and engagement data
    2. Search for related web discussions and broader context
    3. Analyze sentiment patterns and engagement indicators
    4. Identify cross-platform themes and influence networks
    5. Generate strategic recommendations with evidence backing

    Provide comprehensive intelligence report following the structured format.
    """

    # Execute the analysis
    return social_media_agent.print_response(analysis_prompt, stream=True)

print("Analysis function created")

4c. Create a Test Function

def test_agent():
    """Test the complete agent with a sample query."""
    print("Testing social media intelligence agent...")
    analyze_brand_sentiment("Agno OR AgnoAGI", tweet_count=10)

print("Test function ready")

4d. Complete Working Example

Here’s your complete app/social_media_agent.py file:

"""
Complete Social Media Intelligence Agent
Built with Agno framework
"""
from pathlib import Path
from textwrap import dedent
from dotenv import load_dotenv

from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno.tools.x import XTools
from agno.tools.exa import ExaTools

# Load infrastructure secrets
load_dotenv(dotenv_path=Path(__file__).resolve().parents[1] / "infra" / "secrets" / ".env")

# Step 1: Choose the AI model
model = OpenAIChat(id="gpt-5-mini")

# Step 2: Configure tools
tools = [
    XTools(
        include_post_metrics=True,
        wait_on_rate_limit=True,
    ),
    ExaTools(
        num_results=10,
        include_domains=["reddit.com", "news.ycombinator.com", "medium.com"],
        exclude_domains=["spam-site.com"],
    )
]

# Step 3: Define instructions
complete_instructions = dedent("""
    You are a Senior Social Media Intelligence Analyst specializing in cross-platform
    brand monitoring and strategic analysis.

    CORE METHODOLOGY:

    DATA COLLECTION STRATEGY:
    - Use X Tools to gather direct social media mentions with full engagement metrics
    - Use Exa Tools to find broader web discussions, articles, and forum conversations
    - Cross-reference findings between social and web sources for comprehensive coverage

    ANALYSIS FRAMEWORK:
    - Classify sentiment as Positive/Negative/Neutral/Mixed with detailed reasoning
    - Weight analysis by engagement volume and author influence (verified accounts = 1.5x)
    - Identify engagement patterns: viral advocacy, controversy, influence concentration
    - Extract cross-platform themes and recurring discussion points

    INTELLIGENCE SYNTHESIS:
    - Detect crisis indicators through sentiment velocity and coordination patterns
    - Identify competitive positioning and feature gap discussions
    - Surface growth opportunities and advocacy moments
    - Generate strategic recommendations with clear priority levels

    REPORT FORMAT:

    ### Executive Dashboard
    - **Brand Health Score**: [1-10] with supporting evidence
    - **Net Sentiment**: [%positive - %negative] with trend analysis
    - **Key Drivers**: Top 3 positive and negative factors
    - **Alert Level**: Normal/Monitor/Crisis with threshold reasoning

    ### Quantitative Metrics
    | Sentiment | Posts | % | Avg Engagement | Influence Score |
    |-----------|-------|---|----------------|-----------------|
    [Detailed breakdown with engagement weighting]

    ### Strategic Recommendations
    **IMMEDIATE (≤48h)**: Crisis response, high-impact replies
    **SHORT-TERM (1-2 weeks)**: Content strategy, community engagement
    **LONG-TERM (1-3 months)**: Product positioning, market strategy

    ANALYSIS PRINCIPLES:
    - Evidence-based conclusions with supporting metrics
    - Actionable insights that drive business decisions
    - Cross-platform correlation analysis
    - Influence-weighted sentiment scoring
    - Proactive risk and opportunity identification
""")

# Step 4: Create the complete agent
social_media_agent = Agent(
    name="Social Media Intelligence Analyst",
    model=model,
    tools=tools,
    instructions=complete_instructions,
    markdown=True,
    show_tool_calls=True,
)

def analyze_brand_sentiment(query: str, tweet_count: int = 20):
    """Execute comprehensive social media intelligence analysis."""
    prompt = f"""
    Conduct comprehensive social media intelligence analysis for: "{query}"

    ANALYSIS PARAMETERS:
    - Twitter Analysis: {tweet_count} most recent tweets with engagement metrics
    - Web Intelligence: Related articles, discussions, and broader context via Exa
    - Cross-Platform Synthesis: Correlate social sentiment with web discussions
    - Strategic Focus: Brand positioning, competitive analysis, risk assessment

    METHODOLOGY:
    1. Gather direct social media mentions and engagement data
    2. Search for related web discussions and broader context
    3. Analyze sentiment patterns and engagement indicators
    4. Identify cross-platform themes and influence networks
    5. Generate strategic recommendations with evidence backing

    Provide comprehensive intelligence report following the structured format.
    """

    return social_media_agent.print_response(prompt, stream=True)

if __name__ == "__main__":
    # Test the complete agent
    analyze_brand_sentiment("Agno OR AgnoAGI", tweet_count=25)

4e. Spin-up the infrastructure for our project:

Now that we have completed our agent, we can spin-up the infrastructure for our project:

ag infra up

Your AgentOS API is now running. We are ready to start building!

4f. Test Your Complete Agent

python app/social_media_agent.py

You should see your agent:

Use X Tools to gather Twitter data with engagement metrics
Use Exa Tools to find broader web context
Generate a structured report following your defined format
Provide strategic recommendations based on the analysis

Step 5: Test and experiment via AgentOS

Why API-first? The AgentOS infrastructure automatically exposes your agent as a REST API, making it ready for production integration without additional deployment work. Your agent is automatically available via the AgentOS API. Let’s test it! Find your API endpoint:

# Your AgentOS API is running on localhost:7777
curl http://localhost:7777/v1/agents

Test with Postman or curl:

curl -X POST http://localhost:7777/v1/agents/social_media_agent/runs \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Analyze social media sentiment for: Tesla OR @elonmusk",
    "stream": false
  }'

Expected response structure:

{
  "run_id": "run_123",
  "content": "### Executive Dashboard\n- **Brand Health Score**: 7.2/10...",
  "metrics": {
    "tokens_used": 1250,
    "tools_called": ["x_tools", "exa_tools"],
    "analysis_time": "23.4s"
  }
}

Next Steps

Your social media intelligence system is now live with a production-ready API! Consider these as possible next steps to extend this system:

Specialized Agents: Create focused agents for crisis detection, competitive analysis, or influencer identification
Alert Integration: Connect webhooks to Slack, email, or your existing monitoring systems
Visual Analytics: Build dashboards that consume the API for executive reporting
Multi-Brand Monitoring: Scale to monitor multiple brands or competitors simultaneously

Conclusion

You’ve built a comprehensive social media intelligence system that:

Combines direct social data with broader web intelligence
Provides weighted sentiment analysis with strategic recommendations
Serves insights via production-ready AgentOS API
Scales from development through enterprise deployment

This demonstrates Agno’s infrastructure-first approach, where your AI agents become immediately deployable services with proper monitoring, scaling, and integration capabilities built-in.

Tutorials

​What You’ll Build

​Prerequisites and Setup

​Building our Social Media Intelligence System

​Step 1: Choose Your AI Model

​Step 2: Add Social Media Tools

​2a. Add XTools for Twitter/X Data

​2b. Add ExaTools for Web Intelligence

​Step 3: Define Intelligence Strategy

​3a. Define the Data Collection Strategy

​3b. Define the Analysis Framework

​3c. Define the Intelligence Synthesis

​3d. Define the Report Format

​3e. Define Analysis Principles

​3f. Combine Into Complete Instructions

​Step 4: Create the Complete Agent

​4a. Create the Agent

​4b. Create the Analysis Function

​4c. Create a Test Function

​4d. Complete Working Example

​4e. Spin-up the infrastructure for our project:

​4f. Test Your Complete Agent

​Step 5: Test and experiment via AgentOS

​Next Steps

​Conclusion