---
name: agenthub-python
description: Agent Hub Python SDK (agentsapi / agentserviceapi)—run workflows, handle tool and completion webhooks, define output validators from StandardAgentOutput, save run JSON locally. Invoke for AgentServiceAPIClient, execute_agent, webhooks, validators, or agentsapi.
---

# Agent Hub — Python client (`agentsapi`)

**Install:** `pip install agentserviceapi` — import **`agentsapi`** (PyPI distribution name is **`agentserviceapi`**).

```python
from agentsapi import AgentServiceAPIClient

client = AgentServiceAPIClient(base_url="https://your-agent-hub-host")
client.set_api_key("sk_...")
```

---

## Running agents

- **`execute_agent_polling`**: returns `task_id` immediately; poll `get_agent_task_status` or use webhooks. No local SSE/tool loop.
- **`run_agent`** / **`execute_agent`**: SSE stream; use **`client.set_tools({ name: (ToolDefinition | None, async_handler) })`** first. Handler: `async def f(args, *, agent_id, task_id) -> str`.

Environments: `playground`, `test`, `production`. Inputs use string slots like `"1"`, `"2"` in `string_inputs`.

---

## Webhooks

Parse POST JSON as **`AgentGraphRunStatusResponse.model_validate(...)`**.

**Tools paused:** `await client.process_webhook_tools(payload, tools_dict)` then `await client.send_tool_responses(agent_id, task_id, tool_results.results)`.

**Completed:** `await client.process_webhook_agent_completed(payload, { graph_id: async_handler })` returning **`AgentTaskCompletedProcessedResult`**.

Note **`subgraph_task_id`** on parent payloads for nested runs.

---

## Validators

Subclass **`StandardAgentOutput`** (`agentsapi.models.agent_execution`). Register with **`await client.agent_validation.upsert_validators([YourModel])`**. Wire **`output_format_validator_name`** (or id) on workflow nodes.

---

## Save runs locally

`json.dumps(final.model_dump(mode="json"), default=str)` to a file; `final` is **`AgentGraphRunStatusResponse`**.

---

## Flow

```mermaid
sequenceDiagram
  participant App as ClientApp
  participant API as AgentHubAPI
  App->>API: POST execute
  alt SSE_tools
    API-->>App: awaiting tools
    App->>API: tool_responses
  else HTTP_webhook
    API->>App: webhook
    App->>API: tool_responses
  end
  API-->>App: completed
```
