Enable built-in tools by name, or register your own Python handlers. Both stream into the same UI.
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
Agent
agent: hand a part of the work to an agent of its own, in the background
Bash
Editor
WebSearch
Browser
DataBase
Canvas and Apps
Suggest and Ask
Agent
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.
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:
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.
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 rankingBRAVE_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. So are files under apps/<slug>/: an app reaches
its data only beside the chat, so the browser would show it empty.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 serviceBROWSER_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.The agent changes an app’s data only from what it read. A put or delete on an
app’s key is refused when the agent never read that key in the conversation, or
when someone changed it in the app since, and the agent is told to read it again.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.The user sees every canvas call in the chat, and the canvas shows the model
nothing. So a reply opens one deliverable, and other files go in it as links. The
agent checks its own work with read, which returns a picture or a PDF’s pages to
it, and keeps pictures made for that in .tmp/, which the canvas refuses. Pictures
meant for the user go in the reply as images.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.onChange(fn)
runs fn when the app’s data or files changed under it, by the agent, a teammate or another tab. cycls.refresh() checks at once
cycls.ctx.user, cycls.people()
who is viewing, as {id, name, role}, and the workspace’s members with their pictures. Store ids, never names
cycls.who(key)
who last changed a shared key, and when
cycls.onTheme(fn)
runs fn when the chat switches between light and dark. The app’s <html> gets the dark class by itself
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.An open app without an onChange listener is reloaded when the agent changes its
data, never for a teammate’s change. Fonts, images and sounds in the app’s src/
that its code refers to are written into the app, since it loads nothing from the
network.
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.
agent starts an agent of the agent’s own with a short label and a brief, and
returns at once. The new agent works in the background, in the same workspace with
the same tools, while the chat carries on. When it finishes, its report reaches the
agent that started it as a message, and that agent tells the user what matters.
Up to four work at once in a chat. They can’t start agents of their own or ask the
user anything, and the run’s 45 minutes cover all of them. The chat shows them in
one card, a row each, and a row opens that agent’s work.Agents cost several times a normal turn. To keep them to some users, such as paid
plans, add the tool for that request: llm.allowed_tools([*TOOLS, "Agent"]) returns
a new builder, so the others keep their list.
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_PARSER=doc-parserCYCLS_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.
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 connectorname, 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, the step’s line in the chat. It may return {"en": ..., "ar": ...} so each language gets its own words. Defaults to the first string value in the input
title
what the tool did, for the collapsed line of steps, such as “checked market data”. A string, or {"en": ..., "ar": ...}. With it, the step reads as label’s sentence alone
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']}", title={"en": "searched orders", "ar": "بحثت في الطلبات"}, 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.
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.
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.
Repeated calls
The loop counts each call in a run by its tool, its input and the result it
returned. When the same call returns the same result a third time, the result
carries a note asking the model to use what it already has, try another way, or
ask the user. The fifth time, the note tells the model not to make that call
again. The eighth time, the run stops and the chat shows a Stopped: callout.A call made again after something changed returns a new result and starts its
own count, so checking work after an edit never draws a note. Polling a job that
keeps answering “still running” does draw the notes, and stops at the eighth
identical answer.Failed calls are counted apart, each one different. The tenth failure in a row
carries a note asking the model to rethink its approach or say what is in its way,
and the twenty-fifth stops the turn. A call that works resets the count.
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.
Next steps
Custom tool guide
A complete tool with a handler, a label and a UI return.
Connectors
OAuth grants, API keys, MCP servers and per-tool approvals.
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Cycls","description":"The deep-stack AI SDK for Python. Runtime, interface, intelligence and state as composable primitives, in one file, deployed with one command.","colors":{"primary":"#686868","light":"#F7F7F7","dark":"#1A1A1A"},"logo":{"light":"https://mintcdn.com/cycls/fWfaZaPSV4PPC_sv/img/logo.svg?fit=max\u0026auto=format\u0026n=fWfaZaPSV4PPC_sv\u0026q=85\u0026s=5c91e026e09d8a1703497ffd3c78f6ee","dark":"https://mintcdn.com/cycls/wIEcbOXtHHM9MyJs/img/logo-white.svg?fit=max\u0026auto=format\u0026n=wIEcbOXtHHM9MyJs\u0026q=85\u0026s=07cd7140b0b852d71a9d3fa69834ec23"},"favicon":{"light":"https://mintcdn.com/cycls/aEKtWvRsb7BZk9hL/img/favicon-light.svg?fit=max\u0026auto=format\u0026n=aEKtWvRsb7BZk9hL\u0026q=85\u0026s=5c99924b61c74e8405efab7e662f3420","dark":"https://mintcdn.com/cycls/aEKtWvRsb7BZk9hL/img/favicon-dark.svg?fit=max\u0026auto=format\u0026n=aEKtWvRsb7BZk9hL\u0026q=85\u0026s=71459cbc40076603514f7a17e26139a2"},"api":{"playground":{"display":"interactive","proxy":true},"examples":{"languages":["bash","python","javascript"]},"url":"full"},"appearance":{"default":"system","strict":false},"navbar":{"links":[{"href":"https://blog.cycls.com","label":"Blog"},{"icon":"github","href":"https://github.com/Cycls/cycls","label":"","type":"github"}],"primary":{"type":"button","label":"Cycls Cloud","href":"https://cloud.cycls.com"}},"footer":{"socials":{"github":"https://github.com/Cycls","x":"https://x.com/cyclsai","linkedin":"https://www.linkedin.com/company/cycls"},"links":[{"header":"Platform","items":[{"label":"Cycls Cloud","href":"https://cloud.cycls.com"},{"label":"Cloud pricing","href":"https://cloud.cycls.com/pricing"},{"label":"SDK on GitHub","href":"https://github.com/Cycls/cycls"},{"label":"PyPI","href":"https://pypi.org/project/cycls"}]},{"header":"Company","items":[{"label":"Cycls","href":"https://cycls.com"},{"label":"Blog","href":"https://blog.cycls.com"},{"label":"Community","href":"https://cycls.com/community"},{"label":"Contact","href":"https://cycls.com/contact"}]}]},"seo":{"metatags":{"canonical":"https://docs.cycls.com","og:image":"https://docs.cycls.com/img/og.png","og:type":"website","og:site_name":"Cycls Documentation","twitter:card":"summary_large_image","twitter:site":"@cyclsai","robots":"index, follow"},"organization":{"name":"Cycls","url":"https://cycls.com","logo":"https://docs.cycls.com/img/logo.svg","sameAs":["https://x.com/cyclsai","https://github.com/Cycls","https://www.linkedin.com/company/cycls/"]},"indexing":"all"},"integrations":{"ga4":{"measurementId":"G-HV0GHWTCKY"},"posthog":{"apiKey":"phc_1jZcYQc0hfsofG8AdCa3w3XZyPyDaAKvK5lZ7rxQ0uB"}},"thumbnails":{"background":"https://mintcdn.com/cycls/Vjgw_hSP7-Pr95Zb/img/og-background.png?fit=max\u0026auto=format\u0026n=Vjgw_hSP7-Pr95Zb\u0026q=85\u0026s=547095cb665569ea11883d4a849e7542"},"styling":{"latex":false},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"cycls","hasAudioNarration":false,"actualSubdomain":"cycls","customDomains":["docs.cycls.com"],"gitSource":{"type":"github","owner":"cycls","repo":"docs","deployBranch":"main","contentDirectory":"","isPrivate":true,"mountPath":"","label":""},"feedback":{"thumbs":false},"entitlements":{},"buildId":"6afb81694be341e0f89b276e","clientVersion":"0.0.4270","searchFilterCounts":[{"language":"default","tag":"Documentation","count":42},{"language":"default","tag":"API reference","count":15},{"language":"default","tag":"Endpoints","count":14},{"language":"default","tag":"Agents","count":10},{"language":"default","tag":"Guides","count":7},{"language":"default","tag":"Volumes","count":7},{"language":"default","tag":"Functions","count":4},{"language":"default","tag":"Reference","count":4},{"language":"default","tag":"Ship it","count":4},{"language":"default","tag":"Interface and users","count":4}]},"assistantConfig":{},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"site-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"starter-pricing","enabled":true,"variant":{"name":"control","enabled":true,"payload":{"type":"string","value":"control"},"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"wildcard-email-auth","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[{"filePath":"custom.css","content":"#topbar-cta-button,#topbar-cta-button:visited{background-color:#000000!important;color:#ffffff!important;border:0.5px solid #ffffff!important;border-radius:0.2rem!important;overflow:hidden}#topbar-cta-button:hover,#topbar-cta-button:focus,#topbar-cta-button:active{background-color:#000000!important;color:#ffffff!important}#topbar-cta-button .bg-primary-dark{background-color:#000000!important;border-radius:inherit!important}"}]}
{"page":{"pagePath":"agents/tools","slug":"/agents/tools","pageMetadata":{"title":"Tools","description":"Enable built-in tools by name, or register your own Python handlers. Both stream into the same UI.","icon":"wrench","keywords":["agent tools","tool calling","bash sandbox","web search tool","custom tool handler"],"href":"/agents/tools"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"Enable built-in tools by name, or register your own Python handlers. Both stream into the same UI.\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,code:`code`,p:`p`,pre:`pre`,span:`span`,tbody:`tbody`,td:`td`,th:`th`,thead:`thead`,tr:`tr`,..._provideComponents(),...props.components},{Card,CardGroup,CodeBlock,Heading,Note,Tab,Table,Tabs}=_components;if(!Card)_missingMdxReference(`Card`,true);if(!CardGroup)_missingMdxReference(`CardGroup`,true);if(!CodeBlock)_missingMdxReference(`CodeBlock`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!Note)_missingMdxReference(`Note`,true);if(!Tab)_missingMdxReference(`Tab`,true);if(!Table)_missingMdxReference(`Table`,true);if(!Tabs)_missingMdxReference(`Tabs`,true);return _jsxs(_Fragment,{children:[_jsx(_components.p,{children:`Tools come from two places. Built-in tools ship with the SDK and are enabled by\nname. Custom tools are JSON schemas you define with async handlers you write.`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`7`,language:`python`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`python`,children:_jsxs(_components.code,{language:`python`,numberOfLines:`7`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`llm `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` (`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` cycls.LLM()`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` .model(`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"anthropic/claude-sonnet-4-6\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`)`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` .allowed_tools([`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Bash\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Editor\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"WebSearch\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Canvas\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`]) `}),_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:`# built in`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` .tools(`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#D4D4D4`},children:`MY_TOOLS`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`) `}),_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:`# your schemas`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` .on(`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"create_ticket\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, create_ticket) `}),_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:`# your handler`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`)`})}),`\n`]})})}),`\n`,_jsx(Heading,{level:`2`,id:`built-in-tools`,children:`Built-in tools`}),`\n`,_jsx(_components.p,{children:`Each name enables one or more tools and brings its own prompt guidance, so\nenabling it is the only switch you need.`}),`\n`,_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`Name`}),_jsx(_components.th,{children:`What the model gets`})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`Bash`})}),_jsxs(_components.td,{children:[_jsx(_components.code,{children:`bash`}),`: run shell commands in a sandbox rooted at the workspace`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`Editor`})}),_jsxs(_components.td,{children:[_jsx(_components.code,{children:`read`}),` and `,_jsx(_components.code,{children:`edit`}),`: view and modify workspace files`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`WebSearch`})}),_jsxs(_components.td,{children:[_jsx(_components.code,{children:`web_search`}),` and `,_jsx(_components.code,{children:`web_fetch`}),`, or the provider’s native search`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`Browser`})}),_jsxs(_components.td,{children:[_jsx(_components.code,{children:`browser`}),`: drive a real Chrome session, only offered when a browser service is configured`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`DataBase`})}),_jsxs(_components.td,{children:[_jsx(_components.code,{children:`database`}),`: the user’s own key-value memory, and the workspace’s app data`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`Canvas`})}),_jsxs(_components.td,{children:[_jsx(_components.code,{children:`canvas`}),`: open a finished file in the side panel viewer`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`Apps`})}),_jsxs(_components.td,{children:[_jsx(_components.code,{children:`build_app`}),`: bundle a source folder into an installable mini app`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`Suggest`})}),_jsxs(_components.td,{children:[_jsx(_components.code,{children:`suggest`}),`: one follow-up chip above the composer`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`Ask`})}),_jsxs(_components.td,{children:[_jsx(_components.code,{children:`ask`}),`: up to three questions on one card, which ends the turn`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`Agent`})}),_jsxs(_components.td,{children:[_jsx(_components.code,{children:`agent`}),`: hand a part of the work to an agent of its own, in the background`]})]})]})]}),`\n`,_jsxs(Tabs,{children:[_jsxs(Tab,{title:`Bash`,id:`bash`,children:[_jsxs(_components.p,{children:[`Runs inside a `,_jsx(_components.code,{children:`bubblewrap`}),` sandbox with the user’s workspace bound at\n`,_jsx(_components.code,{children:`/workspace`}),` and a sanitized environment. The working directory is the\nworkspace, scratch belongs in `,_jsx(_components.code,{children:`.tmp/`}),`, and `,_jsx(_components.code,{children:`/tmp`}),` is per-command and discarded.`]}),_jsx(CodeBlock,{filename:``,numberOfLines:`1`,language:`python`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`python`,children:_jsxs(_components.code,{language:`python`,numberOfLines:`1`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`llm `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` cycls.LLM().allowed_tools([`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Bash\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`]).bash_timeout(`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`600`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`).sandbox(`}),_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#9CDCFE`},children:`network`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:`True`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`)`})]}),`\n`]})})}),_jsxs(_components.p,{children:[`Network access is on by default so `,_jsx(_components.code,{children:`curl`}),`, `,_jsx(_components.code,{children:`pip`}),` and `,_jsx(_components.code,{children:`git`}),` work. A prompt\ninjection can exfiltrate anything the sandbox can read, so turn it off when the\nagent does not need it:`]}),_jsx(CodeBlock,{filename:``,numberOfLines:`1`,language:`python`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`python`,children:_jsxs(_components.code,{language:`python`,numberOfLines:`1`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`llm `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` cycls.LLM().allowed_tools([`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Bash\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`]).sandbox(`}),_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#9CDCFE`},children:`network`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:`False`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`)`})]}),`\n`]})})})]}),_jsxs(Tab,{title:`Editor`,id:`editor`,children:[_jsxs(_components.p,{children:[_jsx(_components.code,{children:`read`}),` renders files. With a `,_jsx(_components.a,{href:`#document-parser`,children:`document parser`}),`, documents (PDF,\nWord, PowerPoint, Excel, OpenDocument, RTF, EPUB) come back as Markdown text.\nWithout one, a PDF up to 3MB goes to the model whole, a larger one is read as page\nimages, and other formats are left to bash. PDF pages come back as images whenever\nthe model asks for them with `,_jsx(_components.code,{children:`pages`}),`, up to 20 a call, for scans, charts or checking\na page. Images go to vision models as they are. `,_jsx(_components.code,{children:`edit`}),` creates and modifies files.\nThe model is told to use these rather than `,_jsx(_components.code,{children:`cat`}),` or `,_jsx(_components.code,{children:`sed`}),`, which keeps writes inside\nthe safety checks and off the output token budget.`]}),_jsxs(_components.p,{children:[`One `,_jsx(_components.code,{children:`read`}),` returns at most 50,000 characters and ends with the line to continue\nfrom, so a large file or attachment arrives in pages instead of filling the\ncontext window. A long parsed document shows its first 20,000 characters, and its\nfull text is kept in the chat’s `,_jsx(_components.code,{children:`.tmp/`}),` folder for the model to read on or search.`]}),_jsx(_components.p,{children:`Paths are workspace relative. Traversal outside the workspace is refused, and so\nare the reserved internal directories.`})]}),_jsxs(Tab,{title:`WebSearch`,id:`websearch`,children:[_jsx(CodeBlock,{filename:``,numberOfLines:`1`,language:`python`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`python`,children:_jsxs(_components.code,{language:`python`,numberOfLines:`1`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`llm `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` cycls.LLM().allowed_tools([`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"WebSearch\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`]).web_search(`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"brave\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`)`})]}),`\n`]})})}),_jsxs(_components.p,{children:[_jsx(_components.code,{children:`brave`}),`, the default, is the portable pair, `,_jsx(_components.code,{children:`web_search`}),` plus `,_jsx(_components.code,{children:`web_fetch`}),`. It works\non every provider and needs `,_jsx(_components.code,{children:`BRAVE_API_KEY`}),`. Without the key, an Anthropic model\ngets `,_jsx(_components.code,{children:`native`}),` search instead, and on other providers `,_jsx(_components.code,{children:`web_search`}),` returns an error\nwhile `,_jsx(_components.code,{children:`web_fetch`}),` still works. Results arrive in the UI as one `,_jsx(_components.code,{children:`sources`}),` row of\ncitation chips at the end of the answer. `,_jsx(_components.code,{children:`native`}),` uses the provider’s server-side\nsearch, which is Anthropic only today.`]}),_jsx(_components.p,{children:`Two optional variables set deployment-wide defaults, which the model can override\nper query:`}),_jsx(CodeBlock,{filename:``,numberOfLines:`2`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`2`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`BRAVE_COUNTRY`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`sa`}),_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:` # a two-letter country code that biases ranking`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`BRAVE_SEARCH_LANG`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`ar`}),_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:` # a two-letter language code that restricts results`})]}),`\n`]})})})]}),_jsxs(Tab,{title:`Browser`,id:`browser`,children:[_jsxs(_components.p,{children:[`A real Chrome session driven step by step: `,_jsx(_components.code,{children:`open`}),`, `,_jsx(_components.code,{children:`read`}),`, `,_jsx(_components.code,{children:`click`}),`, `,_jsx(_components.code,{children:`type`}),`,\n`,_jsx(_components.code,{children:`press`}),`, `,_jsx(_components.code,{children:`back`}),`, `,_jsx(_components.code,{children:`evaluate`}),`, `,_jsx(_components.code,{children:`screenshot`}),`, `,_jsx(_components.code,{children:`download`}),`. The page persists between\ncalls in a turn, so logins and multi-step forms work.`]}),_jsxs(_components.p,{children:[_jsx(_components.code,{children:`open`}),` also takes a workspace `,_jsx(_components.code,{children:`.html`}),`, `,_jsx(_components.code,{children:`.htm`}),` or `,_jsx(_components.code,{children:`.svg`}),` file by its path, or as\n`,_jsx(_components.code,{children:`/workspace/...`}),` or `,_jsx(_components.code,{children:`file://...`}),`, so the agent can look at a page it wrote. The\nfile’s text is written into a blank tab, with no site’s origin or cookies, and the\npage is read once it loads or after 15 seconds. The browser gets nothing but that\ntext, so anything the page loads by a relative path, such as an image, must be\ninlined. `,_jsx(_components.code,{children:`localhost`}),`, `,_jsx(_components.code,{children:`127.0.0.1`}),` and `,_jsx(_components.code,{children:`0.0.0.0`}),` addresses are refused, because the\nbrowser runs on another machine. So are files under `,_jsx(_components.code,{children:`apps/\u003cslug>/`}),`: an app reaches\nits data only beside the chat, so the browser would show it empty.`]}),_jsx(_components.p,{children:`The browser itself runs in a shared service, not in your image. Configure it with\nenvironment variables, and the tool is not offered when they are unset:`}),_jsx(CodeBlock,{filename:``,numberOfLines:`2`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`2`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`BROWSER_URL`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`https://browser.example.com`}),_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:` # your browser service`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`BROWSER_SECRET`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`your_service_secret`}),_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:` # sent as a Bearer token`})]}),`\n`]})})}),_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:_jsx(_components.code,{children:`BROWSER_PROVIDER`})}),_jsx(_components.th,{children:_jsx(_components.code,{children:`BROWSER_URL`})}),_jsx(_components.th,{children:_jsx(_components.code,{children:`BROWSER_SECRET`})})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsxs(_components.td,{children:[_jsx(_components.code,{children:`steel`}),`, the default`]}),_jsx(_components.td,{children:`a Steel Browser service. Each chat gets its own session`}),_jsx(_components.td,{children:`required`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`cdp`})}),_jsxs(_components.td,{children:[`a Chrome DevTools endpoint, such as `,_jsx(_components.code,{children:`http://host:9222`}),`. Every chat shares that one browser`]}),_jsx(_components.td,{children:`not needed`})]})]})]})]}),_jsxs(Tab,{title:`DataBase`,id:`database`,children:[_jsxs(_components.p,{children:[`A JSON key-value store with `,_jsx(_components.code,{children:`get`}),`, `,_jsx(_components.code,{children:`put`}),`, `,_jsx(_components.code,{children:`delete`}),` and `,_jsx(_components.code,{children:`scan`}),`. The key decides\nwhose data it is.`]}),_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`Key`}),_jsx(_components.th,{children:`Holds`}),_jsx(_components.th,{children:`Shared with`})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsxs(_components.td,{children:[`anything outside `,_jsx(_components.code,{children:`apps/`})]}),_jsx(_components.td,{children:`the agent’s memory of this user in this workspace, such as preferences and task progress`}),_jsx(_components.td,{children:`nobody: no teammate and no app reads it`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`apps/\u003cslug>/\u003ckey>`})}),_jsxs(_components.td,{children:[`an app’s data, the rows the app reads and writes with `,_jsx(_components.code,{children:`cycls.get`}),` and `,_jsx(_components.code,{children:`cycls.set`})]}),_jsx(_components.td,{children:`the whole workspace`})]})]})]}),_jsx(_components.p,{children:`Anything a teammate must read belongs in a workspace file or an app’s data, not in\nmemory.`}),_jsxs(_components.p,{children:[_jsx(_components.code,{children:`database`}),` is the agent’s only way into app data: bash sees an empty `,_jsx(_components.code,{children:`.apps`}),`\nfolder, the file tools refuse it, and the `,_jsxs(_components.a,{href:`/agents/files#the-http-api`,children:[_jsx(_components.code,{children:`/files`}),` API`]}),`\nanswers 403. A `,_jsx(_components.code,{children:`scan`}),` with the prefix `,_jsx(_components.code,{children:`apps/\u003cslug>/`}),` lists an app’s keys. In a team\nworkspace, an app whose `,_jsx(_components.code,{children:`app.json`}),` sets `,_jsx(_components.code,{children:`\"write\": \"admin\"`}),` takes writes only from\nthe workspace’s owners and admins. The app’s `,_jsx(_components.code,{children:`data/`}),` folder is something else: its\nfiles, which bash and the file tools reach like any other.`]}),_jsxs(_components.p,{children:[`The agent changes an app’s data only from what it read. A `,_jsx(_components.code,{children:`put`}),` or `,_jsx(_components.code,{children:`delete`}),` on an\napp’s key is refused when the agent never read that key in the conversation, or\nwhen someone changed it in the app since, and the agent is told to read it again.`]}),_jsxs(_components.p,{children:[`Users manage their memory in the web client under Settings, General, Memory. Each\nentry in the active workspace shows as a plain-text note they can edit or delete.\nTurning Memory off removes the `,_jsx(_components.code,{children:`database`}),` tool from their chats in every\nworkspace, along with the agent’s way into app data. What was saved stays.`]})]}),_jsxs(Tab,{title:`Canvas and Apps`,id:`canvas-and-apps`,children:[_jsxs(_components.p,{children:[_jsx(_components.code,{children:`Canvas`}),` opens one finished deliverable in the side panel. It renders markdown,\nHTML, PDF, images, audio, video, code, CSV, spreadsheets and 3D models. Office\nformats render read-only through the office service, and anything else falls back\nto a download card.`]}),_jsxs(_components.p,{children:[`The user sees every canvas call in the chat, and the canvas shows the model\nnothing. So a reply opens one deliverable, and other files go in it as links. The\nagent checks its own work with `,_jsx(_components.code,{children:`read`}),`, which returns a picture or a PDF’s pages to\nit, and keeps pictures made for that in `,_jsx(_components.code,{children:`.tmp/`}),`, which the canvas refuses. Pictures\nmeant for the user go in the reply as images.`]}),_jsxs(_components.p,{children:[_jsx(_components.code,{children:`Apps`}),` lets the agent bundle a source folder into a single self-contained HTML\nfile installed in the Apps tab. Apps run under a strict CSP with no external\nfetch, and reach the workspace through a small bridge the host page runs for them:`]}),_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`In the app`}),_jsx(_components.th,{children:`What it does`})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsxs(_components.td,{children:[_jsx(_components.code,{children:`cycls.read(path)`}),`, `,_jsx(_components.code,{children:`cycls.write(path, text)`})]}),_jsxs(_components.td,{children:[`text files in the app’s own folder. Writes go under its `,_jsx(_components.code,{children:`data/`}),` folder only`]})]}),_jsxs(_components.tr,{children:[_jsxs(_components.td,{children:[_jsx(_components.code,{children:`cycls.get(key)`}),`, `,_jsx(_components.code,{children:`cycls.set(key, value)`})]}),_jsxs(_components.td,{children:[`the app’s key-value data, shared by the workspace. `,_jsx(_components.code,{children:`set`}),` writes at once`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`cycls.save(name, text)`})}),_jsx(_components.td,{children:`asks the user where to save a file, anywhere in the workspace`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`cycls.onChange(fn)`})}),_jsxs(_components.td,{children:[`runs `,_jsx(_components.code,{children:`fn`}),` when the app’s data or files changed under it, by the agent, a teammate or another tab. `,_jsx(_components.code,{children:`cycls.refresh()`}),` checks at once`]})]}),_jsxs(_components.tr,{children:[_jsxs(_components.td,{children:[_jsx(_components.code,{children:`cycls.ctx.user`}),`, `,_jsx(_components.code,{children:`cycls.people()`})]}),_jsxs(_components.td,{children:[`who is viewing, as `,_jsx(_components.code,{children:`{id, name, role}`}),`, and the workspace’s members with their pictures. Store ids, never names`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`cycls.who(key)`})}),_jsx(_components.td,{children:`who last changed a shared key, and when`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`cycls.onTheme(fn)`})}),_jsxs(_components.td,{children:[`runs `,_jsx(_components.code,{children:`fn`}),` when the chat switches between light and dark. The app’s `,_jsx(_components.code,{children:`\u003chtml>`}),` gets the `,_jsx(_components.code,{children:`dark`}),` class by itself`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`cycls.connector(name).json(path, init)`})}),_jsxs(_components.td,{children:[`calls a connected `,_jsx(_components.a,{href:`/agents/connectors#calling-a-rest-api`,children:`connector’s API`}),` with the credential attached server-side, so a dashboard stays live without holding a key`]})]})]})]}),_jsxs(_components.p,{children:[`The agent reads and writes the same key-value data with `,_jsx(_components.code,{children:`database`}),`. In a team\nworkspace, `,_jsx(_components.code,{children:`\"write\": \"admin\"`}),` in the app’s `,_jsx(_components.code,{children:`app.json`}),` limits writing it to the\nworkspace’s owners and admins.`]}),_jsxs(_components.p,{children:[`An open app without an `,_jsx(_components.code,{children:`onChange`}),` listener is reloaded when the agent changes its\ndata, never for a teammate’s change. Fonts, images and sounds in the app’s `,_jsx(_components.code,{children:`src/`}),`\nthat its code refers to are written into the app, since it loads nothing from the\nnetwork.`]})]}),_jsxs(Tab,{title:`Suggest and Ask`,id:`suggest-and-ask`,children:[_jsxs(_components.p,{children:[_jsx(_components.code,{children:`Suggest`}),` shows one follow-up chip above the composer, written in the user’s\nvoice. `,_jsx(_components.code,{children:`Ask`}),` puts up to three questions on one card and ends the turn, with the\nanswers arriving as the next user message. The options are shortcuts, not a gate:\nevery question with options ends with a line where the user writes their own\nanswer, so the model never needs an “Other” option.`]}),_jsxs(_components.p,{children:[`Users can switch both off in Settings, and `,_jsx(_components.code,{children:`context.disabled_tools`}),` reflects that\nfor the turn.`]})]}),_jsxs(Tab,{title:`Agent`,id:`agent`,children:[_jsxs(_components.p,{children:[_jsx(_components.code,{children:`agent`}),` starts an agent of the agent’s own with a short label and a brief, and\nreturns at once. The new agent works in the background, in the same workspace with\nthe same tools, while the chat carries on. When it finishes, its report reaches the\nagent that started it as a message, and that agent tells the user what matters.`]}),_jsx(CodeBlock,{filename:``,numberOfLines:`1`,language:`python`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`python`,children:_jsxs(_components.code,{language:`python`,numberOfLines:`1`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`llm `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` cycls.LLM().allowed_tools([`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Bash\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Editor\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"WebSearch\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Agent\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`])`})]}),`\n`]})})}),_jsx(_components.p,{children:`Up to four work at once in a chat. They can’t start agents of their own or ask the\nuser anything, and the run’s 45 minutes cover all of them. The chat shows them in\none card, a row each, and a row opens that agent’s work.`}),_jsxs(_components.p,{children:[`Agents cost several times a normal turn. To keep them to some users, such as paid\nplans, add the tool for that request: `,_jsx(_components.code,{children:`llm.allowed_tools([*TOOLS, \"Agent\"])`}),` returns\na new builder, so the others keep their list.`]})]})]}),`\n`,_jsx(Note,{children:_jsxs(_components.p,{children:[`A user can switch a tool off in Settings. `,_jsx(_components.code,{children:`LLM.run()`}),` drops those tools for the\nturn. A switch can never enable a tool the operator did not allow.`]})}),`\n`,_jsx(Heading,{level:`2`,id:`document-parser`,children:`Document parser`}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.code,{children:`read`}),` can send documents to a parser you deploy as a `,_jsx(_components.a,{href:`/build/functions`,children:`function`}),`,\nand give the model the Markdown it returns. The parser receives the file’s bytes and\nname, and returns three keys.`]}),`\n`,_jsx(CodeBlock,{filename:`doc_parser.py`,numberOfLines:`16`,language:`python`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`python`,children:_jsxs(_components.code,{language:`python`,numberOfLines:`16`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`import`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` cycls`})]}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:`@cycls.function`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`(`}),_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#9CDCFE`},children:`image`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`cycls.Image().pip(`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"pypdf\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`))`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`def`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:` doc_parser`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`(`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`data`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#4EC9B0`},children:`bytes`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`name`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#4EC9B0`},children:`str`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`mode`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#4EC9B0`},children:`str`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:` =`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"markdown\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`):`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` import`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` io`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` from`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` pypdf `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`import`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` PdfReader`})]}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` if`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` not`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` name.lower().endswith(`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\".pdf\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`):`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` return`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` {`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"content\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"warnings\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: [], `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"page_count\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`0`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` pages `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` PdfReader(io.BytesIO(data)).pages`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` return`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` {`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"content\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:`\\\\n\\\\n`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`.join(page.extract_text() `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`or`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"\"`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` for`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` page `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`in`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` pages),`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"warnings\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: [],`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"page_count\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#DCDCAA`},children:`len`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`(pages),`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` }`})}),`\n`]})})}),`\n`,_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`Key`}),_jsx(_components.th,{children:`Meaning`})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`content`})}),_jsxs(_components.td,{children:[`the document as Markdown. Empty means no text, such as a scan, and `,_jsx(_components.code,{children:`read`}),` goes on without the parser`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`warnings`})}),_jsx(_components.td,{children:`lines shown to the model above the text`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`page_count`})}),_jsxs(_components.td,{children:[`a PDF’s page count, shown so the model can ask to see a page with `,_jsx(_components.code,{children:`pages`})]})]})]})]}),`\n`,_jsx(_components.p,{children:`Deploy it, then name it in the agent container’s environment:`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`2`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`2`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`cycls`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` deploy`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` doc_parser.py`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:`# Deployed: https://doc-parser.cycls.ai`})}),`\n`]})})}),`\n`,_jsx(CodeBlock,{filename:`.providers.env`,numberOfLines:`2`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`2`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`CYCLS_PARSER`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`doc-parser`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`CYCLS_API_KEY`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`...`}),_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:` # the key that deployed doc-parser`})]}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`The agent calls the parser with `,_jsx(_components.code,{children:`cycls.remote`}),`, and a deployment answers only the\nkey that deployed it, so the agent’s container needs that key. `,_jsx(_components.code,{children:`read`}),` sends PDF,\nWord, PowerPoint, Excel, OpenDocument, RTF and EPUB files up to 50MB, and waits up\nto 120 seconds. A read with `,_jsx(_components.code,{children:`pages`}),` skips the parser. A call that fails falls back\nto reading without it and writes a `,_jsx(_components.code,{children:`level=parser`}),` log record with the error.`]}),`\n`,_jsxs(_components.p,{children:[`The default, `,_jsx(_components.code,{children:`cycls-parser`}),`, is the parser Cycls runs for its own agents and\nanswers only Cycls’s key. Set `,_jsx(_components.code,{children:`CYCLS_PARSER`}),` to your deployment, or to an empty\nstring to skip the call.`]}),`\n`,_jsx(Heading,{level:`2`,id:`custom-tools`,children:`Custom tools`}),`\n`,_jsxs(_components.p,{children:[`A tool schema is a plain dict. A handler is an async function. The return value\ngoes to the UI stream and to the model as the `,_jsx(_components.code,{children:`tool_result`}),`, so one return covers\nboth destinations.`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`27`,language:`python`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`python`,children:_jsxs(_components.code,{language:`python`,numberOfLines:`27`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#D4D4D4`},children:`TOOLS`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:` =`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` [`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` {`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"name\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"create_ticket\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"description\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Open a support ticket for the current user.\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"inputSchema\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: {`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"type\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"object\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"properties\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: {`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"title\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: {`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"type\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"string\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`},`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"priority\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: {`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"type\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"string\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"enum\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: [`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"low\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"high\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`]},`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` },`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"required\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: [`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"title\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`],`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` },`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` }`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`]`})}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`async`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` def`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:` create_ticket`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`(`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`args`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`):`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` ticket `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` await`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` support.create(args[`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"title\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`], args.get(`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"priority\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"low\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`))`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` return`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` f`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Created ticket `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`{`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`ticket.id`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`}`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"`})]}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`llm `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` (`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` cycls.LLM()`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` .model(`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"anthropic/claude-sonnet-4-6\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`)`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` .tools(`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#D4D4D4`},children:`TOOLS`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`)`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` .on(`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"create_ticket\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, create_ticket, `}),_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#9CDCFE`},children:`label`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`lambda`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:` i`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: i[`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"title\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`])`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`)`})}),`\n`]})})}),`\n`,_jsx(Heading,{level:`3`,id:`handler-signature`,children:`Handler signature`}),`\n`,_jsx(_components.p,{children:`A handler takes the tool input, and optionally a second argument with request\ncontext.`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`5`,language:`python`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`python`,children:_jsxs(_components.code,{language:`python`,numberOfLines:`5`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`async`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` def`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:` create_ticket`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`(`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`args`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`ctx`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`):`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` ws `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` ctx.workspace `}),_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:`# the caller's workspace`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` user `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` ctx.user `}),_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:`# the authenticated user`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` grant `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` await`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` ctx.secret(`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"linear\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`) `}),_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:`# {\"key\": ...}, or None if not connected`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` return`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` f`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Created for `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`{`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`user.id`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`}`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"`})]}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.code,{children:`ctx.secret(name)`}),` reads what was stored for the `,_jsx(_components.a,{href:`/agents/connectors`,children:`connector`}),`\n`,_jsx(_components.code,{children:`name`}),`, the user’s own grant before the workspace’s. An API key comes back as\n`,_jsx(_components.code,{children:`{\"key\": ...}`}),`, and an OAuth grant as stored, with `,_jsx(_components.code,{children:`access_token`}),` and `,_jsx(_components.code,{children:`expires_at`}),`.\n`,_jsx(_components.code,{children:`ctx.secret`}),` does not refresh an expired token.`]}),`\n`,_jsxs(_components.p,{children:[`A handler that raises sends `,_jsx(_components.code,{children:`Error:`}),` and the exception to the model as the result,\nand the turn goes on.`]}),`\n`,_jsx(Heading,{level:`3`,id:`presentation`,children:`Presentation`}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.code,{children:`.on()`}),` controls how the call appears in the UI.`]}),`\n`,_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`Argument`}),_jsx(_components.th,{children:`Effect`})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`label`})}),_jsxs(_components.td,{children:[`a function from input to a string, the step’s line in the chat. It may return `,_jsx(_components.code,{children:`{\"en\": ..., \"ar\": ...}`}),` so each language gets its own words. Defaults to the first string value in the input`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`title`})}),_jsxs(_components.td,{children:[`what the tool did, for the collapsed line of steps, such as “checked market data”. A string, or `,_jsx(_components.code,{children:`{\"en\": ..., \"ar\": ...}`}),`. With it, the step reads as `,_jsx(_components.code,{children:`label`}),`’s sentence alone`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`icon`})}),_jsx(_components.td,{children:`an image URL shown where a connector logo goes`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`details=True`})}),_jsx(_components.td,{children:`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`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`picture`})}),_jsxs(_components.td,{children:[`a function from input to the shape of a picture the tool makes, such as `,_jsx(_components.code,{children:`\"16:9\"`}),`. While the call runs, the chat holds a frame of that shape, and the picture the tool opens with `,_jsx(_components.code,{children:`open_canvas`}),` takes its place`]})]})]})]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`8`,language:`python`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`python`,children:_jsxs(_components.code,{language:`python`,numberOfLines:`8`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`llm `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` cycls.LLM().on(`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"search_orders\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` search_orders,`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#9CDCFE`},children:` label`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`lambda`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:` i`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`f`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"orders for `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`{`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`i[`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`'email'`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`]`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`}`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#9CDCFE`},children:` title`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`{`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"en\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"searched orders\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"ar\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"بحثت في الطلبات\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`},`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#9CDCFE`},children:` icon`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"https://example.com/logo.png\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#9CDCFE`},children:` details`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:`True`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`)`})}),`\n`]})})}),`\n`,_jsx(Heading,{level:`3`,id:`returning-ui-components`,children:`Returning UI components`}),`\n`,_jsx(_components.p,{children:`A handler can return a component dict instead of text. It renders in the\nconversation, and the model reads it as JSON.`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`3`,language:`python`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`python`,children:_jsxs(_components.code,{language:`python`,numberOfLines:`3`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`async`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` def`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:` render_chart`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`(`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`args`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`):`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` path `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` await`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` make_chart(args[`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"series\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`])`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` return`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` {`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"type\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"image\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"src\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: path, `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"caption\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Revenue by month\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}`})]}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`To give the model and the chat different things, return two channels. `,_jsx(_components.code,{children:`_model`}),`\nbecomes the tool result, and `,_jsx(_components.code,{children:`_ui`}),` is one event or a list of events for the chat.`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`6`,language:`python`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`python`,children:_jsxs(_components.code,{language:`python`,numberOfLines:`6`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`async`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` def`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:` search_docs`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`(`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`args`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`):`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` hits `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` await`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` index.search(args[`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"query\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`]) `}),_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:`# [{\"title\", \"url\", \"snippet\"}]`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` return`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` {`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"_model\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: json.dumps(hits),`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"_ui\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: {`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"type\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"sources\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"sources\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: hits},`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` }`})}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`A tool’s `,_jsx(_components.code,{children:`sources`}),` and the files it opens are kept with the chat, so they come\nback after a reload. A link in the answer to a source’s `,_jsx(_components.code,{children:`url`}),` becomes its chip,\nand a source can say more than its title:`]}),`\n`,_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`Key`}),_jsx(_components.th,{children:`Shown as`})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`label`})}),_jsx(_components.td,{children:`the chip’s words, in place of the site’s name`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`quote`})}),_jsx(_components.td,{children:`the words cited, on the card`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`status`})}),_jsx(_components.td,{children:`a short state on the card, such as “In force”`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`note`})}),_jsx(_components.td,{children:`one line of context under the quote`})]})]})]}),`\n`,_jsxs(_components.p,{children:[`A file a tool opens with an `,_jsx(_components.code,{children:`open_canvas`}),` event in `,_jsx(_components.code,{children:`_ui`}),` also stands in the\nconversation as its card, and a picture as itself.`]}),`\n`,_jsxs(_components.p,{children:[`A handler can also return a `,_jsx(_components.a,{href:`/agents/streaming#client-actions`,children:`client action`}),`\nwith an `,_jsx(_components.code,{children:`ack`}),`. The client gets the action, and the model reads `,_jsx(_components.code,{children:`ack`}),` in its place.\nA `,_jsx(_components.code,{children:`confirm`}),` or `,_jsx(_components.code,{children:`connect`}),` action ends the turn, because the user has to answer\nfirst.`]}),`\n`,_jsx(Heading,{level:`2`,id:`repeated-calls`,children:`Repeated calls`}),`\n`,_jsxs(_components.p,{children:[`The loop counts each call in a run by its tool, its input and the result it\nreturned. When the same call returns the same result a third time, the result\ncarries a note asking the model to use what it already has, try another way, or\nask the user. The fifth time, the note tells the model not to make that call\nagain. The eighth time, the run stops and the chat shows a `,_jsx(_components.code,{children:`Stopped:`}),` callout.`]}),`\n`,_jsx(_components.p,{children:`A call made again after something changed returns a new result and starts its\nown count, so checking work after an edit never draws a note. Polling a job that\nkeeps answering “still running” does draw the notes, and stops at the eighth\nidentical answer.`}),`\n`,_jsx(_components.p,{children:`Failed calls are counted apart, each one different. The tenth failure in a row\ncarries a note asking the model to rethink its approach or say what is in its way,\nand the twenty-fifth stops the turn. A call that works resets the count.`}),`\n`,_jsx(Heading,{level:`2`,id:`reserved-names`,children:`Reserved names`}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.code,{children:`skill`}),` and `,_jsx(_components.code,{children:`find_tools`}),` are reserved by the loop. `,_jsx(_components.code,{children:`skill`}),` loads a\n`,_jsx(_components.a,{href:`/agents/knowledge#skills`,children:`skill`}),` on demand and publishes one with\n`,_jsx(_components.code,{children:`action: \"publish\"`}),`. It is offered every turn, even before any skill exists, unless\nyou set `,_jsx(_components.code,{children:`.skills(None)`}),`. `,_jsx(_components.code,{children:`find_tools`}),` loads a connector’s tools when the model\nneeds them. A built-in tool’s name, such as `,_jsx(_components.code,{children:`bash`}),`, `,_jsx(_components.code,{children:`read`}),` or `,_jsx(_components.code,{children:`database`}),`, is taken\ntoo: a custom tool with that name runs the built-in.`]}),`\n`,_jsx(Heading,{level:`2`,id:`next-steps`,children:`Next steps`}),`\n`,_jsxs(CardGroup,{cols:2,children:[_jsx(Card,{title:`Custom tool guide`,icon:`code`,href:`/guides/custom-tool`,children:_jsx(_components.p,{children:`A complete tool with a handler, a label and a UI return.`})}),_jsx(Card,{title:`Connectors`,icon:`plug`,href:`/agents/connectors`,children:_jsx(_components.p,{children:`OAuth grants, API keys, MCP servers and per-tool approvals.`})})]})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Tools","description":"Enable built-in tools by name, or register your own Python handlers. Both stream into the same UI.","icon":"wrench","keywords":["agent tools","tool calling","bash sandbox","web search tool","custom tool handler"],"href":"/agents/tools"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"Built-in tools","slug":"built-in-tools","depth":2,"children":[]},{"title":"Document parser","slug":"document-parser","depth":2,"children":[]},{"title":"Custom tools","slug":"custom-tools","depth":2,"children":[{"title":"Handler signature","slug":"handler-signature","depth":3,"children":[]},{"title":"Presentation","slug":"presentation","depth":3,"children":[]},{"title":"Returning UI components","slug":"returning-ui-components","depth":3,"children":[]}]},{"title":"Repeated calls","slug":"repeated-calls","depth":2,"children":[]},{"title":"Reserved names","slug":"reserved-names","depth":2,"children":[]},{"title":"Next steps","slug":"next-steps","depth":2,"children":[]}],"codeExamples":{}},"jsLinks":[],"subdomain":"cycls","siteName":"Cycls","title":"Tools - Cycls","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-11-16T22:19:28.500Z","originalFileLocation":"agents/tools.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Enable built-in tools by name, or register your own Python handlers. Both stream into the same UI.\">\u003cmeta data-mint-head name=\"application-name\" content=\"Cycls\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003cmeta data-mint-head name=\"robots\" content=\"index, follow\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/cycls/RZSKjbSx5qJq7Dtr/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/cycls/RZSKjbSx5qJq7Dtr/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/cycls/RZSKjbSx5qJq7Dtr/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/cycls/RZSKjbSx5qJq7Dtr/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/cycls/RZSKjbSx5qJq7Dtr/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/cycls/RZSKjbSx5qJq7Dtr/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/cycls/RZSKjbSx5qJq7Dtr/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/cycls/RZSKjbSx5qJq7Dtr/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/cycls/RZSKjbSx5qJq7Dtr/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Tools - Cycls\">\u003cmeta data-mint-head property=\"og:description\" content=\"Enable built-in tools by name, or register your own Python handlers. Both stream into the same UI.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Cycls Documentation\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.cycls.com/agents/tools\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://docs.cycls.com/img/og.png\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Tools - Cycls\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Enable built-in tools by name, or register your own Python handlers. Both stream into the same UI.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://docs.cycls.com/img/og.png\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/cycls/RZSKjbSx5qJq7Dtr/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Cycls\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#686868\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.cycls.com/agents/tools\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/agents/tools.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://cycls.com/#organization\",\"name\":\"Cycls\",\"url\":\"https://cycls.com\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://docs.cycls.com/img/logo.svg\"},\"sameAs\":[\"https://x.com/cyclsai\",\"https://github.com/Cycls\",\"https://www.linkedin.com/company/cycls/\"]},{\"@type\":\"WebSite\",\"@id\":\"https://docs.cycls.com#website\",\"name\":\"Cycls\",\"url\":\"https://docs.cycls.com\",\"publisher\":{\"@id\":\"https://cycls.com/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.cycls.com/agents/tools#webpage\",\"url\":\"https://docs.cycls.com/agents/tools\",\"name\":\"Tools\",\"description\":\"Enable built-in tools by name, or register your own Python handlers. Both stream into the same UI.\",\"dateModified\":\"2026-11-16T22:19:28.500Z\",\"isPartOf\":{\"@id\":\"https://docs.cycls.com#website\"},\"breadcrumb\":{\"@id\":\"https://docs.cycls.com/agents/tools#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.cycls.com/agents/tools#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Agents\",\"item\":\"https://docs.cycls.com/agents/overview\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Tools\",\"item\":\"https://docs.cycls.com/agents/tools\"}]},{\"@type\":[\"Article\",\"TechArticle\"],\"@id\":\"https://docs.cycls.com/agents/tools#article\",\"headline\":\"Tools\",\"name\":\"Tools\",\"description\":\"Enable built-in tools by name, or register your own Python handlers. Both stream into the same UI.\",\"url\":\"https://docs.cycls.com/agents/tools\",\"mainEntityOfPage\":{\"@id\":\"https://docs.cycls.com/agents/tools#webpage\"},\"image\":\"https://docs.cycls.com/img/og.png\",\"dateModified\":\"2026-11-16T22:19:28.500Z\",\"keywords\":\"agent tools, tool calling, bash sandbox, web search tool, custom tool handler\",\"publisher\":{\"@id\":\"https://cycls.com/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.cycls.com#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Cycls\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"Cycls\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/agents/tools.md","siteName":"Cycls","nav":{"global":null,"tabs":[{"tab":"Documentation","groups":[{"group":"Get started","pages":[{"title":"Introduction","icon":"sparkles","mode":"wide","href":"/get-started/introduction"},{"title":"Quickstart","icon":"play","mode":"wide","href":"/get-started/quickstart"},{"title":"Core concepts","icon":"diagram-project","href":"/get-started/concepts"}]},{"group":"Functions","pages":[{"title":"Functions","icon":"box","href":"/build/functions"},{"title":"Images","icon":"layer-group","href":"/build/images"},{"title":"Volumes","icon":"hard-drive","href":"/build/volumes"},{"title":"Cron","icon":"clock","href":"/build/cron"}]},{"group":"Apps","pages":[{"title":"Apps","icon":"server","href":"/build/apps"}]},{"group":"Agents","pages":[{"title":"Agents","icon":"comments","href":"/agents/overview"},{"title":"Models","description":"One builder for every provider: Anthropic natively, and any OpenAI-compatible endpoint through a base URL.","icon":"brain","href":"/agents/models"},{"title":"Tools","icon":"wrench","href":"/agents/tools"},{"title":"Streaming components","description":"Yield strings for markdown or dicts for rich components: thinking bubbles, tables, code, callouts, images and client actions.","icon":"bolt","href":"/agents/streaming"},{"title":"Context","icon":"user","href":"/agents/context"},{"title":"Instructions and skills","icon":"book","href":"/agents/knowledge"},{"title":"Files and the canvas","icon":"folder-open","href":"/agents/files"},{"title":"Connectors and MCP","icon":"plug","href":"/agents/connectors"},{"title":"Sandbox and trust model","icon":"shield-halved","href":"/agents/sandbox"},{"title":"Custom loops","icon":"code-branch","href":"/agents/custom-loop"}]},{"group":"Interface and users","pages":[{"title":"Interface","icon":"window","href":"/web/interface"},{"title":"Authentication","icon":"lock","href":"/web/auth"},{"title":"Workspaces","icon":"users","href":"/web/workspaces"},{"title":"Plans and quotas","icon":"credit-card","href":"/web/monetization"}]},{"group":"Ship it","pages":[{"title":"Local and remote builds","icon":"docker","href":"/ship/builds"},{"title":"Deploy","icon":"rocket","href":"/ship/deploy"},{"title":"Logs, cost and SQL","icon":"chart-line","href":"/ship/observability"},{"title":"CLI reference","icon":"terminal","href":"/ship/cli"}]},{"group":"Guides","pages":[{"title":"Build your first agent","icon":"graduation-cap","href":"/guides/first-agent"},{"title":"Add a custom tool","icon":"wrench","href":"/guides/custom-tool"},{"title":"Serve a FastAPI app","icon":"server","href":"/guides/fastapi-app"},{"title":"Run batch jobs","icon":"layer-group","href":"/guides/batch-jobs"},{"title":"Build a data warehouse on a volume","icon":"database","href":"/guides/duckdb-warehouse"},{"title":"Schedule a nightly report","icon":"clock","href":"/guides/scheduled-reports"},{"title":"Open and self-hosted models","icon":"server","href":"/guides/self-hosted-models"}]},{"group":"Reference","pages":[{"title":"Python API","icon":"code","href":"/reference/python"},{"title":"Agent HTTP API","icon":"server","href":"/reference/agent-api"},{"title":"Environment variables","icon":"key","href":"/reference/environment"},{"title":"Limits","icon":"gauge","href":"/reference/limits"}]},{"group":"Resources","pages":[{"title":"Examples","icon":"code","href":"/resources/examples"},{"title":"FAQ","icon":"circle-question","href":"/resources/faq"},{"title":"Contributing","icon":"code-pull-request","href":"/resources/contributing"}]},{"group":"For LLMs","pages":[{"title":"llms.txt","icon":"robot","mode":"wide","url":"https://docs.cycls.com/llms.txt","href":"/llms"},{"title":"llms-full.txt","icon":"robot","mode":"wide","url":"https://docs.cycls.com/llms-full.txt","href":"/llms-full"}]}]},{"tab":"API reference","pages":[{"title":"API reference","href":"/api-reference/introduction"}]},{"tab":"Changelog","pages":[{"title":"Changelog","href":"/changelog"}]}]},"basePath":"","title":"Tools - Cycls","deploymentId":"dpl_DyXGnKeCjZyA3sUdfMJ7FjkdBefg","buildId":"dpl_DyXGnKeCjZyA3sUdfMJ7FjkdBefg","dynamics":[],"chunks":[]}