This release is a pre-release and may not be stable for production use.
LigaX Python SDK
Run the AI agents you build in LigaX from your own Python code.
ligaxai is the official Python client for the LigaX Agent API. It has a sync client
(LigaX) and an async client (AsyncLigaX) with the same methods, typed results, safe
automatic retries, and streaming that can resume after a dropped connection.
Contents: What you need · Install · Configure · Quickstart · Common tasks · Web apps · Webhooks · Configuration reference · Errors · Retries and timeouts · Security · API reference · For AI coding assistants
What you need
Get these four things from your LigaX workspace before you write any code:
| You need | Looks like | Where to get it |
|---|---|---|
| API base URL | https://<your-ligax-host>/api/public/v1 |
Your LigaX administrator. It is the address of your LigaX platform. |
| Secret API key | lgx_sk_… |
LigaX → Settings → Developers → API keys. Keep it on your server. |
| Agent profile ID | prf_… |
LigaX → Settings → Developers. A profile is a published agent your key may run. |
| Python | 3.11 or newer |
Words used on this page:
- Agent profile (
prf_…): an agent you built in LigaX and published for API use. - Run: one request to an agent. You send
inputtext and get backoutput.text. - Conversation (
conv_…): a thread of runs. Pass its id to continue where you left off. - End user: a person in your app that a run acts for, named by your own user id.
- Approval: a run can stop with status
requires_actionto ask before it acts. You approve or reject it.
Install
pip install ligaxai
Add the FastAPI helpers with pip install "ligaxai[fastapi]". With uv: uv add ligaxai.
Configure
Set two environment variables. Both are required.
| Variable | Required | Value |
|---|---|---|
LIGAX_BASE_URL |
yes | Your platform's API root, for example https://<your-ligax-host>/api/public/v1 |
LIGAX_API_KEY |
yes | Your secret API key, lgx_sk_… |
export LIGAX_BASE_URL="https://<your-ligax-host>/api/public/v1"
export LIGAX_API_KEY="lgx_sk_..."
<your-ligax-host> is a placeholder: replace it with your platform's host. The SDK has no
built-in address, for any environment. If the base URL is missing, creating the client
raises MissingBaseURLError. If the key is missing, it raises MissingAPIKeyError. Both
happen before any network call.
You can also pass both values in code: LigaX(base_url="...", api_key="..."). An argument
wins over the environment variable.
Quickstart
Save this as hello.py and run python hello.py:
from ligaxai import LigaX
client = LigaX() # reads LIGAX_BASE_URL and LIGAX_API_KEY
run = client.runs.wait(
profile_id="prf_...", # your agent profile ID
input="Summarise yesterday's P1 incidents.",
)
if run.status == "completed":
print(run.output.text)
else:
print("Run ended with status:", run.status, run.error)
It prints the agent's answer. runs.wait sends the request and waits until the run
finishes or needs your approval.
To check your setup first, call client.keys.self(). It returns your key's name, scopes
and spend limit. client.profiles.list() returns the profiles your key may run.
Common tasks
Stream the answer as it is written
from ligaxai import LigaX
client = LigaX()
with client.runs.stream(profile_id="prf_...", input="Draft a reply to ticket 4411.") as stream:
for text in stream.text_stream():
print(text, end="", flush=True)
print()
print(stream.status, stream.run_id, stream.conversation_id)
text_stream() yields only the new text each time. To see every event (tool calls,
sources, artifacts), iterate stream itself: each item is a RunEvent with type, seq,
payload and run_id. stream.final_text() returns the whole answer.
If the connection drops, resume from the last event you received. Nothing is repeated:
resumed = client.runs.follow_events(stream.run_id, after=stream.last_seq)
Use async
AsyncLigaX has the same methods. Await them, and use async with for streams:
import asyncio
from ligaxai import AsyncLigaX
async def main() -> None:
async with AsyncLigaX() as client:
run = await client.runs.wait(profile_id="prf_...", input="Hello")
print(run.output.text)
async with client.runs.stream(profile_id="prf_...", input="And again") as stream:
async for text in stream.text_stream():
print(text, end="", flush=True)
asyncio.run(main())
Continue a conversation
Every run belongs to a conversation. Pass conversation_id to continue it:
first = client.runs.wait(profile_id="prf_...", input="Open a ticket for the VPN outage")
follow_up = client.runs.wait(
profile_id="prf_...",
input="Make it priority 2",
conversation_id=first.conversation_id,
)
Act for one of your users
Pass end_user with your own user id. The run then uses that user's connected accounts
and conversations, and only that user can continue them:
run = client.runs.wait(profile_id="prf_...", input="What is on my calendar?", end_user="user-42")
Take the user id from your own login session, never from the browser's request.
Approve or reject an action
An agent can stop and ask before it acts, for example before it sends an email. The run
then has status requires_action:
run = client.runs.wait(profile_id="prf_...", input="Email the team about the outage")
if run.status == "requires_action" and run.required_action:
print("The agent asks:", run.required_action.prompt)
run = client.runs.resolve_interrupt(
run.id, run.required_action.interrupt_id, decision="approve" # or "reject"
)
Send a file
Upload a file, then attach its id to a run. The key needs the files:write scope:
f = client.files.create(file="contract.pdf") # a path, bytes, or a file opened in "rb" mode
run = client.runs.wait(
profile_id="prf_...",
input="Summarise the termination clause",
attachments=[f.id],
)
- Up to 25 MB per file and 10 files per run. A larger file raises
ValueErrorbefore upload. - Files are kept for 30 days.
client.files.delete(f.id)removes one early. files.get(id)returns metadata only. There is no download.- Whether a file type can be read depends on the agent's model.
Check a run later
Start a run without waiting, then read it:
run = client.runs.create(profile_id="prf_...", input="Prepare the weekly report", mode="async")
run = client.runs.get(run.id) # status: queued, running, completed, ...
client.runs.cancel(run.id) # stop it if you no longer need it
A run's status is one of queued, running, requires_action, completed, failed,
canceled or expired.
Web apps
Stream to a browser with FastAPI
Keep the secret key on your server. The browser talks to your route, and your route talks to LigaX:
from fastapi import FastAPI, Request
from ligaxai.fastapi import client_dependency, run_stream_route
app = FastAPI()
get_client = client_dependency() # one AsyncLigaX per process, from the environment
def current_user(request: Request) -> str:
return request.state.user_id # from YOUR login session
app.post("/chat")(run_stream_route(get_client, "prf_...", current_user))
The browser sends POST /chat with {"input": "…", "conversation_id": "conv_…"} and reads
a text/event-stream. The profile is fixed on the server and the user comes from your
session, so one person cannot read or continue another's conversation. Without a signed-in
user the route answers 401. A complete app is in
examples/fastapi-app.
Let a browser call LigaX directly (client tokens)
Your server can mint a short-lived client token (lgx_ct_…) for the signed-in user.
The browser uses it instead of your secret key:
token = client.client_tokens.create(
profile_id="prf_...",
end_user={"id": "user-42", "name": "Ada"}, # or just "user-42"
expires_in=900, # seconds, 60 to 3600; default 600
)
# Send token.token and token.expires_at to that user's browser. Never log the token.
A client token runs one profile, as one end user, for a few minutes. It cannot manage keys, webhooks or usage. Two settings must be in place:
- the secret key that mints it needs the
client_tokens:writescope; - the profile must list your website's origin (for example
https://app.example.com) under allowed origins in Settings → Developers.
With FastAPI, client_token_route is that endpoint:
from fastapi import FastAPI, Request
from ligaxai.fastapi import client_dependency, client_token_route
app = FastAPI()
get_client = client_dependency()
def current_user(request: Request) -> tuple[str, str] | None:
user = request.state.user # from YOUR login session
return (user.id, user.name) if user else None # None answers 401
app.post("/ligax/token")(client_token_route(get_client, "prf_...", current_user))
It answers {"token": "lgx_ct_…", "expires_at": "…"} with Cache-Control: no-store. In
Django or Flask, write the same three steps in your own view: require a signed-in user,
call client.client_tokens.create(...), return token and expires_at.
Let your users connect their own accounts
By default an agent uses the workspace's shared connections. If the profile allows it
(End users can connect their own accounts, on the agent's API & Integrations tab),
each of your users can connect their own Gmail, Outlook and so on. Runs with that
end_user then use the user's own account.
Your server starts a connect session (scope connections:write) and gives the
browser its connect_url:
session = client.connect_sessions.create(
connector_key="gmail",
profile_id="prf_...",
end_user="user-42",
)
# In the browser, open session.connect_url in a popup from a click handler.
Then wait until the user finishes. denied, failed and expired are results, not
errors. wait raises TimeoutError if the session is still pending after timeout
seconds:
session = client.connect_sessions.wait(session.id, end_user_id="user-42", timeout=300)
if session.status == "succeeded":
print("Connected:", session.connection_id)
List or remove a user's own accounts (never the shared ones):
for conn in client.end_users.connections.list("user-42").data:
print(conn.id, conn.connector_key, conn.status)
client.end_users.connections.delete("user-42", conn.id)
Webhooks
LigaX can call your server when something happens, so you don't have to poll. Managing
endpoints needs the webhooks:manage scope.
| Event | Sent when |
|---|---|
run.completed, run.failed, run.canceled |
a run ends |
run.requires_action |
a run waits for your approval |
api_key.limit_reached |
a key reaches its spend limit |
connection.created, connection.deleted |
an end user connects or removes an account |
webhook.test |
you call webhooks.test |
1. Create an endpoint and store its secret. The secret (whsec_…) is returned only
once:
endpoint = client.webhooks.create(
url="https://example.com/hooks/ligax",
event_types=["run.completed", "run.failed", "run.requires_action"],
profile_ids=["prf_..."], # optional: only these profiles' runs
)
print(endpoint.id, endpoint.secret) # store the secret in your secret manager
client.webhooks.test(endpoint.id) # sends a webhook.test event now
2. Verify every delivery against the raw request body. webhooks.verify checks the
signature and the timestamp, then returns a typed event:
from ligaxai import WebhookVerificationError, webhooks
from ligaxai.types import RunWebhookEvent
def handle(raw_body: bytes, headers: dict[str, str], secret: str) -> int:
try:
event = webhooks.verify(raw_body, headers, secret=secret)
except WebhookVerificationError:
return 400
if isinstance(event, RunWebhookEvent) and event.type == "run.completed":
run = client.runs.get(event.data.id) # the event holds ids, not the answer
print(run.output.text)
return 204
In FastAPI, ligaxai.fastapi.webhook_dependency(get_secret) does the reading and
verifying for you and answers 400 on a bad signature.
3. Follow these rules:
- Use the raw bytes. Re-encoding parsed JSON changes what was signed.
- Answer 2xx within 15 seconds. Do slow work in the background. Failed deliveries are retried for about 27 hours; an endpoint that keeps failing is disabled.
- Skip duplicates. A retry has the same
webhook-idheader. Remember the ids you handled. - Fetch the content. Events carry ids and a status only. Read the run with
runs.get.
Deliveries follow Standard Webhooks. For Zapier, Make
or n8n, map subscribe to webhooks.create and unsubscribe to webhooks.delete.
Use an agent from MCP or A2A clients
Every published agent profile is also an MCP server and an A2A agent, so Claude Code, Cursor or another agent can call it without this SDK. Use a secret key with the Start runs and Read runs scopes:
claude mcp add --transport http ligax-support \
https://<your-ligax-host>/api/public/v1/mcp/prf_... \
--header "Authorization: Bearer $LIGAX_API_KEY"
- MCP endpoint:
https://<your-ligax-host>/api/public/v1/mcp/prf_...(toolsask,get_run,respond). - A2A agent card:
https://<your-ligax-host>/api/public/v1/a2a/prf_.../.well-known/agent-card.json(A2A 1.0 and 0.3; send the sameAuthorizationheader). - Add the header
X-LigaX-End-User: <your user id>to act for one of your users.
Configuration reference
| Setting | Argument | Environment variable | Default |
|---|---|---|---|
| API base URL | base_url= |
LIGAX_BASE_URL |
none, required |
| API key | api_key= |
LIGAX_API_KEY |
none, required |
| Timeout | timeout= |
600 s per request, 5 s to connect | |
| Retries | max_retries= |
2 |
|
| Extra headers | default_headers= |
none | |
| HTTP client | http_client= |
the SDK's own httpx2.Client |
|
| Logging | LIGAX_LOG |
off |
Change options for a few calls with client.with_options(max_retries=0, timeout=10). It
returns a copy that shares the connection pool. Any single call also accepts
options=RequestOptions(timeout=..., max_retries=..., headers=..., idempotency_key=...).
LIGAX_LOG takes debug, info, warn, error or off. Logs never show your key.
Errors
Every error the SDK raises is a subclass of ligaxai.APIError:
from ligaxai import APIConnectionError, APIStatusError, LigaX, PaymentRequiredError, RateLimitError
client = LigaX()
try:
client.runs.create(profile_id="prf_...", input="Hi")
except PaymentRequiredError as e: # the key or workspace reached its spend limit
print(e.code, e.response.headers.get("x-limit-resets-at"))
except RateLimitError as e: # still limited after the SDK's retries
print(e.status_code, e.request_id)
except APIStatusError as e: # any other 4xx or 5xx answer
print(e.status_code, e.code, e.message, e.request_id)
except APIConnectionError: # network problem or timeout (APITimeoutError)
raise
| HTTP status | Exception |
|---|---|
| 400 | BadRequestError |
| 401 | AuthenticationError |
| 402 | PaymentRequiredError |
| 403 | PermissionDeniedError |
| 404 | NotFoundError |
| 409 | ConflictError |
| 422 | UnprocessableEntityError |
| 429 | RateLimitError |
| 500 and above | InternalServerError |
| no response | APIConnectionError, APITimeoutError |
| missing setup | MissingBaseURLError, MissingAPIKeyError (also ValueError) |
Each status error has status_code, code, message, param and request_id. Every
successful result has request_id too. Quote it when you contact support.
Retries and timeouts
- Retried, 2 times by default: connection errors, timeouts, and answers 408, 409, 429
and 5xx. The wait grows from 0.5 s to 8 s, and the SDK honours the server's
Retry-After. - Never retried: 402, 403 and 422, and a stream that has already started.
- No duplicate runs: every
POSTcarries anIdempotency-Keythat stays the same across retries. Pass your ownidempotency_key=to make a retry safe across processes. - Timeout: 600 seconds per request, so
runs.waithas room. The server answers a long run after up to 240 seconds, andruns.waitthen keeps polling for you.
Security
An agent run with your key acts with your workspace's connected accounts (mail, files, tickets) and spends your credit.
- Keep secret keys (
lgx_sk_…) on your server. Never in a browser, a mobile app, a repository or a log. Give each key only the profiles and scopes it needs, and a spend limit. - Treat website keys (
lgx_pk_…) as public. Anyone can copy one from your page. Visitors on a website key can only chat. Give it a small spend limit. - Take the user's identity from your own session, never from the request body or a header the browser sets.
- Keep approvals on for sending, writing and deleting. Anything the agent reads (an email, a web page) can try to give it instructions.
- Treat the agent's answer as untrusted input. Never
evalit or insert it into HTML unescaped. - Verify every webhook and skip duplicates.
- Pin the version in your lockfile. Releases carry PyPI provenance attestations.
Report a vulnerability to security@ligaments.ai (see SECURITY.md).
API reference
Every method exists on LigaX and AsyncLigaX with the same name and parameters.
Results are typed models from ligaxai.types, with field names exactly as in the API
(snake_case). Fields the server adds later are kept in model.model_extra.
| Method | API call | Returns |
|---|---|---|
runs.create(profile_id=, input=, conversation_id=, end_user=, model=, mode="wait"|"async", metadata=, attachments=, idempotency_key=) |
POST /runs |
Run |
runs.wait(...): create, then poll until the run ends or needs approval |
POST /runs, GET /runs/{id} |
Run |
runs.stream(...) |
POST /runs (streamed) |
RunStream |
runs.get(run_id) |
GET /runs/{id} |
Run |
runs.events(run_id, after=0) |
GET /runs/{id}/events |
RunEventList |
runs.follow_events(run_id, after=0) |
GET /runs/{id}/events?stream=true |
RunStream |
runs.cancel(run_id) |
POST /runs/{id}/cancel |
Run |
runs.resolve_interrupt(run_id, interrupt_id, decision="approve"|"reject"|"answer", payload=) |
POST /runs/{id}/interrupts/{iid} |
Run |
conversations.get(conversation_id, end_user_id=None) |
GET /conversations/{id} |
Conversation |
profiles.list(), profiles.get(profile_id) |
GET /profiles[/{id}] |
ProfileList, Profile |
keys.self() |
GET /keys/self |
ApiKey |
usage.get(start=, end=, group_by=) |
GET /usage |
UsageReport |
files.create(file=, end_user_id=None) |
POST /files |
FileObject |
files.get(file_id), files.delete(file_id) |
GET, DELETE /files/{id} |
FileObject, FileDeleted |
webhooks.create(url=, event_types=, description=, profile_ids=, idempotency_key=) |
POST /webhooks |
WebhookEndpointWithSecret |
webhooks.list(), webhooks.get(webhook_id) |
GET /webhooks[/{id}] |
WebhookEndpointList, WebhookEndpoint |
webhooks.update(webhook_id, url=, description=, event_types=, profile_ids=, status=) |
PATCH /webhooks/{id} |
WebhookEndpoint |
webhooks.delete(webhook_id) |
DELETE /webhooks/{id} |
WebhookEndpointDeleted |
webhooks.test(webhook_id) |
POST /webhooks/{id}/test |
WebhookDelivery |
client_tokens.create(profile_id=, end_user=, conversation_id=, expires_in=) |
POST /client_tokens |
ClientToken |
connect_sessions.create(connector_key=, profile_id=, end_user=) |
POST /connect_sessions |
ConnectSession |
connect_sessions.get(session_id, end_user_id=None) |
GET /connect_sessions/{id} |
ConnectSession |
connect_sessions.wait(session_id, end_user_id=None, poll_interval=2, timeout=600) |
GET /connect_sessions/{id} |
ConnectSession |
end_users.connections.list(end_user_id) |
GET /end_users/{id}/connections |
EndUserConnectionList |
end_users.connections.delete(end_user_id, connection_id) |
DELETE /end_users/{id}/connections/{cid} |
EndUserConnectionDeleted |
Module-level helpers: ligaxai.webhooks.verify (with verify_signature and parse_event),
ligaxai.TextAssembler (rebuilds answer text from recorded events), and
ligaxai.fastapi (client_dependency, run_stream_route, client_token_route,
webhook_dependency).
For AI coding assistants
If you are an AI assistant writing code with this package, follow these facts exactly:
- Install
ligaxai. Import from the top-level package:from ligaxai import LigaX, AsyncLigaX. - There is no default base URL. The code must read
LIGAX_BASE_URLfrom the environment or passbase_url=. Never invent or hard-code a host. Without it the client raisesMissingBaseURLError. - The key comes from
LIGAX_API_KEYorapi_key=. A secret key (lgx_sk_…) belongs in server code only. For a browser, mint a client token withclient.client_tokens.create. - Create the client once and reuse it:
client = LigaX(). - The main call is
client.runs.wait(profile_id="prf_...", input="..."). The answer isrun.output.textwhenrun.status == "completed". Handle"requires_action"withruns.resolve_interrupt. - Parameter and field names are snake_case, exactly as in the API (
profile_id,conversation_id,end_user). The async client has the same names;awaiteach call. - Catch
ligaxai.APIStatusError(or a subclass from the table in Errors). Do not add your own retry loop: the client already retries safely. - Take
end_userfrom the app's login session, never from user input.
Versions and support
- Python: 3.11, 3.12, 3.13 and 3.14, on Linux, macOS and Windows.
- Release channels:
pip install ligaxaiinstalls the latest stable release. Preview builds from thedevbranch are versioned like0.1.0.dev14; install one withpip install --pre ligaxaior an exact pin. Every channel needsLIGAX_BASE_URL. - Transport:
httpx2. If your app imports plainhttpxand you want one shared stack, callhttpx2.alias_httpx()before anyhttpximport. - Changes: CHANGELOG.md.
- Bugs and questions: GitHub issues.
- Contributing: CONTRIBUTING.md.
License
Apache-2.0. See LICENSE.
Metadata
Release files for ligaxai 0.1.0.dev15
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ligaxai-0.1.0.dev15.tar.gz | 96.5 kB | With provenance | Details for ligaxai-0.1.0.dev15.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ligaxai-0.1.0.dev15-py3-none-any.whl | Python 3 | none | any | Details for ligaxai-0.1.0.dev15-py3-none-any.whl |
Total release size: 166.0 kB
Release files / ligaxai-0.1.0.dev15.tar.gz
| Download URL | ligaxai-0.1.0.dev15.tar.gz |
|---|---|
| Size | 96.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8b500d36d29f851e2b35233180a442db0a408ccd17653c607f9a58b7b70837a6
|
|
BLAKE2b-256 checksum How to use checksums |
d223d39da67871cabe20272b970569cb0c4d0085915ec2b8d8465ff7687ce1d0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.
Transparency logRelease files / ligaxai-0.1.0.dev15-py3-none-any.whl
| Download URL | ligaxai-0.1.0.dev15-py3-none-any.whl |
|---|---|
| Size | 69.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ba56cadb5b6592253820a3170617199026ef7797e4359701578a8dab547760cd
|
|
BLAKE2b-256 checksum How to use checksums |
3cf717dffc94e729508ab85f248e4c81e5515281ccfade4f038e35b5702871f0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.
Transparency logSecurity for ligaxai 0.1.0.dev15
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for ligaxai-0.1.0.dev15.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.