Build your first agent

This tutorial is for developers new to Cycls. You will build a research agent that searches the web, writes files into the user’s workspace, and shows the result on the canvas. It takes about fifteen minutes. Prerequisites

Python 3.10 or newer
Docker running, for the local step
CYCLS_API_KEY from Cycls Cloud
ANTHROPIC_API_KEY

Set up the directory

mkdir atlas && cd atlas
pip install cycls

Create two env files. The first stays on your machine, the second ships inside the container.

.env

CYCLS_API_KEY=your_cycls_key

.providers.env

ANTHROPIC_API_KEY=sk-ant-your_key

Write the agent

atlas.py

import cycls

image = cycls.Image().copy(".providers.env", ".env")

chats = cycls.Volume("atlas-chats")

web = (
    cycls.Web()
    .auth(cycls.Clerk())
    .title("Atlas")
)

llm = (
    cycls.LLM()
    .model("anthropic/claude-sonnet-4-6")
    .system("You are a research assistant. Cite sources and keep answers short.")
)


@cycls.agent(image=image, web=web, volumes={"/workspace": chats})
async def atlas(context):
    async for ev in llm.run(context=context):
        yield ev

Four declarations and a body. image describes the container, chats is where conversations and files live, web configures the interface and sign-in, and llm configures the model.

Run it

cycls run atlas.py

The first build takes a minute or two. When it finishes, open http://localhost:8080 and ask a question. Saving the file rebuilds and reloads.

Add tools

Replace the llm block:

llm = (
    cycls.LLM()
    .model("anthropic/claude-sonnet-4-6")
    .system("You are a research assistant. Cite sources and keep answers short.")
    .allowed_tools(["WebSearch", "Bash", "Editor", "Canvas"])
    .sandbox(network=False)
)

Save, then ask for something that needs work, for example:

Compare the three largest Saudi banks by total assets and write the result to banks.md.

The agent searches, writes the file into the workspace, and opens it on the canvas. Each tool carries its own prompt guidance, so nothing else is needed.sandbox(network=False) removes network access from the bash tool. Web search still works, because it runs outside the sandbox.

Brand it

web = (
    cycls.Web()
    .auth(cycls.Clerk())
    .title("Atlas")
    .brand(name="Atlas", description="Research assistant for market questions")
    .suggestions(True)
)

The name and description appear on the empty chat screen. Add logo="./icon.svg" once you have an icon.

Track cost

llm = (
    cycls.LLM()
    .model("anthropic/claude-sonnet-4-6")
    .system("You are a research assistant. Cite sources and keep answers short.")
    .allowed_tools(["WebSearch", "Bash", "Editor", "Canvas"])
    .sandbox(network=False)
    .price(input=3, output=15, cache_read=0.30, cache_write=6)
)

Prices are USD per million tokens. With them set, every turn logs its cost and cycls cost atlas reports spend.

Limit the free tier

from datetime import datetime, timezone

FREE_MONTHLY_LIMIT = 10


@cycls.agent(image=image, web=web, volumes={"/workspace": chats})
async def atlas(context):
    db = cycls.DB(context.workspace)
    month = datetime.now(timezone.utc).strftime("%Y-%m")
    entry = await db.get(f"usage/{month}", {"count": 0})

    if context.prod and context.user.plan == "u:free_user" and entry["count"] >= FREE_MONTHLY_LIMIT:
        yield {"type": "callout", "callout": "Free limit reached this month.", "style": "warning"}
        yield {"type": "ui", "action": "open_plan_modal"}
        return

    entry["count"] += 1
    await db.put(f"usage/{month}", entry)

    async for ev in llm.run(context=context):
        yield ev

context.prod is False under cycls run, so your local loop is never blocked.

Deploy

cycls deploy atlas.py
#   [DONE] https://atlas.cycls.ai

Check it is live, then watch it:

cycls ls
cycls logs atlas -f
cycls cost atlas

The finished file

atlas.py

from datetime import datetime, timezone

import cycls

image = cycls.Image().copy(".providers.env", ".env")

chats = cycls.Volume("atlas-chats")

web = (
    cycls.Web()
    .auth(cycls.Clerk())
    .title("Atlas")
    .brand(name="Atlas", description="Research assistant for market questions")
    .suggestions(True)
)

llm = (
    cycls.LLM()
    .model("anthropic/claude-sonnet-4-6")
    .system("You are a research assistant. Cite sources and keep answers short.")
    .allowed_tools(["WebSearch", "Bash", "Editor", "Canvas"])
    .sandbox(network=False)
    .price(input=3, output=15, cache_read=0.30, cache_write=6)
)

FREE_MONTHLY_LIMIT = 10


@cycls.agent(image=image, web=web, volumes={"/workspace": chats})
async def atlas(context):
    db = cycls.DB(context.workspace)
    month = datetime.now(timezone.utc).strftime("%Y-%m")
    entry = await db.get(f"usage/{month}", {"count": 0})

    if context.prod and context.user.plan == "u:free_user" and entry["count"] >= FREE_MONTHLY_LIMIT:
        yield {"type": "callout", "callout": "Free limit reached this month.", "style": "warning"}
        yield {"type": "ui", "action": "open_plan_modal"}
        return

    entry["count"] += 1
    await db.put(f"usage/{month}", entry)

    async for ev in llm.run(context=context):
        yield ev

Get started

Functions

Apps

Agents

Interface and users

Ship it

Guides

Reference

Resources

For LLMs

Build your first agent

The finished file

Where to go next

Add a custom tool

Query a data warehouse

​The finished file

​Where to go next

Add a custom tool

Query a data warehouse

The finished file

Where to go next