engini
Agent-first Python SDK for the Engini Public API — discover tools, execute them against your connected apps, and wrap them as LLM tool definitions.
pip install engini
Quickstart
from engini import Engini
client = Engini(api_key="eng_…") # or set ENGINI_API_KEY
# Discover canonical tool schemas
tools = client.tools.get(applications=["salesforce"], search="accounts", limit=5)
# Execute a tool against a connection
conn_id = next(c.connection_id for c in client.connections.list(application="salesforce"))
result = client.tools.execute(
"salesforce_getrecords", {"sobject": "Account"}, connection_id=conn_id
)
print(result.output)
JWT auth is the fallback: Engini(token="<jwt>", company_token="<id>"), or set
ENGINI_API_TOKEN / ENGINI_COMPANY_TOKEN. With an API key the company is bound to the key,
so no company token is needed. Point at another host with Engini(..., base_url=…).
Every request carries a User-Agent identifying this SDK and its runtime (e.g.
engini-sdk-python/0.13.0 python/3.11.6 darwin). If you're embedding the SDK inside your own
product, prepend your own token with user_agent_prefix:
client = Engini(api_key="eng_…", user_agent_prefix="my-product/1.4.0")
# -> "my-product/1.4.0 engini-sdk-python/0.13.0 python/3.11.6 darwin"
user_agent_prefix only prepends a token — it can't override or remove the SDK's own identity.
Use with an LLM
Provider adapters wrap canonical schemas into vendor tool definitions client-side, with no
vendor SDK dependency. OpenAI is the default; Anthropic is also available.
# Bind applications → connections once, then drive a tool-calling loop
toolset = client.toolset(tools=["salesforce_getrecords"], connections={"salesforce": "Prod"})
openai_tools = client.provider.wrap_tools(toolset.tools()) # plain OpenAI tool-JSON dicts
# … send openai_tools to the model, get a response …
results = toolset.handle_tool_calls(llm_response) # runs the calls, returns results
client.mcp inspects and maintains the account's MCP servers — the endpoints Engini
exposes over the Model Context Protocol:
servers = client.mcp.list() # includes deactivated ones
client.mcp.deactivate(servers[0].mcp_server_token) # reversible; sends only is_active
tools = client.mcp.available_tools(token, connection_id=2139) # candidates for tool_slugs
update() replaces connections/workflows rather than merging them, and every
connection entry needs an explicit connection_id (MCP servers are account-wide, so there
is no per-user default). There is no create/delete: those stay in the engini.io UI.
client.opa provisions, inspects, configures and credentials on-premise agents — the
Engini component a customer installs behind their own firewall to reach SQL Server,
Oracle, Priority ERP and file shares:
# Provision one and hand the token to the installer
agent = client.opa.create("Warehouse SQL", pull_period_seconds=30)
print(agent.token) # a credential - store it, do not log it
# Later: is it healthy?
a = client.opa.get(agent.agent_id)
print(a.status, a.version, a.last_seen_at)
# Change its log level; the agent picks it up on its next poll
r = client.opa.update(agent.agent_id, log_level="Debug")
if not r.applied_to_agent:
print("stored; the agent is not Online yet")
An agent polls Engini, so anything that "talks to" it waits for its next poll. update()
merges — an omitted keyword leaves that field alone, unlike connections.update(),
which replaces its whole field map. Settings you omit take the server's defaults, and the
minimums come from the connector's own declared metadata rather than the client. Agents are
not connections: client.connections never returns them.
client.triggers is the event side of the platform: a trigger instance (ti_…) watches a
connected system and captures events, which Engini POSTs to a destination you register.
# What can be triggered, then one instance of it
types = client.triggers.types.list(application_slug="monday")
trigger = client.triggers.create("monday_item_created", connection_name="prod")
client.triggers.enable(trigger.id)
# Where events are delivered. The secret is shown once - store it, never log it.
created = client.triggers.destinations.create("primary", "https://acme.test/hooks/engini")
signing_secret = created.signing_secret
Verify a delivery in your web handler. verify_webhook raises rather than returning a
bool — a bool is silently ignorable, which is the one failure mode a signature check cannot
afford — and hands back the parsed event so it is one call, not two:
from engini import verify_webhook
from engini.errors import EnginiWebhookSignatureError
def handle(request): # raw bytes, not a re-serialised body
try:
event = verify_webhook(request.body, request.headers.get("X-Engini-Signature"), secret)
except EnginiWebhookSignatureError:
return 400
... # dedupe on the X-Engini-Event-Id header
For local development subscribe() reads the same events as a blocking stream. It resumes
by itself, which is not a nicety: the gateway caps every connection at one hour of
wall-clock time, and the cut arrives as a truncated body with no goodbye. It reconnects
from the last event you saw, and stops hard only where a gap would otherwise go unnoticed —
a revoked stream, or a cursor the server has already pruned.
for event in client.triggers.subscribe(trigger_id=trigger.id):
print(event["id"], event["payload"])
# `event["delivery"]` is always "pending" on the stream - it is not a delivery
# state. Use client.triggers.events.get(event["id"]) for the real one.
client.toolset(...) builds a local toolset (no I/O until used) or loads a server one via
toolset_id=….
Files
Tools whose input_schema marks a field "format": "engini/file" accept files. Wrap a file
with engini.File and pass it as the field value — the SDK base64-encodes it into the
{base64_content, mime_type, filename} wire shape. A field can take a single file or a list,
per the tool's schema.
from engini import Engini, File
client = Engini(api_key="eng_…")
client.tools.execute(
"doc_summarize",
{
"document": File.from_path("report.pdf"), # single file
"attachments": [File.from_path("a.png"), File.from_path("b.png")], # list of files
},
connection_id=conn_id,
)
File.from_path infers the filename and mime type; File.from_bytes(data, filename=…, mime_type=…) and File.from_base64(…) cover in-memory content.
In the LLM loop an agent can't produce base64, so file fields are presented to it as string fields. Register the files you'll allow and let the model reference one by key:
results = toolset.handle_tool_calls(llm_response, files={"report": File.from_path("report.pdf")})
What this adds over the raw REST client
Built on the autogenerated engini-client, the SDK
adds what the generated client deliberately lacks: typed errors (the EnginiError family),
retry/backoff, auto-pagination, pluggable auth (ApiKeyAuth / BearerAuth), Provider
adapters for OpenAI/Anthropic, and the ergonomic Toolset object.
Command-line interface
The engini CLI is npm-only now: npm install -g @engini/cli. See
https://www.npmjs.com/package/@engini/cli (or ts/packages/cli/README.md in
the source repo) for install, commands, and the machine-readable output/exit-code
contract. This package (engini, PyPI) is the Python SDK only.
Source & docs: https://github.com/engini/engini-sdk
Metadata
Release files for engini 0.21.0
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 |
|---|---|---|---|---|
| engini-0.21.0.tar.gz | 78.7 kB | With provenance | Details for engini-0.21.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| engini-0.21.0-py3-none-any.whl | Python 3 | none | any | Details for engini-0.21.0-py3-none-any.whl |
Total release size: 135.9 kB
Release files / engini-0.21.0.tar.gz
| Download URL | engini-0.21.0.tar.gz |
|---|---|
| Size | 78.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e86f5aad9fab631b8f833f5ac906dd063184225d3fa88cbd6eb3c8ff1fd33b14
|
|
BLAKE2b-256 checksum How to use checksums |
5fb45d56f893df479235dfa85b3c3f34b77353fe37b707dfa24f017b4604e62c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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 Sep 14, 2026.
Transparency logRelease files / engini-0.21.0-py3-none-any.whl
| Download URL | engini-0.21.0-py3-none-any.whl |
|---|---|
| Size | 57.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9b961e658be5eecd307425aa1fb242affea3eed6c20f8f44de5708f71350e8b2
|
|
BLAKE2b-256 checksum How to use checksums |
1a40d7a9c040fd39dc79fc6f54b54822d167ab6257a1b6673df3408d1facded2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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 Sep 14, 2026.
Transparency logSecurity for engini 0.21.0
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 engini-0.21.0.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 Sep 14, 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.