# Agent

## Automate

`agent.automate(AgentAutomateParams**kwargs)  -> AutomateEvent`

**post** `/automate`

Execute AI-powered browser automation tasks using natural language with optional geotargeting. This endpoint **always streams** responses using Server-Sent Events (SSE).

**Streaming Response:**

- All responses are streamed using Server-Sent Events (`text/event-stream`)
- Real-time progress updates and results as they're generated

**Geotargeting:**

- Optionally specify a country code for geotargeted browsing

**Use Cases:**

- Web scraping and data extraction
- Form filling and interaction
- Navigation and information gathering
- Multi-step web workflows
- Content analysis from web pages

### Parameters

- `task: str`

  The task description in natural language

- `data: Optional[object]`

  JSON data to provide context for form filling or complex tasks

- `geo_target: Optional[GeoTarget]`

  Optional geotargeting parameters for proxy requests

  - `country: Optional[str]`

    Country code using ISO 3166-1 alpha-2 standard (2 letters, e.g., "US", "GB", "JP").
    See: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2

- `guardrails: Optional[str]`

  Safety constraints for execution

- `max_iterations: Optional[int]`

  Maximum task iterations

- `max_validation_attempts: Optional[int]`

  Maximum validation attempts

- `url: Optional[str]`

  Starting URL for the task

### Returns

- `class AutomateEvent: …`

  - `data: Optional[object]`

    Event payload data

  - `event: Optional[str]`

    The event type (e.g., start, agent:processing, complete)

### Example

```python
import os
from tabstack import Tabstack

client = Tabstack(
    api_key=os.environ.get("TABSTACK_API_KEY"),  # This is the default and can be omitted
)
automate_event = client.agent.automate(
    task="Find the top 3 trending repositories and extract their names, descriptions, and star counts",
    guardrails="browse and extract only, don't interact with repositories",
    url="https://github.com/trending",
)
print(automate_event.data)
```

## Research

`agent.research(AgentResearchParams**kwargs)  -> ResearchEvent`

**post** `/research`

Execute AI-powered research queries that search the web, analyze sources, and synthesize comprehensive answers. This endpoint **always streams** responses using Server-Sent Events (SSE).

**Streaming Response:**

- All responses are streamed using Server-Sent Events (`text/event-stream`)
- Real-time progress updates as research progresses through phases

**Research Modes:**

- `fast` - Quick answers with minimal web searches
- `balanced` - Standard research with multiple iterations (default)

**Use Cases:**

- Answering complex questions with cited sources
- Synthesizing information from multiple web sources
- Research reports on specific topics
- Fact-checking and verification tasks

### Parameters

- `query: str`

  The research query or question to answer

- `fetch_timeout: Optional[int]`

  Timeout in seconds for fetching web pages

- `mode: Optional[Literal["fast", "balanced"]]`

  Research mode: fast (quick answers), balanced (standard research, default)

  - `"fast"`

  - `"balanced"`

- `nocache: Optional[bool]`

  Skip cache and force fresh research

### Returns

- `class ResearchEvent: …`

  - `data: Optional[object]`

    Event payload data

  - `event: Optional[Literal["phase", "progress", "complete", "error"]]`

    The event type: phase, progress, complete, or error

    - `"phase"`

    - `"progress"`

    - `"complete"`

    - `"error"`

### Example

```python
import os
from tabstack import Tabstack

client = Tabstack(
    api_key=os.environ.get("TABSTACK_API_KEY"),  # This is the default and can be omitted
)
research_event = client.agent.research(
    query="What are the latest developments in quantum computing?",
)
print(research_event.data)
```

## Domain Types

### Automate Event

- `class AutomateEvent: …`

  - `data: Optional[object]`

    Event payload data

  - `event: Optional[str]`

    The event type (e.g., start, agent:processing, complete)

### Research Event

- `class ResearchEvent: …`

  - `data: Optional[object]`

    Event payload data

  - `event: Optional[Literal["phase", "progress", "complete", "error"]]`

    The event type: phase, progress, complete, or error

    - `"phase"`

    - `"progress"`

    - `"complete"`

    - `"error"`