evokai-client
Python client for Evokai, the agents runtime. One package, import evokai:
| Class | Credential | What it is |
|---|---|---|
EvokaiServer / AsyncEvokaiServer |
server key (and admin key for .admin) |
Your backend: session tokens, server runs, conversations, memories, usage, privacy requests, the admin API. |
EvokaiSession / AsyncEvokaiSession |
session token | One subject, one agent, one conversation: chats streamed as typed events, confirmations, questions, replay, cancel, thumbs. |
It is the Python sibling of the TypeScript client (@evokai/evokai-client): same routes, same names in snake_case.
Built on httpx and pydantic v2, sync and async, fully typed (py.typed), Python 3.10 or newer.
base_url is where the service is mounted, base path included, e.g. https://agents.example.com/agent. Keys
never belong in a browser.
Install
uv add evokai-client
# or
pip install evokai-client
# or, unreleased changes, from the repository:
uv add "evokai-client @ git+https://github.com/Giordyfish/evokai#subdirectory=clients/python"
Backend: minting a session token
import os
from evokai import EvokaiServer
evokai = EvokaiServer(
os.environ["EVOKAI_URL"], # https://agents.example.com/agent
os.environ["EVOKAI_SERVER_KEY"], # evk_srv_...
admin_key=os.environ.get("EVOKAI_ADMIN_KEY"), # evk_adm_..., only for evokai.admin
)
token = evokai.mint_session_token(
"user-42", # your own opaque id of the end user
"assistant",
tags=["team:ops"],
forward_credential=request_jwt, # forward_user MCP servers call your API as this user
limits={"caps": [{"period": "week", "amount": 5}]}, # or subject_daily_usd (USD)
voice_engine="browser",
)
# Hand the browser what it needs: token.token, token.expires_at, token.conversation_id,
# token.usage (shares of the caps, never amounts) and token.suggestions.
Every field of POST /v1/session-tokens is a keyword argument: conversation_id (continue a conversation),
ttl_seconds, model, voice, voice_engine, storage_mode, consent, exit_code (kiosks), memory_consent
(the person's answer to long-term memory, asked in your own interface; token.memory is their memory state).
With FastAPI, a token route is a few lines:
from fastapi import Depends, FastAPI
from evokai import AsyncEvokaiServer
app = FastAPI()
evokai = AsyncEvokaiServer(EVOKAI_URL, EVOKAI_SERVER_KEY)
@app.post("/api/evokai/token")
async def evokai_token(user=Depends(current_user)):
t = await evokai.mint_session_token(user.id, "assistant")
return {"token": t.token, "expiresAt": t.expires_at, "conversationId": t.conversation_id}
Running an agent from the server
An agent whose channels include server runs with no browser and no user:
result = evokai.run(
"mail-triage",
"Classify this message",
subject="customer-9137",
attachments=[{"name": "mail.txt", "text": body}],
)
result.output # the schema-valid JSON when the agent has an output_schema, else the answer text
result.model # the model that answered
result.usage.cost_usd # server to server: amounts are fine here
input can also be a conversation: [{"role": "user", "text": "..."}, {"role": "assistant", "text": "..."}].
store=True keeps the run as a conversation of the subject.
Streaming a session chat
from evokai import AskEvent, ConfirmEvent, EvokaiSession, TextEvent
with EvokaiSession(EVOKAI_URL, token) as session: # a token string or the minted SessionToken
with session.chat("How many orders are waiting to ship?", page={"path": "/orders"}) as stream:
for event in stream:
match event:
case TextEvent(delta=delta):
print(delta, end="", flush=True)
case AskEvent(question=q, options=options):
print(f"\n{q} {options}")
case ConfirmEvent(action_id=action_id, items=items):
pending = action_id
print(stream.done.reason) # end_turn, confirm, ask, limit, ...
- Iterating yields typed events (pydantic models):
conversation,text,say,tool,chart,diagram,ask,navigate,confirm,rewritten,usage,speech,erroranddone. Each carriesturn_idandseq. A type this client does not know yet arrives asUnknownEventwith every field inevent.data, so a newer service never breaks you. stream.turn_id(from theX-Turn-Idheader),stream.text(the deltas so far),stream.doneandstream.until_done()help when you do not need every event.- Leaving the
withblock (orbreak, orstream.close()) closes the connection, and the service cancels that turn.session.cancel(turn_id)cancels it explicitly and the stream still ends withdone. - If the connection drops before
done, the stream completes itself from the replay endpoint (GET /v1/session/events?after=seq); afterreplay_attemptspolls withoutdoneit raisesEvokaiConnectionErrorwith codeincomplete_turn. - Server-sent events are parsed by the client itself: comments (
: pingevery 10 seconds), multi-linedata:, CR/LF/CRLF line ends and chunks that split anything, multi-byte characters included.
Confirmations and questions
A tool that changes data never runs directly: the turn ends with a confirm event and done reason confirm.
Send the user's decision and stream the turn that resumes:
for event in session.confirm(pending, approve=True):
...
confirm.why[i] says why items[i] waits: key is confirm.why.writes (a change), confirm.why.policy or
confirm.why.rule (an ask rule, with its label in the application's language).
The person may edit their last question and send it again while it is rewritable (on the stored user message, and on
every done): the last turn is replaced, and the stream starts with conversation and rewritten. A turn that
changed data cannot be rewritten (EvokaiConflictError, code rewrite_after_write):
for event in session.rewrite("Show September instead"):
...
An ask event is answered by sending the chosen option as the next message:
session.answer("The second one").until_done()
session.answer(["Rome", "Milan"]) # several options of a multiple-choice question: "Rome, Milan"
Without streaming
result = session.chat_json("Summarise my week") # Accept: application/json, waits for the end
result.text, result.reason, result.events
External storage (the application keeps the conversation): pass history=[...] (HistoryMessage or plain dicts)
to chat, confirm, answer or chat_json, and append done.messages (or result.messages) to your copy. A
rewrite (session.rewrite(text, history=...), chat_json(text, history=..., rewrite=True)) says where its messages go:
drop your copy from replaced_from first.
The rest of the session API
session.info() # conversation, agent, usage shares, memories, starter questions
session.conversation() # stored messages (events typed), open confirmation, last seq, running turn
session.events(after=0) # replay
session.feedback(message_id, 1) # thumbs up (1), down (-1) or none (None)
session.cancel(turn_id)
session.report_bug("The chart is empty", {"page": "/reports"})
session.exit("1234") # kiosk sessions
session.use_token(new_token) # a refreshed token for the same conversation
# Long-term memory, as the person sees it
listed = session.memories() # listed.memory (mode, consent, active, ask), listed.items (Memory)
session.memory_consent(True) # a no deletes what was remembered; 409 memory_off when the mode is off
session.edit_memory(memory_id, "Prefers short answers") # 400 memory_refused: instructions, secrets, personal data
session.forget_memory(memory_id) # one; forget_memory() deletes everything. Returns how many.
EvokaiServer.session(token) gives a session that shares the server client's HTTP connection pool.
Async
Every class has an async twin with the same methods:
import asyncio
from evokai import AsyncEvokaiServer, TextEvent
async def main() -> None:
async with AsyncEvokaiServer(EVOKAI_URL, EVOKAI_SERVER_KEY) as evokai:
token = await evokai.mint_session_token("user-42", "assistant")
async with evokai.session(token) as session, session.chat("Hi") as stream:
async for event in stream:
if isinstance(event, TextEvent):
print(event.delta, end="")
asyncio.run(main())
Conversations, memories, usage, catalogue
evokai.conversations.list("user-42", limit=10)
evokai.conversations.get(conversation_id, "user-42")
evokai.conversations.delete(conversation_id, "user-42")
evokai.memories.list("user-42")
evokai.memories.forget("user-42") # everything, or memory_id="..." for one fact
evokai.memories.consent("user-42", False) # the person's answer; False deletes what was remembered
evokai.agents()
evokai.voices(language="it-IT")
report = evokai.usage(group_by=["subject", "day"], from_="2026-11-01")
usage() returns amounts (server key only). People never see amounts: before usage reaches a browser, turn it into
shares of the caps with to_usage_shares(report), which drops every amount.
Privacy requests
The subject travels in the body, never in the address:
data = evokai.privacy.export("user-42") # everything Evokai keeps about them
erased = evokai.privacy.erase("user-42") # right to be forgotten; idempotent
erased.conversations, erased.usage_deidentified
evokai.privacy.revoke_sessions("user-42") # sign-out everywhere
Admin API
from evokai import AgentDef, AppPatch
admin = evokai.admin # needs admin_key
admin.application.get()
admin.application.patch(daily_cap_usd=20, allowed_origins=["https://app.example.com"])
admin.application.patch(AppPatch(daily_cap_usd=None)) # None clears; unset fields are not sent
admin.agents.put(
AgentDef(
name="assistant",
model="bedrock:eu.anthropic.claude-sonnet-4-5",
instructions="You help the bookshop staff with orders and returns.",
mcp_servers=["crm"],
channels=["browser"],
)
)
admin.agents.list()
admin.agents.versions("assistant")
admin.agents.delete("assistant")
admin.mcp_servers.put("crm", {"url": "https://crm.example.com/mcp", "auth": "forward_user"})
admin.mcp_servers.test("crm", credential=user_jwt)
admin.mcp_servers.connectors()
admin.skills.put("refunds", {"description": "How refunds work", "body": "..."})
admin.prompts.put("assistant", "You are ...") # returns the version
admin.security.put({"mode": "enforce", "tools": {"deny": ["crm_delete_client"]}})
admin.security.events(control="input.", limit=50)
admin.grants.get()
admin.grants.change([{"kind": "model", "name": "openai:gpt-5", "value": "off"}])
admin.grants.change([{"kind": "code", "name": "*", "value": True}]) # code_run, off until granted
admin.compliance.put_profile({"controller": "Acme S.p.A.", "ai_act": {"annex_iii": []}})
admin.compliance.pack("gdpr", lang="it") # JSON, every statement with its sources
admin.compliance.pack("ai-act", format="html", lang="en") # printable HTML (or "md")
snap = admin.compliance.snapshot("before the November release")
admin.compliance.diff(snap.id, admin.compliance.snapshot().id, lang="en")
admin.keys.rotate(key_id) # the new key is shown only now
admin.usage_summary(from_="2026-11-01")
admin.activity(limit=20)
admin.export() # the application as a config file
Errors
Every failure raises an EvokaiError with status, the service's stable code and a message that is safe to show
(plus fields for invalid requests and body for the rest, e.g. problems of not_granted):
| Class | When |
|---|---|
EvokaiAuthError |
401, 403 (unauthorized, origin, channel, model_not_granted, ...) |
EvokaiNotFoundError |
404 |
EvokaiConflictError |
409 (closed, storage_mode, expired_conversation, ...) |
EvokaiValidationError |
400, 422 (bad_request with fields, not_granted, ...) |
EvokaiRateLimitError |
429 (limit, rate_limited), with retry_after |
EvokaiServerError |
5xx (internal, invalid_output) |
EvokaiConnectionError |
no answer (network, timeout) or a turn that ended without done (incomplete_turn) |
from evokai import EvokaiError, is_expired_conversation
try:
token = evokai.mint_session_token("user-42", "assistant", conversation_id=cid)
except EvokaiError as e:
if is_expired_conversation(e):
token = evokai.mint_session_token("user-42", "assistant")
else:
raise
Models
Requests and answers are pydantic models with snake_case attributes; on the wire they keep the service's names.
Every model keeps fields it does not know yet in model_extra. Methods that take a body accept the model or a plain
mapping (attribute or wire names). A test checks the request models against the service's OpenAPI schema
(clients/typescript/openapi.json), so a renamed or newly required field fails CI.
Development
cd clients/python
uv sync
uv run ruff check src tests && uv run ruff format --check src tests
uv run ty check
uv run pytest -q
uv build
scripts/ci.sh python runs the same gates from the repository root.
License
Apache-2.0, see LICENSE and NOTICE. "Evokai" and its logo are trademarks of Giordano Pescetelli and are not licensed under the Apache License.
Metadata
Release files for evokai-client 0.1.2
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 |
|---|---|---|---|---|
| evokai_client-0.1.2.tar.gz | 53.4 kB | With provenance | Details for evokai_client-0.1.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| evokai_client-0.1.2-py3-none-any.whl | Python 3 | none | any | Details for evokai_client-0.1.2-py3-none-any.whl |
Total release size: 105.4 kB
Release files / evokai_client-0.1.2.tar.gz
| Download URL | evokai_client-0.1.2.tar.gz |
|---|---|
| Size | 53.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9f5fb082cf02ba85b8f503fead74fea7f51f38fb186aaf73fddcc18a5282dc4d
|
|
BLAKE2b-256 checksum How to use checksums |
32a375e1626ec8691459045034691c388a0f1a67209377c674092dc15637c029
|
| 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 20, 2026.
Transparency logRelease files / evokai_client-0.1.2-py3-none-any.whl
| Download URL | evokai_client-0.1.2-py3-none-any.whl |
|---|---|
| Size | 52.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2aed6fa464fc5e623f9636583f141b81bd6a3a504b2c9602e9fce9da907ca3d2
|
|
BLAKE2b-256 checksum How to use checksums |
62f673cc9528ff083db70732a56f943fd4761bf14ce98711ac97563e29f4e89f
|
| 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 20, 2026.
Transparency logSecurity for evokai-client 0.1.2
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 evokai_client-0.1.2.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 20, 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.