Introduction

Cycls is the deep-stack AI SDK for Python. Runtime, interface, intelligence and state are composable primitives in one file, deployed with one command.

Write the agent, the container it runs in, the interface it serves and the storage it keeps, in one Python file. Then ship it.

hello.py

import cycls

llm = (
    cycls.LLM()
    .model("anthropic/claude-sonnet-4-6")
    .system("You are a helpful assistant.")
    .allowed_tools(["Bash", "Editor", "WebSearch"])
)


@cycls.agent(volumes={"/workspace": cycls.Volume("hello-chats")})
async def hello(context):
    async for ev in llm.run(context=context):
        yield ev

cycls deploy hello.py
#   https://hello.cycls.ai

That deploy produces a chat interface, sign-in, per-user file storage, chat history, share links, an OpenAI-compatible API endpoint and a sandboxed tool loop. There is no Dockerfile, no YAML and no separate infrastructure repository.

Every agent ships with this interface. Text, tables, code, files and tool steps stream as the model produces them.

The four layers

Layer	Primitive	What you declare
Runtime	cycls.Image	pip packages, system packages, bundled files, build commands
Interface	cycls.Web	branding, auth, themes, analytics, workspaces
Intelligence	cycls.LLM	model, system prompt, tools, budgets, reasoning
State	cycls.Volume	named persistent storage, attached by mount path

Each primitive is an immutable builder, so every method returns a new object and one base configuration can be branched without side effects.

Three decorators

Decorators accept exactly the primitives they need. Each one extends the layer below it, so anything a function can do, an app can do, and anything an app can do, an agent can do.

@cycls.agent      chat product, managed LLM loop, web UI
  extends
@cycls.app        blocking ASGI service, auth, per-user storage
  extends
@cycls.function   containerized Python, volumes, schedules

Function

Run Python in a container locally, in the cloud, or on a schedule. Freeze it as a named endpoint anyone with your key can call.

App

Return a FastAPI application and get a URL, sign-in and per-user storage.

Agent

A chat product with a managed model loop, tools, memory, files and a web interface.

What an agent includes

Interface

Streaming chat in light and dark, English and Arabic, a file canvas, voice input, share links and generated social previews.

Managed loop

Tool calling, retries, context compaction, cost accounting, and background runs that survive a dropped connection.

Tools

Sandboxed bash, file editing, web search, a real browser, a key-value store, a canvas, app building, and your own Python handlers.

State

Per-user files and chats on a volume you own, team workspaces, trash and restore, and shareable conversations.

Identity

Clerk out of the box or any OIDC provider. Organizations, roles, plans and feature flags arrive as context.user.

Connectors

OAuth and API-key grants a user makes once, with per-tool approvals, an audit trail, and remote MCP servers on any provider.

Model support

One builder covers Anthropic natively and every OpenAI-compatible endpoint through a base URL.

cycls.LLM().model("anthropic/claude-sonnet-4-6")
cycls.LLM().model("openai/gpt-5.4")
cycls.LLM().model("groq/llama-3.3-70b").base_url("https://api.groq.com/openai/v1")
cycls.LLM().model("local/qwen3").base_url("http://localhost:8000/v1")

Reasoning control, tool calls and streaming are unified across providers. See Models.

Start here

Quickstart

Install, run locally, deploy. About five minutes.

Core concepts

Layers, builders, and the difference between run, remote and deploy.

Build your first agent

A guided build with tools, branding and a quota check.

CLI reference

Every command, flag and default.