Agents

A chat product in one decorator: managed LLM loop, tools, files, history and a web interface.

An agent is an async generator that receives a context and yields events. Cycls wraps it in a web application, a streaming protocol, per-user storage and a managed model loop.

agent.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(
    image=cycls.Image().copy(".providers.env", ".env"),
    web=cycls.Web().auth(cycls.Clerk()).title("My Agent"),
    volumes={"/workspace": cycls.Volume("my-agent")},
)
async def my_agent(context):
    async for ev in llm.run(context=context):
        yield ev

cycls run my_agent.py      # localhost:8080
cycls deploy my_agent.py   # https://my-agent.cycls.ai

The decorator

@cycls.agent(name=None, image=None, web=None, volumes=None, memory="1Gi")

Argument	Meaning
name	deployment name and subdomain. Defaults to the function name
image	cycls.Image for packages and bundled files
web	cycls.Web for interface, auth and branding
volumes	mount paths to cycls.Volume. A /workspace entry is required
memory	container memory, for example "1Gi", "4Gi"

Agents keep chats, files and credentials under /workspace, so the decorator raises if no volume is mounted there. Locally, cycls run ignores volumes and your code sees the local filesystem.

What the managed loop does

llm.run(context=context) is the default loop. Yielding its events through your body is all a normal agent needs.

Model calls and streaming

Text, reasoning and tool-call deltas from Anthropic natively and from any OpenAI-compatible endpoint.

Tool execution

Built-in tools and your handlers, run in parallel where the provider sends a batch, with results fed back to the model.

Retries and recovery

Transient provider failures are retried with backoff. Context overflow triggers one compaction and a replay.

Compaction

When the window fills, older turns are summarized behind an append-only marker so the conversation continues.

Persistence

The user’s turn is written to disk before the model is called, so a dropped connection never loses it.

Cost accounting

Every turn logs tokens and cost when .price() is set, queryable with cycls cost and cycls sql.

A turn, end to end

Yielding your own events

The body is ordinary Python, so you can emit anything before, during or after the loop. Events are plain dicts, and strings are markdown text.

@cycls.agent(web=web, volumes={"/workspace": chats})
async def my_agent(context):
    if context.user.plan == "u:free_user" and await over_quota(context):
        yield {"type": "callout", "callout": "Free limit reached.", "style": "warning"}
        yield {"type": "ui", "action": "open_plan_modal"}
        return

    yield {"type": "status", "status": "Thinking about it"}

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

    yield "\n\n_Answered by My Agent._"

See Streaming components for every event type.

Watching the loop

Events are dicts, so a plain check is enough to react without changing behavior.

async for ev in llm.run(context=context):
    if isinstance(ev, dict) and ev.get("type") == "callout" and ev.get("style") == "error":
        alert_ops(ev["callout"])
    yield ev

cycls.to_ui(ev) still appears in older examples. It is now an identity function kept for backwards compatibility, so yield ev and yield cycls.to_ui(ev) do the same thing.

Adding HTTP routes

An agent is also a web service. Use .server for webhooks, health checks and OAuth callbacks, and Depends(my_agent.auth) to protect a route with the same identity the chat endpoint uses.

from fastapi import Depends


@my_agent.server.api_route("/webhook", methods=["POST"])
async def webhook(request):
    payload = await request.json()
    return {"ok": True}


@my_agent.server.api_route("/profile", methods=["GET"])
async def profile(user=Depends(my_agent.auth)):
    return {"id": user.id, "plan": user.plan}

Next steps

Models

Providers, reasoning, budgets and pricing.

Tools

Built-in tools and your own handlers.

Context

Messages, users, workspaces and per-request switches.

Custom loops

Replace the default loop while keeping the kit.