Quickstart

In this quickstart, you’ll create a simple Agent, run it locally, and then build and deploy a powerful AI agent to the cloud.

Prerequisites:

Python 3.9 or higher (3.10+ recommended for deployment)
Docker (Required for local runtime) - Install Docker

Step 1: Install Cycls

Install Cycls SDK:

pip install cycls

Step 2: Create a Simple Agent

Create a file named app.py with the following code. This creates a simple agent that replies with a static message.

app.py

import cycls

@cycls.app()
async def app(context):
    yield "Hello, World!"

app.local()

Step 3: Run your Agent

Make sure Docker Desktop is running before starting your agent.

Run the file from your terminal:

python app.py

This will start a local development server with hot-reload. Open http://localhost:8080 to see your agent in action.

Success! You’ve created and run your first Agent locally.

Next: Cloud Deployment (OpenAI Agent)

Now let’s build a simple AI agent powered by OpenAI LLMs and deploy it to the cloud.

Get Your Keys

Get your Cycls API Key.
Get your OpenAI API Key.
Create a .env file in your project root:

.env

CYCLS_API_KEY=your-cycls-key
OPENAI_API_KEY=sk-your-openai-key

You can use any model of your choice, such as OpenAI, Anthropic, or Gemini, etc.

Write the Agent

Update app.py with this complete code:

app.py

import cycls
import os

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

@cycls.app(pip=["openai"], copy=[".env"], auth=True)
async def app(context):
    from openai import AsyncOpenAI

    client = AsyncOpenAI(api_key=os.getenv("OPENAI_API_KEY"))
    response = await client.chat.completions.create(
        model="gpt-4o-mini",
        messages=context.messages,
        stream=True
    )
    async for chunk in response:
        content = chunk.choices[0].delta.content
        if content:
            yield content

# Deploy to cloud
app.deploy()

Pro Tip: Notice how we import openai inside the function? This ensures the package is loaded only when needed inside the container. Cycls automatically loads your .env file—no extra packages needed.

Deploy

Run the script to deploy:

python app.py

You will see the deployment logs and your public URL:

🚀 Deploying...
✅ Deployment successful!
🔗 Service is available at: https://app.cycls.ai

Next Steps

Configure Your Agent

Explore configuration options like dependencies, secrets, and custom UI.

Work with Context

Learn how to use context to store user data and conversation history.

Customize UI

Tailor the chat interface to match your brand.

Get Started

Basics

Guide

Resources

LLMs

Step 1: Install Cycls

Step 2: Create a Simple Agent

Step 3: Run your Agent

Next: Cloud Deployment (OpenAI Agent)

Next Steps

Configure Your Agent

Work with Context

Customize UI

​Step 1: Install Cycls

​Step 2: Create a Simple Agent

​Step 3: Run your Agent

​Next: Cloud Deployment (OpenAI Agent)

​Next Steps

Configure Your Agent

Work with Context

Customize UI

Step 1: Install Cycls

Step 2: Create a Simple Agent

Step 3: Run your Agent

Next: Cloud Deployment (OpenAI Agent)

Next Steps