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`: the user’s own key-value memory, and the workspace’s app data
`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. With a document parser, documents (PDF, Word, PowerPoint, Excel, OpenDocument, RTF, EPUB) come back as Markdown text. Without one, a PDF up to 3MB goes to the model whole, a larger one is read as page images, and other formats are left to bash. PDF pages come back as images whenever the model asks for them with pages, up to 20 a call, for scans, charts or checking a page. Images go to vision models as they are. 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.One read returns at most 50,000 characters and ends with the line to continue from, so a large file or attachment arrives in pages instead of filling the context window. A long parsed document shows its first 20,000 characters, and its full text is kept in the chat’s .tmp/ folder for the model to read on or search.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, the default, is the portable pair, web_search plus web_fetch. It works on every provider and needs BRAVE_API_KEY. Without the key, an Anthropic model gets native search instead, and on other providers web_search returns an error while web_fetch still works. 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.Two optional variables set deployment-wide defaults, which the model can override per query:

BRAVE_COUNTRY=sa       # a two-letter country code that biases ranking
BRAVE_SEARCH_LANG=ar   # a two-letter language code that restricts results

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.open also takes a workspace .html, .htm or .svg file by its path, or as /workspace/... or file://..., so the agent can look at a page it wrote. The file’s text is written into a blank tab, with no site’s origin or cookies, and the page is read once it loads or after 15 seconds. The browser gets nothing but that text, so anything the page loads by a relative path, such as an image, must be inlined. localhost, 127.0.0.1 and 0.0.0.0 addresses are refused, because the browser runs on another machine.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_URL=https://browser.example.com   # your browser service
BROWSER_SECRET=your_service_secret        # sent as a Bearer token

`BROWSER_PROVIDER`	`BROWSER_URL`	`BROWSER_SECRET`
`steel`, the default	a Steel Browser service. Each chat gets its own session	required
`cdp`	a Chrome DevTools endpoint, such as `http://host:9222`. Every chat shares that one browser	not needed

A JSON key-value store with get, put, delete and scan. The key decides whose data it is.

Key	Holds	Shared with
anything outside `apps/`	the agent’s memory of this user in this workspace, such as preferences and task progress	nobody: no teammate and no app reads it
`apps/<slug>/<key>`	an app’s data, the rows the app reads and writes with `cycls.get` and `cycls.set`	the whole workspace

Anything a teammate must read belongs in a workspace file or an app’s data, not in memory.database is the agent’s only way into app data: bash sees an empty .apps folder, the file tools refuse it, and the /files API answers 403. A scan with the prefix apps/<slug>/ lists an app’s keys. In a team workspace, an app whose app.json sets "write": "admin" takes writes only from the workspace’s owners and admins. The app’s data/ folder is something else: its files, which bash and the file tools reach like any other.Users manage their memory in the web client under Settings, General, Memory. Each entry in the active workspace shows as a plain-text note they can edit or delete. Turning Memory off removes the database tool from their chats in every workspace, along with the agent’s way into app data. What was saved stays.

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 the workspace through a small bridge the host page runs for them:

In the app	What it does
`cycls.read(path)`, `cycls.write(path, text)`	text files in the app’s own folder. Writes go under its `data/` folder only
`cycls.get(key)`, `cycls.set(key, value)`	the app’s key-value data, shared by the workspace. `set` writes at once
`cycls.save(name, text)`	asks the user where to save a file, anywhere in the workspace
`cycls.connector(name).json(path, init)`	calls a connected connector’s API with the credential attached server-side, so a dashboard stays live without holding a key

The agent reads and writes the same key-value data with database. In a team workspace, "write": "admin" in the app’s app.json limits writing it to the workspace’s owners and admins.

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: every question with options ends with a line where the user writes their own answer, so the model never needs an “Other” option.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.

Document parser

read can send documents to a parser you deploy as a function, and give the model the Markdown it returns. The parser receives the file’s bytes and name, and returns three keys.

doc_parser.py

import cycls


@cycls.function(image=cycls.Image().pip("pypdf"))
def doc_parser(data: bytes, name: str, mode: str = "markdown"):
    import io
    from pypdf import PdfReader

    if not name.lower().endswith(".pdf"):
        return {"content": "", "warnings": [], "page_count": 0}
    pages = PdfReader(io.BytesIO(data)).pages
    return {
        "content": "\n\n".join(page.extract_text() or "" for page in pages),
        "warnings": [],
        "page_count": len(pages),
    }

Key	Meaning
`content`	the document as Markdown. Empty means no text, such as a scan, and `read` goes on without the parser
`warnings`	lines shown to the model above the text
`page_count`	a PDF’s page count, shown so the model can ask to see a page with `pages`

Deploy it, then name it in the agent container’s environment:

cycls deploy doc_parser.py
# Deployed: https://doc-parser.cycls.ai

.providers.env

CYCLS_PARSER=doc-parser
CYCLS_API_KEY=...    # the key that deployed doc-parser

The agent calls the parser with cycls.remote, and a deployment answers only the key that deployed it, so the agent’s container needs that key. read sends PDF, Word, PowerPoint, Excel, OpenDocument, RTF and EPUB files up to 50MB, and waits up to 120 seconds. A read with pages skips the parser. A call that fails falls back to reading without it and writes a level=parser log record with the error. The default, cycls-parser, is the parser Cycls runs for its own agents and answers only Cycls’s key. Set CYCLS_PARSER to your deployment, or to an empty string to skip the call.

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
    grant = await ctx.secret("linear")    # {"key": ...}, or None if not connected
    return f"Created for {user.id}"

ctx.secret(name) reads what was stored for the connector name, the user’s own grant before the workspace’s. An API key comes back as {"key": ...}, and an OAuth grant as stored, with access_token and expires_at. ctx.secret does not refresh an expired token. A handler that raises sends Error: and the exception to the model as the result, and the turn goes on.

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
`picture`	a function from input to the shape of a picture the tool makes, such as `"16:9"`. While the call runs, the chat holds a frame of that shape, and the picture the tool opens with `open_canvas` takes its place

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. It renders in the conversation, and the model reads it as JSON.

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

To give the model and the chat different things, return two channels. _model becomes the tool result, and _ui is one event or a list of events for the chat.

async def search_docs(args):
    hits = await index.search(args["query"])   # [{"title", "url", "snippet"}]
    return {
        "_model": json.dumps(hits),
        "_ui": {"type": "sources", "sources": hits},
    }

A tool’s sources and the files it opens are kept with the chat, so they come back after a reload. A link in the answer to a source’s url becomes its chip, and a source can say more than its title:

Key	Shown as
`label`	the chip’s words, in place of the site’s name
`quote`	the words cited, on the card
`status`	a short state on the card, such as “In force”
`note`	one line of context under the quote

A file a tool opens with an open_canvas event in _ui also stands in the conversation as its card, and a picture as itself. A handler can also return a client action with an ack. The client gets the action, and the model reads ack in its place. A confirm or connect action ends the turn, because the user has to answer first.

Reserved names

skill and find_tools are reserved by the loop. skill loads a skill on demand and publishes one with action: "publish". It is offered every turn, even before any skill exists, unless you set .skills(None). find_tools loads a connector’s tools when the model needs them. A built-in tool’s name, such as bash, read or database, is taken too: a custom tool with that name runs the built-in.

Get started

Functions

Apps

Agents

Interface and users

Ship it

Guides

Reference

Resources

For LLMs

Built-in tools

Document parser

Custom tools

Handler signature

Presentation

Returning UI components

Reserved names

Next steps

Custom tool guide

Connectors

​Built-in tools

​Document parser

​Custom tools

​Handler signature

​Presentation

​Returning UI components

​Reserved names

​Next steps

Custom tool guide

Connectors

Built-in tools

Document parser

Custom tools

Handler signature

Presentation

Returning UI components

Reserved names

Next steps