agi-python 0.0.1__tar.gz → 0.5.0__tar.gz

agi_python-0.5.0/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+## [0.4.1](https://github.com/agi-inc/agi-python/compare/v0.4.0...v0.4.1) (2026-02-06)
+
+
+### Features
+
+* add agi python sdk ([1440466](https://github.com/agi-inc/agi-python/commit/14404667032849e3835e3d40db7ca346a03c8474))
+* add client-driven session support with AgentLoop ([0165ae7](https://github.com/agi-inc/agi-python/commit/0165ae73adceaefd7008f8bb47e01780a58982eb))
+* Add client-driven session support with AgentLoop ([f3d024e](https://github.com/agi-inc/agi-python/commit/f3d024e1a0cfbc49a761f9ebc8745bdcb5af67a0))
+* add Task response models ([1021036](https://github.com/agi-inc/agi-python/commit/10210367ba4df2022131dadb40901fa923c9d357))
+* agi-python sdk ([0fe2e32](https://github.com/agi-inc/agi-python/commit/0fe2e3227d6a254aeb302e9b5262aa5013320d35))
+* **ci:** add release-please workflow for automated releases ([f25ca3f](https://github.com/agi-inc/agi-python/commit/f25ca3fe8601873dc8f96408900a3a0bdd7b3c59))
+* **ci:** add release-please workflow for automated releases ([9da9c57](https://github.com/agi-inc/agi-python/commit/9da9c57ccbe4b51fa0ac3b72438587eb362c2d06))
+* **driver:** Add driver module for binary execution ([#5](https://github.com/agi-inc/agi-python/issues/5)) ([33588e6](https://github.com/agi-inc/agi-python/commit/33588e65d84e0eebca611ac52ed4529a7345e964))
+* update step method in SessionsResource to include session_id ([560e268](https://github.com/agi-inc/agi-python/commit/560e26892101b272db93011da58de8dc55d5abae))
+
+
+### Bug Fixes
+
+* **ci:** Fix security check false positive and add workflow permissions ([442e993](https://github.com/agi-inc/agi-python/commit/442e993ef7317f5458b7b6721d207ccb2e55ecd4))
+* lint and test issues ([502d104](https://github.com/agi-inc/agi-python/commit/502d104bb75e9903b87766b071d8f47a10eb885f))
+* lint issues ([fd15035](https://github.com/agi-inc/agi-python/commit/fd15035c06d125cb65d5a92299788d8cf1750844))
+* **loop:** Add session_id parameter to AgentLoop ([de1ac36](https://github.com/agi-inc/agi-python/commit/de1ac36224bda410415713aab46ae081ac5e3d44))
+* update session context to handle question event ([d062367](https://github.com/agi-inc/agi-python/commit/d0623672a4a0c6dd51100792e8fe71842624b4c2))
+
+
+### Documentation
+
+* add CHANGELOG.md ([f9316c7](https://github.com/agi-inc/agi-python/commit/f9316c762f170750642974074c327cdc1e2b63bc))
+* add enterprise notice for desktop mode ([237eb5e](https://github.com/agi-inc/agi-python/commit/237eb5ea12b3c0015af86c24e9df92687a3454cc))
+* Add enterprise notice for desktop mode ([a2df41e](https://github.com/agi-inc/agi-python/commit/a2df41ed0523131f2ac53f39b76defc3cbb83e31))
+* update readme ([cf05e24](https://github.com/agi-inc/agi-python/commit/cf05e248e0e06164e8475c76dc8bf4fc3d33beb8))

{agi_python-0.0.1/agi_python.egg-info → agi_python-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agi-python
-Version: 0.0.1
+Version: 0.5.0
 Summary: Official Python SDK for AGI.tech API
 Author-email: AGI Inc <kaushik@theagi.company>
 Maintainer-email: AGI Inc <kaushik@theagi.company>
@@ -51,7 +51,7 @@ Dynamic: license-file
 
 ---
 
-**AI agent that actually works on the web.**
+**Universal Computer-Use AI**
 
 <br />
 
@@ -305,6 +305,84 @@ session = client.sessions.create(
 
 </details>
 
+<details>
+<summary><b>Client-Driven Sessions</b> – Run agents on desktop, mobile, or custom environments</summary>
+
+<br />
+
+> **Note:** Desktop mode is currently feature-gated. For enterprise access, contact [`partner@theagi.company`](mailto:partner@theagi.company).
+
+For scenarios where you control the execution environment (desktop automation, mobile apps, custom browsers), use client-driven sessions with `AgentLoop`:
+
+```python
+import asyncio
+from agi import AGIClient, AgentLoop
+
+async def main():
+    client = AGIClient()
+
+    # Create a client-driven session
+    session = client.sessions.create(
+        agent_name="agi-2-claude",
+        agent_session_type="desktop",
+        goal="Open calculator and compute 2+2"
+    )
+
+    # Define your callbacks
+    async def capture_screenshot() -> str:
+        # Return base64-encoded screenshot from your environment
+        return "..."
+
+    async def execute_actions(actions):
+        for action in actions:
+            print(f"Executing: {action['type']}")
+            # Execute action in your environment
+
+    # Create and run the loop
+    loop = AgentLoop(
+        client=client,
+        agent_url=session.agent_url,
+        capture_screenshot=capture_screenshot,
+        execute_actions=execute_actions,
+        on_thinking=lambda t: print(f"💭 {t}"),
+    )
+
+    result = await loop.start()
+    print(f"Finished: {result.finished}")
+
+asyncio.run(main())
+```
+
+**Loop Control:**
+
+```python
+# Start in background
+task = asyncio.create_task(loop.start())
+
+# Pause/resume/stop
+loop.pause()   # Pause after current step
+loop.resume()  # Continue execution
+loop.stop()    # Stop the loop
+
+# Check state
+loop.state          # LoopState.RUNNING, PAUSED, STOPPED, FINISHED
+loop.current_step   # Current step number
+loop.last_result    # Last StepDesktopResponse
+```
+
+**Manual Step Control:**
+
+```python
+# Or manage the loop yourself
+while not finished:
+    screenshot = capture_screenshot()
+    result = client.sessions.step(session.agent_url, screenshot)
+    execute_actions(result.actions)
+    finished = result.finished
+```
+
+</details>
+
 ---
 
 ## Error Handling

{agi_python-0.0.1 → agi_python-0.5.0}/README.md

@@ -13,7 +13,7 @@
 
 ---
 
-**AI agent that actually works on the web.**
+**Universal Computer-Use AI**
 
 <br />
 
@@ -267,6 +267,84 @@ session = client.sessions.create(
 
 </details>
 
+<details>
+<summary><b>Client-Driven Sessions</b> – Run agents on desktop, mobile, or custom environments</summary>
+
+<br />
+
+> **Note:** Desktop mode is currently feature-gated. For enterprise access, contact [`partner@theagi.company`](mailto:partner@theagi.company).
+
+For scenarios where you control the execution environment (desktop automation, mobile apps, custom browsers), use client-driven sessions with `AgentLoop`:
+
+```python
+import asyncio
+from agi import AGIClient, AgentLoop
+
+async def main():
+    client = AGIClient()
+
+    # Create a client-driven session
+    session = client.sessions.create(
+        agent_name="agi-2-claude",
+        agent_session_type="desktop",
+        goal="Open calculator and compute 2+2"
+    )
+
+    # Define your callbacks
+    async def capture_screenshot() -> str:
+        # Return base64-encoded screenshot from your environment
+        return "..."
+
+    async def execute_actions(actions):
+        for action in actions:
+            print(f"Executing: {action['type']}")
+            # Execute action in your environment
+
+    # Create and run the loop
+    loop = AgentLoop(
+        client=client,
+        agent_url=session.agent_url,
+        capture_screenshot=capture_screenshot,
+        execute_actions=execute_actions,
+        on_thinking=lambda t: print(f"💭 {t}"),
+    )
+
+    result = await loop.start()
+    print(f"Finished: {result.finished}")
+
+asyncio.run(main())
+```
+
+**Loop Control:**
+
+```python
+# Start in background
+task = asyncio.create_task(loop.start())
+
+# Pause/resume/stop
+loop.pause()   # Pause after current step
+loop.resume()  # Continue execution
+loop.stop()    # Stop the loop
+
+# Check state
+loop.state          # LoopState.RUNNING, PAUSED, STOPPED, FINISHED
+loop.current_step   # Current step number
+loop.last_result    # Last StepDesktopResponse
+```
+
+**Manual Step Control:**
+
+```python
+# Or manage the loop yourself
+while not finished:
+    screenshot = capture_screenshot()
+    result = client.sessions.step(session.agent_url, screenshot)
+    execute_actions(result.actions)
+    finished = result.finished
+```
+
+</details>
+
 ---
 
 ## Error Handling

{agi_python-0.0.1 → agi_python-0.5.0}/agi/__init__.py

@@ -4,7 +4,7 @@ The agi package provides a complete Python SDK for the AGI.tech API,
 enabling developers to create and manage AI agent sessions that can perform
 complex web tasks.
 
-Example:
+Example (server-driven session):
     >>> from agi import AGIClient
     >>>
     >>> client = AGIClient(api_key="your_api_key")
@@ -14,9 +14,25 @@ Example:
     ...         "Find three nonstop SFO→JFK flights next month under $450"
     ...     )
     ...     print(result)
+
+Example (local desktop session using driver):
+    >>> from agi import AgentDriver, DriverOptions
+    >>>
+    >>> driver = AgentDriver(DriverOptions(mode="local"))
+    >>> result = await driver.start(goal="Open calculator and compute 2+2")
+    >>> print(result.summary)
 """
 
 from agi.client import AGIClient
+from agi.driver import (
+    AgentDriver,
+    DriverAction,
+    DriverOptions,
+    DriverResult,
+    DriverState,
+    find_binary_path,
+    is_binary_available,
+)
 from agi.exceptions import (
     AgentExecutionError,
     AGIError,
@@ -26,6 +42,14 @@ from agi.exceptions import (
     PermissionError,
     RateLimitError,
 )
+from agi.loop import AgentLoop, LoopState
+from agi.types.desktop import (
+    DesktopAction,
+    DesktopActionType,
+    ModelsResponse,
+    StepDesktopRequest,
+    StepDesktopResponse,
+)
 from agi.types.results import Screenshot, TaskMetadata, TaskResult
 from agi.types.sessions import (
     DeleteResponse,
@@ -38,12 +62,17 @@ from agi.types.sessions import (
     SSEEvent,
     SuccessResponse,
 )
-from agi.types.shared import EventType, MessageType, SessionStatus, SnapshotMode
+from agi.types.shared import AgentSessionType, EventType, MessageType, SessionStatus, SnapshotMode
 
 __version__ = "0.0.1"
 
 __all__ = [
+    # Client
     "AGIClient",
+    # Loop
+    "AgentLoop",
+    "LoopState",
+    # Exceptions
     "AGIError",
     "APIError",
     "AgentExecutionError",
@@ -51,6 +80,7 @@ __all__ = [
     "NotFoundError",
     "PermissionError",
     "RateLimitError",
+    # Session types
     "SessionResponse",
     "SSEEvent",
     "MessageResponse",
@@ -63,8 +93,24 @@ __all__ = [
     "SuccessResponse",
     "TaskResult",
     "TaskMetadata",
+    # Desktop types
+    "DesktopAction",
+    "DesktopActionType",
+    "ModelsResponse",
+    "StepDesktopRequest",
+    "StepDesktopResponse",
+    # Shared types
+    "AgentSessionType",
     "EventType",
     "MessageType",
     "SessionStatus",
     "SnapshotMode",
+    # Driver
+    "AgentDriver",
+    "DriverOptions",
+    "DriverResult",
+    "DriverAction",
+    "DriverState",
+    "find_binary_path",
+    "is_binary_available",
 ]

{agi_python-0.0.1 → agi_python-0.5.0}/agi/_http.py

@@ -94,6 +94,62 @@ class HTTPClient:
 
         raise APIError("Request failed")
 
+    def request_url(
+        self,
+        method: str,
+        url: str,
+        **kwargs: Any,
+    ) -> httpx.Response:
+        """Make HTTP request to an absolute URL with retry logic.
+
+        Args:
+            method: HTTP method (GET, POST, etc.)
+            url: Absolute URL to request
+            **kwargs: Additional arguments for httpx.request()
+
+        Returns:
+            HTTP response
+
+        Raises:
+            AGIError: On API errors
+        """
+        last_exception: httpx.HTTPStatusError | None = None
+
+        for attempt in range(self._max_retries):
+            try:
+                # Use httpx directly for absolute URLs
+                response = httpx.request(
+                    method,
+                    url,
+                    headers=self._client.headers,
+                    timeout=self._client.timeout,
+                    **kwargs,
+                )
+                response.raise_for_status()
+                return response
+
+            except httpx.HTTPStatusError as e:
+                if e.response.status_code >= 500 and attempt < self._max_retries - 1:
+                    wait_time = 2**attempt
+                    time.sleep(wait_time)
+                    last_exception = e
+                    continue
+
+                self._handle_error(e.response)
+                raise
+
+            except (httpx.RequestError, httpx.TimeoutException) as e:
+                if attempt < self._max_retries - 1:
+                    wait_time = 2**attempt
+                    time.sleep(wait_time)
+                    continue
+                raise APIError(f"Request failed: {str(e)}") from e
+
+        if last_exception:
+            raise APIError(f"Max retries exceeded: {str(last_exception)}") from last_exception
+
+        raise APIError("Request failed")
+
     def _handle_error(self, response: httpx.Response) -> None:
         """Map HTTP errors to SDK exceptions.
 

agi_python-0.5.0/agi/driver/__init__.py

@@ -0,0 +1,85 @@
+"""Driver module for spawning and managing the agi-driver binary.
+
+The driver communicates via JSON lines over stdin/stdout and provides
+an event-based interface for agent control.
+"""
+
+from agi.driver._binary import (
+    PlatformId,
+    find_binary_path,
+    get_platform_id,
+    is_binary_available,
+)
+from agi.driver._driver import AgentDriver, DriverOptions, DriverResult
+from agi.driver._protocol import (
+    ActionEvent,
+    AnswerCommand,
+    AskQuestionEvent,
+    AudioTranscriptEvent,
+    CommandType,
+    ConfirmEvent,
+    ConfirmResponseCommand,
+    DriverAction,
+    DriverCommand,
+    DriverEvent,
+    DriverState,
+    ErrorEvent,
+    EventType,
+    FinishedEvent,
+    GetAudioTranscriptCommand,
+    GetVideoFrameCommand,
+    PauseCommand,
+    ReadyEvent,
+    ResumeCommand,
+    ScreenshotCapturedEvent,
+    ScreenshotCommand,
+    SessionCreatedEvent,
+    SpeechFinishedEvent,
+    SpeechStartedEvent,
+    StartCommand,
+    StateChangeEvent,
+    StopCommand,
+    ThinkingEvent,
+    TurnDetectedEvent,
+    VideoFrameEvent,
+)
+
+__all__ = [
+    "AgentDriver",
+    "DriverOptions",
+    "DriverResult",
+    "DriverEvent",
+    "DriverAction",
+    "DriverState",
+    "DriverCommand",
+    "EventType",
+    "CommandType",
+    "ReadyEvent",
+    "StateChangeEvent",
+    "ThinkingEvent",
+    "ActionEvent",
+    "ConfirmEvent",
+    "AskQuestionEvent",
+    "FinishedEvent",
+    "ErrorEvent",
+    "ScreenshotCapturedEvent",
+    "SessionCreatedEvent",
+    "AudioTranscriptEvent",
+    "VideoFrameEvent",
+    "SpeechStartedEvent",
+    "SpeechFinishedEvent",
+    "TurnDetectedEvent",
+    "GetAudioTranscriptCommand",
+    "GetVideoFrameCommand",
+    "StartCommand",
+    "ScreenshotCommand",
+    "PauseCommand",
+    "ResumeCommand",
+    "StopCommand",
+    "ConfirmResponseCommand",
+    "AnswerCommand",
+    "find_binary_path",
+    "is_binary_available",
+    "get_platform_id",
+    "PlatformId",
+]

agi_python-0.5.0/agi/driver/_binary.py

@@ -0,0 +1,102 @@
+"""Binary locator for the agi-driver.
+
+Finds the platform-specific binary bundled with the package
+or a global installation.
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+import sys
+from pathlib import Path
+from typing import Literal
+
+PlatformId = Literal["darwin-arm64", "darwin-x64", "linux-x64", "windows-x64"]
+
+
+def get_platform_id() -> PlatformId:
+    """Get the current platform identifier."""
+    os_name = platform.system().lower()
+    arch = platform.machine().lower()
+
+    if os_name == "darwin":
+        if arch == "arm64":
+            return "darwin-arm64"
+        elif arch in ("x86_64", "amd64"):
+            return "darwin-x64"
+        else:
+            raise RuntimeError(f"Unsupported architecture for macOS: {arch}")
+    elif os_name == "linux":
+        if arch not in ("x86_64", "amd64"):
+            raise RuntimeError(f"Unsupported architecture for Linux: {arch}")
+        return "linux-x64"
+    elif os_name == "windows":
+        if arch not in ("x86_64", "amd64"):
+            raise RuntimeError(f"Unsupported architecture for Windows: {arch}")
+        return "windows-x64"
+    else:
+        raise RuntimeError(f"Unsupported platform: {os_name}-{arch}")
+
+
+def get_binary_filename(platform_id: PlatformId | None = None) -> str:
+    """Get the binary filename for the given platform."""
+    pid = platform_id or get_platform_id()
+    if pid == "windows-x64":
+        return "agi-driver.exe"
+    return "agi-driver"
+
+
+def _get_search_paths(platform_id: PlatformId) -> list[Path]:
+    """Get the list of paths to search for the binary."""
+    filename = get_binary_filename(platform_id)
+    paths: list[Path] = []
+
+    # 1. Bundled in package's bin directory
+    package_dir = Path(__file__).parent.parent
+    paths.append(package_dir / "bin" / filename)
+
+    # 2. In the package root's bin directory
+    paths.append(package_dir.parent / "bin" / filename)
+
+    # 3. In site-packages bin directory
+    for site_pkg in sys.path:
+        if "site-packages" in site_pkg:
+            paths.append(Path(site_pkg).parent / "bin" / filename)
+
+    # 4. Global installation (in PATH)
+    env_path = os.environ.get("PATH", "")
+    for dir_path in env_path.split(os.pathsep):
+        if dir_path:
+            paths.append(Path(dir_path) / filename)
+
+    return paths
+
+
+def find_binary_path() -> str:
+    """Find the agi-driver binary path.
+
+    Raises:
+        RuntimeError: If the binary cannot be found
+    """
+    platform_id = get_platform_id()
+    search_paths = _get_search_paths(platform_id)
+
+    for path in search_paths:
+        if path.exists() and path.is_file():
+            return str(path)
+
+    raise RuntimeError(
+        f"Could not find agi-driver binary for {platform_id}. "
+        f"Searched: {', '.join(str(p) for p in search_paths[:5])}... "
+        f"Ensure agi-driver is installed or in PATH."
+    )
+
+
+def is_binary_available() -> bool:
+    """Check if the binary is available."""
+    try:
+        find_binary_path()
+        return True
+    except RuntimeError:
+        return False