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

Action ID	Description	Convenience Method
grabWebText	Get text from a webpage	grab_web_text()
grabWebScreenshot	Screenshot a webpage	grab_web_screenshot()
getYoutubeTranscript	Get YouTube video transcript	get_youtube_transcript()
getYoutubeChannel	Get YouTube channel info	get_youtube_channel()
runYoutubeSearch	Search YouTube	search_youtube()
getGoogleNews	Get Google News articles	get_google_news()
getSearchResults	Web search results	search_web()
getLinkedinProfile	Get LinkedIn profile	get_linkedin_profile()
getLinkedinActivity	Get LinkedIn posts	get_linkedin_activity()
getCompanyObject	Company intelligence	get_company_info()
getTwitterUsers	Twitter user info	get_twitter_user()
getRecentTweets	Get recent tweets	get_recent_tweets()
getBlueskyPosts	Get Bluesky posts	get_bluesky_posts()
searchBlueskyPosts	Search Bluesky	search_bluesky()
getInstagramProfile	Instagram profile	get_instagram_profile()
invokeLlm	Chat with LLM	chat()
generateImage	Generate images	generate_image()
outputAudio	Text to speech	text_to_audio()
convertFile	Convert files	convert_file()
convertFileOptions	Get conversion options	get_convert_options()
storeVariableToDatabase	Store variable	store_variable()
getVariableFromDatabase	Get variable	get_variable()
invokeAgent	Call another agent	invoke_agent()
restCall	Make REST API call	rest_call()

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:

Model	Description
gpt4o	OpenAI GPT-4o (default)
gpt4o-mini	OpenAI GPT-4o Mini (faster, cheaper)
claude-sonnet	Anthropic Claude Sonnet
claude-haiku	Anthropic Claude Haiku (faster)
gemini-pro	Google Gemini Pro
gemini-flash	Google Gemini Flash (faster)
llama-70b	Meta Llama 70B
llama-8b	Meta Llama 8B (faster)
deepseek	DeepSeek

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