Tools

Tools come from two places. Built-in tools ship with the SDK and are enabled by name. Custom tools are JSON schemas you define with async handlers you write.

llm = (
    cycls.LLM()
    .model("anthropic/claude-sonnet-4-6")
    .allowed_tools(["Bash", "Editor", "WebSearch", "Canvas"])   # built in
    .tools(MY_TOOLS)                                            # your schemas
    .on("create_ticket", create_ticket)                         # your handler
)

Built-in tools

Each name enables one or more tools and brings its own prompt guidance, so enabling it is the only switch you need.

Name	What the model gets
`Bash`	`bash`: run shell commands in a sandbox rooted at the workspace
`Editor`	`read` and `edit`: view and modify workspace files
`WebSearch`	`web_search` and `web_fetch`, or the provider’s native search
`Browser`	`browser`: drive a real Chrome session, only offered when a browser service is configured
`DataBase`	`database`: a per-user key-value store with prefix scans
`Canvas`	`canvas`: open a finished file in the side panel viewer
`Apps`	`build_app`: bundle a source folder into an installable mini app
`Suggest`	`suggest`: one follow-up chip above the composer
`Ask`	`ask`: up to three questions on one card, which ends the turn

Runs inside a bubblewrap sandbox with the user’s workspace bound at /workspace and a sanitized environment. The working directory is the workspace, scratch belongs in .tmp/, and /tmp is per-command and discarded.

llm = cycls.LLM().allowed_tools(["Bash"]).bash_timeout(600).sandbox(network=True)

Network access is on by default so curl, pip and git work. A prompt injection can exfiltrate anything the sandbox can read, so turn it off when the agent does not need it:

llm = cycls.LLM().allowed_tools(["Bash"]).sandbox(network=False)

read renders files, including PDFs page by page and images for vision models. edit creates and modifies files. The model is told to use these rather than cat or sed, which keeps writes inside the safety checks and off the output token budget.Paths are workspace relative. Traversal outside the workspace is refused, and so are the reserved internal directories.

llm = cycls.LLM().allowed_tools(["WebSearch"]).web_search("brave")

brave is the portable pair, web_search plus web_fetch. It works on every provider and needs BRAVE_API_KEY. Results arrive in the UI as one sources row of citation chips at the end of the answer. native uses the provider’s server-side search, which is Anthropic only today.

A real Chrome session driven step by step: open, read, click, type, press, back, evaluate, screenshot, download. The page persists between calls in a turn, so logins and multi-step forms work.The browser itself runs in a shared service, not in your image. Configure it with environment variables, and the tool is not offered when they are unset:

BROWSER_PROVIDER=cycls
BROWSER_URL=https://cycls-browser.cycls.ai
BROWSER_SECRET=your_shared_secret

A per-user JSON key-value store with get, put, delete and scan. It is private to the user: no teammate and no app can read it. Use it for agent memory across chats, such as preferences and task progress.Anything a teammate or an app needs to read belongs in a workspace file or under apps/<slug>/data/ instead.

Canvas opens one finished deliverable in the side panel. It renders markdown, HTML, PDF, images, audio, video, code, CSV, spreadsheets and 3D models. Office formats render read-only through the office service, and anything else falls back to a download card.Apps lets the agent bundle a source folder into a single self-contained HTML file installed in the Apps tab. Apps run under a strict CSP with no external fetch, and reach their own data through a small bridge, so a dashboard stays live without holding any key.

Suggest shows one follow-up chip above the composer, written in the user’s voice. Ask puts up to three questions on one card and ends the turn, with the answers arriving as the next user message. The options are shortcuts, not a gate: the user can type anything instead.Users can switch both off in Settings, and context.disabled_tools reflects that for the turn.

A user can switch a tool off in Settings. LLM.run() drops those tools for the turn. A switch can never enable a tool the operator did not allow.

Custom tools

A tool schema is a plain dict. A handler is an async function. The return value goes to the UI stream and to the model as the tool_result, so one return covers both destinations.

TOOLS = [
    {
        "name": "create_ticket",
        "description": "Open a support ticket for the current user.",
        "inputSchema": {
            "type": "object",
            "properties": {
                "title": {"type": "string"},
                "priority": {"type": "string", "enum": ["low", "high"]},
            },
            "required": ["title"],
        },
    }
]


async def create_ticket(args):
    ticket = await support.create(args["title"], args.get("priority", "low"))
    return f"Created ticket {ticket.id}"


llm = (
    cycls.LLM()
    .model("anthropic/claude-sonnet-4-6")
    .tools(TOOLS)
    .on("create_ticket", create_ticket, label=lambda i: i["title"])
)

Handler signature

A handler takes the tool input, and optionally a second argument with request context.

async def create_ticket(args, ctx):
    ws = ctx.workspace          # the caller's workspace
    user = ctx.user             # the authenticated user
    return f"Created for {user.id}"

Presentation

.on() controls how the call appears in the UI.

Argument	Effect
`label`	a function from input to a string, rendering the step line like `Bash(command)`. Defaults to the first string value in the input
`icon`	an image URL shown where a connector logo goes
`details=True`	the step opens into Request and Response panes, and the result goes there instead of into the chat. The model still receives all of it

llm = cycls.LLM().on(
    "search_orders",
    search_orders,
    label=lambda i: f"orders for {i['email']}",
    icon="https://example.com/logo.png",
    details=True,
)

Returning UI components

A handler can return a component dict instead of text, and it renders in the conversation.

async def render_chart(args):
    path = await make_chart(args["series"])
    return {"type": "image", "src": path, "caption": "Revenue by month"}

Reserved names

skill and find_tools are reserved by the loop. skill loads a skill on demand, and find_tools loads a connector’s tools when the model needs them.

Get started

Functions

Apps

Agents

Interface and users

Ship it

Guides

Reference

Resources

For LLMs

Built-in tools

Custom tools

Handler signature

Presentation

Returning UI components

Reserved names

Next steps

Custom tool guide

Connectors

​Built-in tools

​Custom tools

​Handler signature

​Presentation

​Returning UI components

​Reserved names

​Next steps

Custom tool guide

Connectors

Built-in tools

Custom tools

Handler signature

Presentation

Returning UI components

Reserved names

Next steps