crewai-ceki 0.1.0

CrewAI toolkit for Ceki — real Chrome sessions for AI agents with persistent profiles across runs

crewai-ceki

CrewAI toolkit for Ceki — drive a real Chrome session from your CrewAI agent.

Killer combo. CrewAI's structured planning + Ceki's profile export = browser sessions that remember themselves across runs. Log in once, your crew walks straight into the dashboard on the next run — no cookies in your code, no second login.

Install

pip install crewai-ceki

The squat alias ceki-crewai is reserved by the same project and depends on crewai-ceki — both resolve to the same symbols.

Architecture

Variant C — structural toolkit. Eleven crewai.tools.BaseTool subclasses that the CrewAI agent's own LLM plans across:

Tool	What it does
ceki_rent_browser	Rent a real Chrome session and return its session_id.
ceki_navigate	Open a URL.
ceki_click	Click at viewport coordinates. Mouse jitter ON by default.
ceki_type	Type into the focused element. Cadence + jitter ON by default.
ceki_scroll	Scroll by delta_y pixels.
ceki_screenshot	PNG of the current viewport as base64.
ceki_snapshot	Screenshot + drained chat messages from the provider.
ceki_chat_send	Send a chat message to the human provider (captcha / OTP).
ceki_stop	End the session — always call this when done.
ceki_export_profile	Killer: export cookies/storage/fingerprint to disk.
ceki_restore_profile	Killer: restore a saved profile into a fresh rent.

There is no server-side NL endpoint and no LLM lives inside this package — your CrewAI agent's own model does the planning.

Quick start

import os
os.environ["CEKI_API_KEY"] = "your_ceki_key"   # https://ceki.me dashboard

from crewai import Agent, Task, Crew
from crewai_ceki import CekiCrewaiToolkit

toolkit = CekiCrewaiToolkit(default_rent={"schedule_id": 4242})

browser_agent = Agent(
    role="Web Operator",
    goal="Drive the rented browser to complete the task.",
    backstory=(
        "You operate a real Chrome session via the ceki_* tools. After a "
        "successful login, ALWAYS call ceki_export_profile so future runs "
        "can skip the login. On a fresh rent for a site you previously "
        "logged into, ALWAYS try ceki_restore_profile BEFORE navigating."
    ),
    tools=toolkit.get_tools(),
)

task = Task(
    description="Open https://example.com and report the page title.",
    expected_output="The page title as a string.",
    agent=browser_agent,
)

try:
    Crew(agents=[browser_agent], tasks=[task]).kickoff()
finally:
    toolkit.close()

The killer combo — persistent profiles

Tell your agent in its backstory:

After a successful login, always call ceki_export_profile.
On a fresh rent for a previously-logged-in site, always call
ceki_restore_profile before navigating.

That is the entire setup. Now every login the crew performs is durable:

# Run A — crew logs into your.example.com, then:
ceki_export_profile(session_id, profile_name="your-example")
# → JSON written to ~/.cache/ceki-crewai/profiles/your-example.json

# Process restarts. The file survives.

# Run B — fresh rent on a new browser:
ceki_restore_profile(session_id, profile_name="your-example")
# → cookies, localStorage, sessionStorage, fingerprint all restored
ceki_navigate(session_id, "https://your.example.com/dashboard")
# → already authenticated

By default profiles live under ~/.cache/ceki-crewai/profiles/. Override with:

from pathlib import Path
toolkit = CekiCrewaiToolkit(
    default_rent={"schedule_id": 4242},
    profile_dir=Path("/var/lib/myapp/ceki-profiles"),
)

Or override via the CEKI_PROFILE_DIR environment variable. If you'd rather keep the JSON in your own store, pass it via the payload argument to either tool and the toolkit skips the disk read/write.

See examples/persistent_session.py for an end-to-end runnable demo.

Use responsibly

Use only on sites you own or have authorization to operate on (your own apps, your own dashboards, public data within site Terms of Service, accessibility audits you're responsible for).

License

MIT.