Build Agents

The @cycls.app() decorator is your main interface for configuring dependencies, authentication, and deployment settings. Write a function, decorate it, and Cycls handles the rest. Here is a full example of an agent configuration:

import cycls

@cycls.app(
    pip=["openai", "pandas"],       # Python packages to install
    apt=["ffmpeg"],                 # System packages via apt
    copy=["data.csv", ".env"],      # Local files to bundle
    copy_public=["logo.png"],       # Public assets (images, etc.)
    auth=True                       # Enable authentication
)
async def app(context):
    # Your agent logic here
    yield "Hello! I am ready to help."

# Run locally for development
app.local()

Deployment Modes

Local Development (`app.local()`)

Running app.local() builds a portable Docker image containing your agent and all dependencies. The image includes a pre-configured FastAPI server that serves the REST API and the web interface.

Requirement: You must have Docker installed and running.

app.local()

You will see the build logs and your local URL:

Successfully built de0e95b9ae6d
Successfully tagged cycls/app:52afe9dc9be77162
----------------------------------------
✅ Base image built successfully
--- 🪵 Container Logs (streaming) ---
🔨 Visit app => http://localhost:8080
INFO:     Started server process [1]
INFO:     Application startup complete.

Result: A locally running Docker container serving your agent.
Hot Reload: By default, the server watches for file changes and restarts automatically.
Portability: You can take this image and deploy it to any cloud provider or on-premise server.
URL: http://localhost:8080

Development Options

# Standard development with hot-reload
app.local()

# Disable file watching
app.local(watch=False)

Cloud Deployment (`app.deploy()`)

Running app.deploy() auto-builds your agent and deploys it to Cycls’ serverless infrastructure in a single command.

import cycls
import os

# Set your API key
cycls.api_key = os.getenv("CYCLS_API_KEY")

@cycls.app(pip=["openai"])
async def app(context):
    yield "Hello from the cloud!"

app.deploy()

Result: A live, auto-scaling API and web interface.
Features: Managed SSL, built-in auth, global CDN.
URL: https://<app-name>.cycls.ai

Configuration Reference

`@cycls.app()` Decorator

The decorator transforms your function into a deployable agent with all configuration in one place.

Decorator

Hide parameters

list[string]

List of Python package names to install (e.g., ["openai", "pandas"]).

list[string]

System-level dependencies to install via apt (e.g., ["ffmpeg"]).

list[string]

List of local files or directories to bundle with your agent (e.g., [".env", "data"]).

list[string]

List of local files to copy to the public assets folder (e.g., ["logo.png"]). Accessible via /public endpoint.

boolean

If True, enables built-in user authentication (Sign in with Google/Email). Default is False.

string

Set to "cycls_pass" to enable Cycls Pass monetization with automatic feature gating.

`app.local()`

Method

Hide parameters

boolean

True (default): Enables hot-reload, automatically restarting on code changes.
False: Runs without file watching.

`app.deploy()`

Deploys your agent to the Cycls cloud. Requires cycls.api_key to be set.

import cycls
cycls.api_key = "your-api-key"

app.deploy()

Next Steps

Manage Context

Learn how to use context to access conversation history.

Get Started

Basics

Guide

Resources

LLMs

Build Agents

Deployment Modes

Local Development (`app.local()`)

Development Options

Cloud Deployment (`app.deploy()`)

Configuration Reference

`@cycls.app()` Decorator

`app.local()`

`app.deploy()`

Next Steps

Manage Context

​Deployment Modes

​Local Development (app.local())

​Development Options

​Cloud Deployment (app.deploy())

​Configuration Reference

​@cycls.app() Decorator

​app.local()

​app.deploy()

​Next Steps

Manage Context

Deployment Modes

Local Development (`app.local()`)

Development Options

Cloud Deployment (`app.deploy()`)

Configuration Reference

`@cycls.app()` Decorator

`app.local()`

`app.deploy()`

Next Steps