Metadata-Version: 2.4
Name: agentserviceapi
Version: 0.1.0
Summary: Python client for the Agent Service workflow execution HTTP API
Home-page: https://pypi.org/project/agentserviceapi/
Author: Agent Service API
License: MIT
Project-URL: Homepage, https://pypi.org/project/agentserviceapi/
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.24.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Dynamic: home-page
Dynamic: requires-python

# Agent Service API — Python client

A Python client library for the Agent Service HTTP API (workflow execution, agents, and related endpoints).

**Imports:** The implementation package is **`agentsapi`**. The PyPI distribution name is **`agentserviceapi`**; after `pip install agentserviceapi` you can import either `agentsapi` or the thin alias module `agentserviceapi` (same public symbols). In this monorepo, prefer `from agentsapi import ...`.

## Installation

```bash
pip install agentserviceapi
```

For a checkout of this repository, install in editable mode:

```bash
pip install -e .
```

Requires Python 3.10 or newer.

## Cursor and Claude Code skills

Bundled markdown skills live next to the package:

- `agenthub-python-cursor-skill.md` — save as `.cursor/skills/agenthub-python/SKILL.md`
- `agenthub-python-claude-skill.md` — save as `.claude/skills/agenthub-python.md` (or another name under `.claude/skills/`)

Print the install directory:

```bash
python -c "import pathlib, agentsapi; print(pathlib.Path(agentsapi.__file__).resolve().parent / 'skills')"
```

On Agent Hub, the same files are also served at `/skills/…` on your app origin for `curl` (see the in-product setup guide).

## Usage

### Basic usage

```python
import asyncio
from agentserviceapi import AgentServiceAPIClient

async def main():
    client = AgentServiceAPIClient()

    response = await client.execute_agent(
        agent_id="your-agent-id",
        string_inputs={"1": "Hello, world!"},
        environment="playground",
    )

    print(f"Task ID: {response.task_id}")
    print(f"Status: {response.status}")

asyncio.run(main())
```

### Advanced usage

```python
import asyncio
from agentserviceapi import (
    AgentServiceAPIClient,
    AgentInputs,
    AgentServiceAPIException,
    AgentServiceAPITimeoutError,
    AgentServiceAPIConnectionError,
)

async def main():
    client = AgentServiceAPIClient(timeout=60.0)  # default base_url is https://sudoiq.com

    inputs = AgentInputs(
        strings={"1": "Hello", "2": "World"},
        images={"1": "base64_image_data"},
    )

    try:
        response = await client.execute_agent(
            agent_id="your-agent-id",
            string_inputs=inputs.strings,
            image_inputs=inputs.images,
            environment="production",
        )

        print(f"Task started: {response.task_id}")

    except AgentServiceAPIException as e:
        print(f"API Error: {e}")
    except AgentServiceAPITimeoutError as e:
        print(f"Timeout: {e}")
    except AgentServiceAPIConnectionError as e:
        print(f"Connection Error: {e}")

asyncio.run(main())
```

The `agentsapi` module name is also available for the same symbols (for example `from agentsapi import AgentServiceAPIClient`).

## API reference

### `AgentServiceAPIClient`

Main client for the Agent Service API.

### Exceptions

- `AgentServiceAPIException`: General API errors
- `AgentServiceAPITimeoutError`: Request timeout errors
- `AgentServiceAPIConnectionError`: Connection errors
- `AgentServiceAPIHTTPError`: HTTP errors (structured `detail` / `error_code` when present)

## License

MIT License
