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

pip install agentserviceapi

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

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:

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

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

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