tessa-sdk 0.1.0

Python SDK for the Tessa Browser Agent & Workflows API

Tessa SDK for Python

The official Python SDK for the Tessa Browser Agent API - AI-powered browser automation with 93% accuracy on WebVoyager.

🚀 Quick Start

pip install tessa_sdk

from tessa_sdk import BrowserAgent

# One-line browser automation
result = BrowserAgent("YOUR_API_KEY").run("Go to news.ycombinator.com and get the top 5 stories")
print(result.output)

📚 Features

• 🎯 One-Line Interface - Run browser automation with a single line of code
• 🔄 Sync & Async Clients - Both synchronous and asynchronous APIs available
• 🧠 Multiple AI Models - Claude, GPT-4, or Gemini for action selection
• 🌐 Residential IPs - Access geo-restricted content
• 📊 Real-time Monitoring - Watch your browser agent work live
• 📝 Type Safety - Full type hints for better IDE support
• 🛡️ Thread-Safe - Sync client works in any environment

🔑 Authentication

Get your API key from app.heytessa.ai/settings

# Method 1: Pass directly
agent = BrowserAgent("YOUR_API_KEY")

# Method 2: Environment variable
export TESSA_API_KEY="YOUR_API_KEY"
agent = BrowserAgent()  # Uses env var

🎯 Usage Examples

Simple Usage

from tessa_sdk import BrowserAgent

agent = BrowserAgent("YOUR_API_KEY")

# Extract data from a website
result = agent.run("Go to example.com and extract the main heading")

# Extract specific data
result = agent.extract(
    url="https://github.com/trending",
    data_description="repository names and star counts"
)

# Search and extract
result = agent.search_and_extract("Python tutorials", num_results=10)

# Fill forms
result = agent.fill_form(
    url="https://example.com/contact",
    form_data={"name": "John", "email": "[e-mail]"}
)

Synchronous Client

from tessa_sdk import TessaClient, BrowserConfig

# Using context manager for automatic cleanup
with TessaClient(api_key="YOUR_API_KEY") as client:
    # Run and wait for completion
    result = client.run_and_wait(
        directive="Extract pricing data from the products page",
        browser_config=BrowserConfig(
            width=1920,
            height=1080,
            residential_ip=True
        ),
        verbose=True
    )
    print(f"Output: {result.output}")
    print(f"Credits used: {result.credits_used}")

# Or manage jobs manually
client = TessaClient(api_key="YOUR_API_KEY")
job = client.run_browser_agent(
    directive="Extract data from multiple pages",
    initial_url="https://shop.example.com"
)

# Monitor progress
print(f"Watch live: {job.live_url}")

# Wait for completion
result = job.wait_for_completion(poll_interval=3.0)
print(f"Output: {result.output}")

client.close()

Async Operations

import asyncio
from tessa_sdk import AsyncTessaClient

async def run_multiple():
    async with AsyncTessaClient(api_key="YOUR_API_KEY") as client:
        # Start multiple jobs concurrently
        jobs = await asyncio.gather(
            client.run_browser_agent("Extract from site1.com"),
            client.run_browser_agent("Extract from site2.com"),
            client.run_browser_agent("Extract from site3.com")
        )
        
        # Wait for all to complete
        results = await asyncio.gather(
            *[job.wait_for_completion() for job in jobs]
        )
        
        for result in results:
            print(result.output)

asyncio.run(run_multiple())

📖 API Reference

BrowserAgent

Simple interface for one-line automation:

agent = BrowserAgent(
    api_key="YOUR_API_KEY",
    residential_ip=False,
    viewport_width=1920,
    viewport_height=1080,
    max_duration_minutes=30,
    model="claude-sonnet-4-20250514",
    verbose=False
)

result = agent.run(directive, initial_url=None, timeout=None)

TessaClient

Full-featured client with job management:

client = TessaClient(api_key="YOUR_API_KEY")

job = client.run_browser_agent(
    directive="Your instruction",
    browser_config={...}
)

status = client.get_job_status(job_id)
result = job.wait_for_completion()

Models

from tessa_sdk import BrowserConfig, ActionSelectionModel

config = BrowserConfig(
    width=1920,              # 320-4096
    height=1080,             # 320-4096  
    residential_ip=False,
    max_duration_minutes=30, # 1-240
    idle_timeout_minutes=2   # 1-60
)

# AI Models
ActionSelectionModel.CLAUDE_SONNET  # Default
ActionSelectionModel.GPT_4O
ActionSelectionModel.GEMINI_FLASH

🛡️ Error Handling

from tessa_sdk.exceptions import *

try:
    result = agent.run("Extract data")
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except TimeoutError as e:
    print(f"Timed out after {e.timeout_seconds}s")
except JobFailedError as e:
    print(f"Job failed: {e.error_message}")

📂 Examples

See the examples/ directory:

• quickstart.py - Simple one-line usage
• sync_example.py - Synchronous client examples
• async_example.py - Concurrent async operations
• web_scraping.py - Various scraping scenarios
• advanced_config.py - Advanced features

🏗️ Common Use Cases

E-commerce Monitoring

result = agent.run("""
    Search amazon.com for 'iPhone 15 Pro'.
    Extract prices and availability for top 5 results.
""")

Social Media Analytics

result = agent.run("""
    Go to twitter.com/elonmusk and extract
    the last 5 tweets with likes and retweets.
""")

Job Aggregation

result = agent.run("""
    Search indeed.com for 'Python Developer' in SF.
    Filter: Remote, $150k+. Extract top 10 jobs.
""")

💳 Credits

• 1 credit per browser action
• 1,000 free credits for new accounts
• Check balance: app.heytessa.ai/settings

result = agent.run("Your task")
print(f"Credits used: {result.credits_used}")

📞 Support

• Docs: docs.heytessa.ai
• Email: [e-mail]
• Issues: GitHub Issues

📄 License

MIT License - see LICENSE for details.

---

Built with ❤️ by the General Agency team