Liyagent Python SDK

A small client for Liyagent's public API: agents, runs, evals, knowledge, approvals and solution templates. It depends only on httpx and returns the server's JSON as it is.

pip install liyagent          # from PyPI, once released
pip install ./sdk/python      # from this repository

Python 3.10+. Versioned with the package (liyagent.__version__); see CHANGELOG.md.

Sign in

from liyagent import Client

# A service account (what a pipeline uses): exchanged for a one-hour session,
# and for a new one when it expires.
liya = Client("https://acme.liyagent.com", token="svc/ci-deployer:...")

# A person, as the console signs in.
liya = Client("https://acme.liyagent.com", username="ana", password="...")

# The machine surface (knowledge.answer): the instance API key or a client token.
liya = Client("https://acme.liyagent.com", api_key="...")

LIYA_URL, LIYA_TOKEN (or TICKETIQ_TOKEN) and LIYA_API_KEY are read when the arguments are left out, as the liya CLI reads them.

What it covers

Anything else: liya.request("GET", "/api/..."), with the same credentials and errors.

Types

Request bodies are typed: liyagent.models holds a TypedDict per body (TemplateInstallBody, BundleApplyBody, …) and REQUEST_BODIES maps each operation to its body. They are generated from the server's OpenAPI document by sdk/scripts/generate_models.py, and the server's test suite fails when the committed file differs from what the document says. The package ships py.typed, so mypy and pyright read them. Responses are the server's JSON as it is.

Your own templates

doc = liya.templates.draft_from_agent("desk-helper", key="desk-answers")["template"]
doc["params"] = [{"name": "team", "label": "Escalation team", "required": True}]
doc["agent"]["instructions"] += "\nEscalate to {{ params.team }}."
assert liya.templates.validate(doc)["ok"]
liya.templates.save_draft(doc)
liya.templates.publish("desk-answers", doc["version"])
liya.templates.install("desk-answers", agent_id="desk-two", params={"team": "Network"})

Errors

A refusal raises LiyagentError with status, the server's detail (for a bundle or template refusal, {message, at}: where in the document it was) and a kind: auth (401, sign in again), forbidden (403, a permission is missing), not_found, invalid (400, 422), conflict (409, 412), unreachable or error.

Check the server

liya.check_server() lists the operations this SDK uses that the server does not serve, so a pipeline can stop before it calls a route an older release does not have. The same list (liyagent.OPERATIONS) is checked against the server's OpenAPI document in the server's test suite (tests/unit/test_sdk_python.py).

Examples

• examples/install_template.py — preview a template, stop if any part would be refused, install it.
• examples/eval_gate.py — score an agent on its eval set and fail a build that is worse than the pinned baseline.
• examples/approvals_queue.py — work the approval queue from a terminal.

Releasing

See sdk/RELEASING.md: a tag sdk-py-vX.Y.Z builds and publishes this package to PyPI from GitHub Actions (.github/workflows/sdk-release.yml) by trusted publishing.