Skip to main content

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, error and done. Each carries turn_id and seq. A type this client does not know yet arrives as UnknownEvent with every field in event.data, so a newer service never breaks you.
  • stream.turn_id (from the X-Turn-Id header), stream.text (the deltas so far), stream.done and stream.until_done() help when you do not need every event.
  • Leaving the with block (or break, or stream.close()) closes the connection, and the service cancels that turn. session.cancel(turn_id) cancels it explicitly and the stream still ends with done.
  • If the connection drops before done, the stream completes itself from the replay endpoint (GET /v1/session/events?after=seq); after replay_attempts polls without done it raises EvokaiConnectionError with code incomplete_turn.
  • Server-sent events are parsed by the client itself: comments (: ping every 10 seconds), multi-line data:, 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.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for evokai-client 0.1.3
File Size Uploaded Provenance Actions
evokai_client-0.1.3.tar.gz 53.4 kB With provenance Details for evokai_client-0.1.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for evokai-client 0.1.3
File Interpreter ABI Platform Actions
evokai_client-0.1.3-py3-none-any.whl Python 3 none any Details for evokai_client-0.1.3-py3-none-any.whl

Total release size: 105.4 kB

Release files / evokai_client-0.1.3.tar.gz

Download URL evokai_client-0.1.3.tar.gz
Size 53.4 kB
Tags Source
SHA-256 checksum
How to use checksums
beadcc3fa283d367eb130e33a2a57610ae74a2119109c701db878306b43295d5
BLAKE2b-256 checksum
How to use checksums
26bb348806c446d9880ee99de74055d06d37379828e0a9299580d6b3ea39106c
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 21, 2026.

Transparency log

Release files / evokai_client-0.1.3-py3-none-any.whl

Download URL evokai_client-0.1.3-py3-none-any.whl
Size 52.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
143e527e982b087148dbec0ea156810fa4516a45e6900fda1fa4d0ebbd86edbf
BLAKE2b-256 checksum
How to use checksums
b12fff72026ba52cc8a68cc7ca3a4b45d53f423580d442c0e752747dff3505ff
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 21, 2026.

Transparency log

Security for evokai-client 0.1.3

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.

Select from 2 files

Attestation for evokai_client-0.1.3.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 21, 2026.

Transparency log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page