servicialo-sdk

Python SDK for the Servicialo protocol — the orchestration layer for professional service delivery in the AI-agent economy.

Installation

pip install servicialo-sdk

Quickstart

import asyncio
from servicialo import ServicialoClient, ActorRef, ActorType

async def main():
    async with ServicialoClient("https://api.coordinalo.com", api_key="sk-...") as client:
        # Phase 1: Discovery — find organizations and available slots
        orgs = await client.discovery.search_registry("health", location="Santiago")
        slots = await client.discovery.check_availability(
            "clinica-dental-sur", date_from="2026-03-01", date_to="2026-03-07",
        )

        # Phase 2: Understanding — read the service definition and contract
        service = await client.understanding.get_service("svc_abc123")
        contract = await client.understanding.get_contract("svc_abc123", org_id="org_1")

        # Phase 3: Commitment — resolve client, book, and confirm
        actor = ActorRef(type=ActorType.AGENT, id="agent_001")
        cl = await client.commitment.get_or_create_client(actor, email="patient@example.com")
        session = await client.commitment.book(
            service_id="svc_abc123",
            provider_id="prov_xyz789",
            client_id=cl["id"],
            starts_at="2026-03-03T10:00:00-03:00",
            actor=actor,
        )
        await client.commitment.confirm(session["id"], actor)

asyncio.run(main())

Standalone models

The SDK models and enums can be imported without a running server for local validation:

from servicialo import ServiceManifest, ServiceStatus, ServiceVisibility

# Validate a service manifest locally
manifest = ServiceManifest(
    id="svc_001",
    type="legal_consultation",
    vertical="legal",
    name="Initial Consultation - 60min",
    duration_minutes=60,
    visibility=ServiceVisibility.PUBLIC,
    provider={"id": "prov_1", "organization_id": "org_1"},
    client={"id": "cli_1"},
    schedule={"requested_at": "2026-03-01T08:00:00Z"},
    lifecycle={"current_state": ServiceStatus.REQUESTED},
    billing={"amount": {"value": 50000, "currency": "CLP"}},
)

Protocol phases

The SDK organizes the 20 protocol tools into 6 phases:

Phase	Namespace	Tools	Auth
1. Discovery	client.discovery	search_registry, get_organization, list_services, check_availability	No
2. Understanding	client.understanding	get_service, get_contract	Yes
3. Commitment	client.commitment	get_or_create_client, book, confirm	Yes
4. Lifecycle	client.lifecycle	get_state, transition, reschedule, cancel	Yes
5. Verification	client.verification	checkin, checkout, record_evidence	Yes
6. Closing	client.closing	create_documentation, create_sale, record_payment, get_payment_status	Yes

Resources

• Protocol Specification (v0.7)
• Servicialo Whitepaper
• TypeScript MCP Server

License

Apache-2.0 — Copyright 2023-2026 Digitalo SpA