agentai

agent.ai Python SDK

A simple and powerful Python library for interacting with the Agent.ai Actions API.

Features

• 🔑 Easy Authentication - Use environment variables or pass token directly
• 🚀 Convenience Methods - Simple methods for common actions
• 🛡️ Robust Error Handling - Clear error messages from the API
• 📝 Well Documented - Comprehensive examples and docstrings
• 🔧 Flexible - Use convenience methods or raw action calls
• 🤖 LLM-Friendly - Includes llm.txt specification for AI assistants

Installation

pip install agentai

Quick Start

1. Get Your API Key

Sign up at Agent.ai and get your Bearer token from account settings.

2. Set Up Authentication

Option A: Environment Variable (Recommended)

export AGENTAI_API_KEY="your_api_key_here"

Option B: Pass Token Directly

from agentai import AgentAiClient
client = AgentAiClient(bearer_token="your_api_key_here")

3. Start Using the API

from agentai import AgentAiClient

client = AgentAiClient()  # Uses AGENTAI_API_KEY env var

# Chat with an LLM
response = client.chat("What is machine learning?")
if response['status'] == 200:
    print(response['results'])

Usage Examples

Chat with LLMs

from agentai import AgentAiClient

client = AgentAiClient()

# Simple chat
response = client.chat("Explain quantum computing in simple terms")
print(response['results'])

# Specify a model
response = client.chat(
    prompt="Write a haiku about coding",
    model="claude-sonnet"  # Options: gpt4o, gpt4o-mini, claude-sonnet, claude-haiku, 
                           # gemini-pro, gemini-flash, llama-70b, llama-8b, deepseek
)
print(response['results'])

Web Scraping

# Get text from a webpage
response = client.grab_web_text("https://example.com")
if response['status'] == 200:
    print(response['results'])

# Take a screenshot
response = client.grab_web_screenshot("https://example.com", full_page=True)
if response['status'] == 200:
    print(f"Screenshot URL: {response['results']}")

YouTube

# Get video transcript
response = client.get_youtube_transcript("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
print(response['results'])

# Search YouTube
response = client.search_youtube("python tutorials", max_results=5)
for video in response['results']:
    print(video['title'])

# Get channel info
response = client.get_youtube_channel("https://www.youtube.com/@PythonTutorials")
print(response['results'])

Social Media

# LinkedIn
response = client.get_linkedin_profile("company/hubspot")
print(response['results'])

# Twitter/X
response = client.get_recent_tweets("elonmusk", count=5)
for tweet in response['results']:
    print(tweet['text'])

# Bluesky
response = client.get_bluesky_posts("user.bsky.social", count=10)
print(response['results'])

# Instagram
response = client.get_instagram_profile("instagram")
print(response['results'])

News & Search

# Google News
response = client.get_google_news(
    query="artificial intelligence",
    date_range="7d",  # Options: 1d, 7d, 30d, 1y
    location="US"
)
for article in response['results'].get('organic_results', []):
    print(f"- {article['title']}")

# Web Search
response = client.search_web("best python libraries 2024", num_results=10)
print(response['results'])

Company Intelligence

# Get company info from domain
response = client.get_company_info("hubspot.com")
if response['status'] == 200:
    company = response['results']
    print(f"Name: {company.get('name')}")
    print(f"Industry: {company.get('category', {}).get('industry')}")
    print(f"Employees: {company.get('metrics', {}).get('employeesRange')}")

Image Generation

response = client.generate_image(
    prompt="A futuristic city with flying cars",
    model="DALL-E 3",        # or "Stable Diffusion"
    style="digital art",
    aspect_ratio="16:9"      # Options: 1:1, 16:9, 9:16, 4:3, 3:4
)
if response['status'] == 200:
    print(f"Image URL: {response['results']['images'][0]['url']}")

Text to Speech

response = client.text_to_audio(
    text="Hello, welcome to agent.ai!",
    voice="alloy"
)
if response['status'] == 200:
    print(f"Audio URL: {response['results']}")

File Conversion

# Check available conversion formats
response = client.get_convert_options("pdf")
print(f"PDF can be converted to: {response['results']}")

# Convert a file
response = client.convert_file(
    file_url="https://example.com/document.pdf",
    target_format="txt"
)
if response['status'] == 200:
    print(f"Converted file: {response['results']}")

Database Variables

# Store a variable
client.store_variable("user_preference", "dark_mode")

# Retrieve a variable
response = client.get_variable("user_preference")
print(response['results'])

REST API Calls

response = client.rest_call(
    url="https://api.example.com/data",
    method="POST",
    headers={"X-Custom-Header": "value"},
    body={"key": "value"}
)
print(response['results'])

Using Raw Actions

For full flexibility, use the action() method directly:

response = client.action(
    action_id="getGoogleNews",
    params={
        "query": "AI news",
        "date_range": "7d",
        "location": "Boston"
    }
)
print(response['results'])

Available Actions

Error Handling

All methods return a dictionary with the following structure:

{
    "status": 200,           # HTTP status code (or None for connection errors)
    "error": None,           # Error message (or None if successful)
    "results": {...},        # API response data (or None if error)
    "metadata": {...}        # Additional metadata (if available)
}

Example Error Handling

response = client.chat("Hello!")

if response['status'] == 200:
    print(f"Success: {response['results']}")
elif response['status'] == 403:
    print("Authentication failed. Check your API key.")
elif response['status'] == 429:
    print("Rate limited. Please wait and try again.")
elif response['status'] is None:
    print(f"Connection error: {response['error']}")
else:
    print(f"Error {response['status']}: {response['error']}")

Examples

See the examples/ directory for complete, runnable examples:

• interactive_chat.py - Chat with different LLM models
• youtube_summary.py - Summarize YouTube videos
• lead_enrichment.py - Enrich leads with company & LinkedIn data
• brand_news_monitor.py - Monitor Google News for brand mentions
• competitor_analysis.py - Analyze competitor websites & social presence
• social_media_content.py - Generate social posts with images
• faq_chatbot.py - Build a chatbot from website content
• sales_email_subject.py - Generate email subject lines
• file_conversion.py - Convert files between formats
• website_monitor.py - Monitor websites for changes
• web_search.py - Search the web and analyze results
• bluesky_monitor.py - Monitor Bluesky posts

LLM Models

Available models for the chat() method:

For AI Assistants (llm.txt)

This package includes an llm.txt file - a comprehensive specification designed for LLM assistants (like ChatGPT, Claude, Copilot, etc.) to understand and use this SDK effectively.

The llm.txt file contains:

• Complete API reference with all methods and parameters
• Response format documentation
• Common use case examples (research assistant, social monitor, content generator, etc.)
• Error handling patterns
• Tips for optimal usage

For AI coding assistants: Reference the llm.txt file when helping users write code with this SDK.

Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues for feature requests or bug reports.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Links

• Agent.ai Website
• API Documentation
• Get API Key
• GitHub Repository
• LLM Specification - For AI assistants