How to Configure Tools

🔧 Tools · 📋 Prompt

The tools provider gives the agent callable tools — functions the LLM can invoke during the conversation loop. Each tool source contributes a set of related tools. You control which sources are active and how they behave.

List and Enable Tool Sources

za agents capabilities tool-sets list
za agents capabilities tool-sets configure <source-name>

Configure Provider Settings

za agents capabilities tool-sets settings

Who may call each tool, the model directly or Python in the REPL, is set here with sandbox_only_sources, sandbox_only_tools, direct_only_sources and direct_only_tools; see Who May Call a Tool.

Tool Search

Tools can load on demand: the model first sees a group of tools only by its name and description (a tools source or an MCP server) and loads the tools it needs by searching. The agent's configuration says which groups load on demand:

Setting	Type	Default	Applies to
defer_tools in tools_provider_configuration	bool	false	Every built-in tools source
defer_tools in a source's block, e.g. web_tools_source_configuration	bool	null	That source; unset follows tools_provider_configuration
defer_tools in mcp_tools_provider_configuration	bool	false	Every MCP server the agent uses
defer_tools in a mount in mounts	bool	null	That server; unset follows mcp_tools_provider_configuration

The most specific value decides: a source's or mount's own, else its provider's. A setting rule's loading decides over all of them, the agent's over the tenant's unless the tenant locked it, see How rules decide. In the agent editor, Tools → Settings and MCP Tools → Settings have the providers' Defer tools switch, and each built-in source and mounted server has a Loading select (Default, Up front, On demand) on its row.

"tools_provider_configuration": { "defer_tools": true },
"index_tools_source_configuration": { "enabled": true, "defer_tools": false },
"mcp_tools_provider_configuration": { "defer_tools": true, "mounts": [{ "name": "ms365" }, { "name": "crm", "defer_tools": false }] }

How the model finds on-demand tools is the agent's tool search method:

Method	How it works	Models
server	The vendor lists the tools and searches them	OpenAI and Azure OpenAI responses models, Anthropic and Azure Anthropic chat models
client	Our search, in the vendor's tool search protocol	Same as server
emulated	A search_tools tool any model can call; the tools it finds are added to the next request	Any chat or responses model

Each model call uses the first of the agent's methods that its model lists in tool_search_methods. When none fits, every on-demand tool goes up front: that costs tokens but hides nothing. Platform Admin warns about this on the agent's page, for its main model, its selectable models and its sub-agents' models.

Tool search is off by default: every tool goes up front. The agent switches it on and picks and orders its methods in tool_search_provider_configuration:

Setting	Type	Default	Description
enabled	bool	false	true loads on-demand tools through tool search; false sends every tool up front
include_sources	list	null	The methods to use, preferred first; a method listed here is on. Unset: the methods whose own block sets "enabled": true, in the order server, client, emulated
exclude_sources	list	null	Methods never to use

client and emulated also take settings in client_tool_search_source_configuration and emulated_tool_search_source_configuration:

Setting	Type	Default	Description
catalogue	groups, names, descriptions	names	How much the search tool's description lists of the on-demand tools: their groups, the groups with tool names, or every tool with a one-line description
max_results	int	8	Most tools one search loads

"tool_search_provider_configuration": { "enabled": true, "include_sources": ["client", "emulated"] },
"emulated_tool_search_source_configuration": { "catalogue": "groups" }

Tool Sources

Source	CLI name	Description
Index Tools	index-tools	Search, browse, and inspect any Zeta Alpha index
Tag Tools	tag-tools	List, search within, create, and manage user tags
Document Tools	document-tools	Read, locate, and retrieve metadata for individual documents
User Document Tools	user-document-tools	Search, list (with status), add, edit, and remove the user's own uploaded documents
Presentation Tools	presentation-tools	Build PowerPoint decks on a corporate template from My Documents, or on PowerPoint's default design (Zeta Alpha platform only)
Office Add-in Tools	office-addin-tools	Change the email, workbook, document or presentation open next to the Zeta Alpha panel in Outlook, Excel, Word and PowerPoint, asking the user before each change by default
Note Tools	note-tools	Create, edit, delete, attach, and list the user's notes
Web Tools	web-tools	Fetch and browse content from the web (optional extra web_tools)
Image Tools	image-tools	Validate images against retrieved document pages
DataFrame Tools	dataframe-tools	Load, analyze, and visualize tabular data (CSV/Excel) (optional extra dataframe_tools)
Plot Tools	plot-tools	Plot data the agent passes directly, shown inline in the conversation (optional extra dataframe_tools)
Image Generation Tools	image-generation-tools	Generate pictures with an image model, shown inline in the conversation
SQL Database Tools	sql-database-tools	Explore and query SQL databases (optional extra sql_tools)
Platform Docs	platform-docs	Browse and read Zeta Alpha platform documentation
Onboarding	onboarding	Guided new-user onboarding: step instructions in the prompt plus a progress-reporting tool
Sub-Agent	sub-agent	Spawn isolated sub-agents for parallel work
Attempts	attempts-tools	Commit candidate answers to a scored lineage on tasks that match a rubric
Refine	refine-tools	Let the agent request edits to its own memories, skills, prompt notes and sub-agents

---

Index Tools

Search, browse, and inspect any Zeta Alpha index.

za agents capabilities tool-sets configure index-tools

Tools

Tool	Description
search	Search the knowledge base for documents matching a query, ranked by relevance. facets (faceted field paths) counts the distinct values of those fields over every hit, not just the returned page, in facet_results
browse	List documents by criteria with sorting — for exploring, not relevance-ranked
get_filter_options	Discover available filter fields and their values for the current index
get_document_fields	Discover metadata fields available on documents by inspecting a sample
get_index_configuration	Retrieve index configuration: filters, sort options, sources, and indexes

Configuration

Setting	Type	Default	Description
fe_base_url	str	"https://search.zeta-alpha.com"	Frontend base URL for building source links
page_size	int	10	Results per search page
browse_page_size	int	20	Results per browse page
max_facet_terms	int	1000	Values a requested search facet lists before it reports itself truncated
default_retrieval_unit	"document" | "chunk"	"chunk"	Return precise passages or full documents
default_retrieval_method	"knn" | "keyword" | "mixed"	"mixed"	Semantic search, keyword matching, or hybrid
default_collapse_key	str or null	null	Group results by this field (deduplication)
description	str	""	Tell the agent what it's searching over
description_field	str	"custom_metadata.metadata.abstract"	Field path for document descriptions
metadata_fields	list[str | MetadataFieldConfig]	["...title", "...source", "...created"]	Metadata fields to extract from hits. Plain strings are included in all scopes; use {"field": "...", "scopes": ["search"]} for fields that should only appear in search/browse results (excluded from listing previews). Available scopes: "search", "listing".
known_filters	list[FilterHint]	[]	Pre-defined filter hints (field_path, description, values, example_values)
sort_field_mapping	dict[str, str]	{"date": "date", ...}	Map user-friendly sort names to backend field names
show_results	bool	false	Stream the query and top hits (title, link) of search and browse to the chat timeline

Describe Your Knowledge Base

The most important settings for search quality are description and known_filters. Write description as you would describe the collection to a new researcher:

description (str) []: R&D papers from arXiv and top ML/AI conference venues (NeurIPS, ICML, ICLR), covering 2000–2026.

For known_filters, provide a JSON array:

known_filters (List[FilterHint]) [[]]: [{"field": "source", "description": "Publication venue"}, {"field": "year", "description": "Publication year"}]

Auto-Generate with the Index Explorer

Instead of writing the configuration by hand, use the Index Explorer — an instruction source that gives the agent a methodology to autonomously probe your document collection and generate a ready-to-use configuration.

Step 1: Enable the Index Explorer instruction source:

za agents capabilities instruction-sources configure index-explorer

Step 2: Start the development UI and tell the agent:

za agents dev

Run the Index Explorer

The agent will inspect the index structure, discover facets, run targeted searches, and output a complete configuration you can paste into your index-tools settings.

tip

After the Index Explorer generates the configuration, you can disable it — it's only needed during setup.

---

Tag Tools

List, search within, create, and manage user tags (collections/folders of documents).

za agents capabilities tool-sets configure tag-tools

Tools

Tool	Description
list_user_tags	List all tags the user has access to (own or shared)
list_documents_in_tag	List documents in a tag with pagination and metadata
search_in_tag	Search for documents within a specific tag (semantic + keyword, scoped)
tag_document	Add a document to a tag
untag_document	Remove a document from a tag
tag_note	Add a note to a tag
untag_note	Remove a note from a tag
create_tag	Create a new personal tag with name and optional description

Configuration

Setting	Type	Default	Description
max_documents_per_page	int	20	Max documents per page when listing tag contents

---

Document Tools

Read, locate, and retrieve metadata for individual documents by ID or fuzzy name.

za agents capabilities tool-sets configure document-tools

Tools

Tool	Description
read_document	Read the full content of a document by its document ID
locate_document	Find a document by fuzzy title, URL, or file name
retrieve_metadata	Get structured metadata for a list of documents by their IDs

Configuration

Setting	Type	Default	Description
page_size	int	10	Number of results for locate_document keyword search

---

User Document Tools

Search, list, add, edit, and remove the user's own uploaded documents.

za agents capabilities tool-sets configure user-document-tools

Tools

Tool	Description
search_my_documents	Search the user's private uploaded documents by content relevance
list_my_documents	List the user's uploaded documents with pagination, metadata previews, and ingestion status (PENDING/SUCCESS/ERROR)
create_my_document	Create and index a document from pasted text so it becomes searchable in the user's private My Documents. Saved as Markdown. With word_documents: true in user_document_tools_source_configuration, the model can also save a Word file (.docx with the Markdown's headings, lists, tables and emphasis) through file_format: "word" (Zeta Alpha platform only)
update_my_document	Update a private document's metadata (title, source, authors, year)
delete_my_document	Delete a private document from the user's My Documents

Configuration

Setting	Type	Default	Description
list_page_size	int	20	Default page size for listing user documents
show_results	bool	false	Stream the query and top hits (title, link) of search_my_documents, and the created document's card, to the chat timeline
word_documents	bool	false	Let create_my_document also save a Word (.docx) file (Zeta Alpha platform only)

---

Presentation Tools

Build PowerPoint decks on the user's corporate template. The template is a .pptx or .potx the user uploaded to My Documents; the agent finds it with the User Document Tools. Without a template, the deck uses PowerPoint's default design. Each deck is saved to My Documents as a new .pptx, so earlier versions stay available. It runs on the Zeta Alpha platform only; the agents SDK does not ship it. Configure it under presentation_tools_source_configuration.

Tools

Tool	Description
describe_template	List the template's (or the default design's) slide layouts with their placeholders, and the layout and title of each example slide
create_presentation	Build a deck from a slide list (per slide: a layout name, title, bullets, an optional table, speaker notes, and sources written into the notes) and save it to My Documents. The template's example slides are dropped. Returns the document's link and warnings about content a layout could not hold

Configuration

Setting	Type	Default	Description
fe_base_url	str	https://search.zeta-alpha.com	Navigator URL the returned document link points to

---

Office Add-in Tools

Let the agent change what the user has open next to the Zeta Alpha panel in Outlook, Word, Excel and PowerPoint. The tools are offered only on turns sent from the panel, and only those of the app it is open in. Every call goes to the panel, which runs it; a change asks first by default, with a card the user can edit and then allow once, always allow for the chat, or deny. Only the agent the user chats with gets the tools: an agent it delegates to or starts with task sees the open file but returns its content for the first agent to apply. The panel makes the change through Office.js and the agent reads what happened as the tool's output. Whether a change asks follows the source's Asks first setting and the agent's and tenant's setting rules on tools:office_addin_tools, like any tool. excel_read, word_read and powerpoint_read only read, and run without asking.

Tools

App	Tool	Description
Excel	excel_read	Read a range's values, formulas and number formats (up to 10,000 cells), find the cells holding a text, or list every sheet's used range, tables, charts and pivot tables. Runs without asking
Excel	excel_write	Write values and formulas to a range, with an optional comment on its first cell. Formulas that reach outside the workbook (WEBSERVICE, HYPERLINK, IMAGE, RTD, CALL, REGISTER.ID, FILTERXML, DDE) are refused. Reports the previous contents
Excel	excel_format	Number format, fill, font, alignment, wrapping, borders, column width, merging, and allowed input (a dropdown list or a number range)
Excel	excel_rules	Conditional formatting: color scale, data bars, icons, above, below, between, equal, contains, formula, top or bottom N, duplicates, or clear
Excel	excel_table	Create a table, or sort, filter, style or total one
Excel	excel_chart	Add a chart, or change a chart's type, titles and position
Excel	excel_pivot	Add a pivot table with row, column, value and filter fields
Excel	excel_sheet	Add, rename, copy, delete or show a sheet, freeze panes, color its tab, place a picture
Word	word_read	Read the outline, paragraphs with styles, the paragraphs holding a text, comments or tracked changes. Runs without asking
Word	word_write	Write Markdown with Word's styles at the selection, start or end, before or after a paragraph, in place of paragraphs or of a text, or in the header or footer, optionally as a tracked change. Reports what it replaced
Word	word_format	Apply a style, highlight, bold, italic, color or alignment to paragraphs or to a text
Word	word_comment	Add a comment, or reply to or resolve one
Word	word_review	Turn tracked changes on or off; accept or reject all or chosen changes
PowerPoint	powerpoint_read	Read the layouts and each slide's shapes with id, kind, position and text. Runs without asking
PowerPoint	powerpoint_add_slides	Add slides on the presentation's layouts with a title, bullets, a table and a picture
PowerPoint	powerpoint_edit_slide	Set a shape's text, add a text box, table or picture, move, resize or delete a shape, change the layout
PowerPoint	powerpoint_arrange	Move, duplicate or delete slides
Outlook	outlook_compose	Open a new email, reply or reply all, prefilled with a Markdown body; the user sends it
Outlook	outlook_edit_draft	Write into the open draft, set its subject, add recipients
Outlook	outlook_meeting	Open a prefilled meeting, or fill in the one being written; the user sends it

Pictures are passed as image:<id> from Image Generation Tools or plot:<id> from the plot tools, and must be made in the same answer. Charts on slides are plot pictures: Office.js has no chart API for PowerPoint.

No additional configuration beyond enabled.

---

Note Tools

Create, edit, and delete notes, attach notes to documents, list the user's notes, and search the notes the user can read.

za agents capabilities tool-sets configure note-tools

Tools

Tool	Description
create_note	Create a standalone personal note
create_document_note	Attach a note to a specific document by its document ID
update_note	Edit an existing note's content (keeps its document attachment)
delete_note	Delete a note
list_my_notes	List the user's notes with pagination
search_notes	Search notes by content: the user's own and those colleagues shared with them. Chat conversations saved as notes are left out; when that empties a page, the response says so and points to the next page

Configuration

Setting	Type	Default	Description
list_page_size	int	20	Default page size for listing notes
search_filters	dict	{"metadata.DCMI.format": "free_note"}	Index filter that selects the notes search_notes returns
search_id_field	str	"custom_metadata.metadata.identifier"	Index field that holds the note ID
search_content_field	str	"custom_metadata.metadata.abstract"	Index field that holds the note content
search_created_at_field	str	"custom_metadata.metadata.created"	Index field that holds the creation date
exclude_chat_notes	bool	true	Leave out chat conversations saved as notes

The search_* defaults match the notes-ingestion content source of new tenants. A tenant whose content source maps these note fields to other index fields sets them here; one that does not index the note type at all needs that mapping added and its notes re-ingested.

---

Web Tools

Fetch and browse content from the web.

Optional extra

Install with pip install zetaalpha.agents[web_tools].

za agents capabilities tool-sets configure web-tools

Tools

Tool	Description
web_fetch	Fetch a web page and return its content as clean text/markdown
web_search	Search the web using a federated search engine (only available if federated indexes exist)

Configuration

Setting	Type	Default	Description
output_markdown	bool	true	Return content as markdown instead of plain text
max_content_chars	int or null	null	Truncate fetched content to this many characters
timeout_seconds	float	30.0	Timeout for each fetch request
search_timeout_seconds	float or null	5.0	Timeout for each web_search call, so one slow upstream source can't stall the turn. null disables it
cache_max_size	int	50	Maximum number of cached responses
cache_ttl_seconds	float	900.0	Cache entry TTL in seconds
upgrade_to_https	bool	true	Upgrade http:// URLs to https://
blocked_hostnames	list[str] or null	null	Additional hostnames (matched by suffix) to block from crawling
allowed_hostnames	list[str] or null	null	Optional exact-match hostname allowlist. null disables the allowlist; a non-empty list denies every hostname not listed
allowed_ports	set[int]	{80, 443}	Connection ports allowed for crawling
max_response_bytes	int	5242880 (5 MiB)	Maximum bytes read from a non-PDF response
max_pdf_bytes	int	20971520 (20 MiB)	Maximum bytes read from a PDF response
max_pdf_pages	int	50	Maximum number of PDF pages to extract
max_pdf_chars	int	200000	Maximum characters extracted from a PDF
allowed_content_types	list[str] or null	null	Optional content-type allowlist. null uses the built-in default set (HTML, plain text, common XML feeds, and PDF)
untrusted_content_envelope	bool	true	Wrap fetched content in a <fetched_content> envelope marking it as untrusted web data
show_results	bool	false	Stream the query and top hits (title, link) of web_search to the chat timeline

Security

web_fetch treats every URL and every byte it returns as untrusted. The following protections are always on and cannot be disabled through prompts:

• SSRF and DNS rebinding. URLs are validated before each request, hostnames are resolved, and requests to private, loopback, link-local, or otherwise reserved IP ranges (including cloud metadata endpoints) are rejected. The resolved IP is pinned for the connection so a hostname cannot resolve to a safe address during validation and a private one at connection time.
• Redirect bypass. Redirects are not followed automatically; every hop is re-validated and re-resolved, and the chain is capped to a small number of hops.
• Blind SSRF / OAST exfiltration. Known out-of-band interaction domains (e.g. interaction-collector services and tunnelling providers) are blocked before any connection is made.
• Oversized and decompression-bomb responses. Responses are streamed and capped by max_response_bytes (or max_pdf_bytes for PDFs); PDF extraction is further bounded by max_pdf_pages and max_pdf_chars.
• Unsafe content types. Only content types in allowed_content_types are parsed; everything else is rejected. The content type is sniffed, not trusted from the Content-Type header alone.
• Prompt injection. Fetched content is returned inside a <fetched_content> envelope and any literal envelope tags in the page are escaped, so models can distinguish untrusted web data from instructions.

Use allowed_hostnames, allowed_ports, and allowed_content_types to tighten the defaults for high-assurance deployments. Every fetch emits a structured web_fetch log entry (URL, final URL, status, content type, bytes read, truncation, block reason, and duration — never the page body) for auditing.

---

Image Tools

Validate images against retrieved document pages using a multimodal LLM.

za agents capabilities tool-sets configure image-tools

Tools

Tool	Description
validate_image_hit	Visually compare a user-uploaded image against a rendered PDF page using a multimodal LLM

Configuration

Setting	Type	Default	Description
validation_prompt	str	(built-in Jinja template)	LLM prompt template for visual comparison
render_dpi	int	96	DPI for rendering PDF pages to images

---

DataFrame Tools

Load, analyze, and visualize tabular data from CSV/Excel files.

Optional extra

Install with pip install zetaalpha.agents[dataframe_tools].

za agents capabilities tool-sets configure dataframe-tools

Tools

Tool	Description
load_dataframe	Load a CSV/Excel document into a named DataFrame
get_dataframe_schema	View column names, types, and sample values
preview_dataframe	Preview the first few rows
read_dataframe	Read rows with pagination
count_dataframe_rows	Count total rows
get_column_values	Get unique/top values of a specific column
get_column_statistics	Get descriptive statistics for a numeric column
get_missing_value_counts	Count missing/null values per column
filter_dataframe_rows	Filter rows using conditions (eq, neq, gt, lt, in, contains, etc.)
sort_dataframe_rows	Sort by a column
aggregate_column	Sum, mean, min, max, count with optional group-by
merge_dataframes	SQL-style join of two DataFrames
concatenate_dataframes	Concatenate multiple DataFrames vertically
read_workbook_formulas	Read an Excel (.xlsx) document's formulas and defined names with their cached values, for all sheets or one sheet and range (up to 300 formula cells). Offered only with read_workbook_formulas: true in dataframe_tools_source_configuration
create_basic_plot	Bar, line, or scatter charts
create_multi_series_plot	Plots with multiple Y-series overlaid
create_distribution_plot	Histogram or box plots
create_time_series_plot	Time-series line plots with date parsing
create_correlation_heatmap	Correlation heatmap for numeric columns

No additional configuration beyond enabled.

---

Plot Tools

Plot data the agent passes directly in the tool call — no loaded dataframe required. The rendered image is shown inline in the conversation; the agent receives a text confirmation and continues its answer.

Optional extra

Requires matplotlib, installed with pip install zetaalpha.agents[dataframe_tools].

za agents capabilities tool-sets configure plot-tools

Tools

Tool	Description
create_plot	Line, area, bar (incl. stacked and horizontal), pie, donut, scatter, histogram, or box plot from named series of values

No additional configuration beyond enabled.

---

Image Generation Tools

Generate pictures (illustrations, diagrams, mock-ups) with an image model. The picture is shown inline in the conversation where the agent places it; the agent receives an image_id and a text confirmation and continues its answer.

The image model is a named LLM configuration of type image (gpt-image-2.5 on OpenAI or Azure OpenAI), set in the agent's image_llm_selection_configuration block:

{
  "llm_configuration_name": "gpt-5.2",
  "agent_configuration": {
    "image_llm_selection_configuration": { "llm_configuration_name": "gpt-image-2.5" },
    "image_generation_tools_source_configuration": { "enabled": true }
  }
}

za agents capabilities tool-sets configure image-generation-tools

Tools

Tool	Description
generate_image	Generate one image from a prompt

When the provider's safety system rejects a prompt or the generated picture, or the model is rate limited, the tool reports it to the agent (blocked, rate_limited) instead of failing the turn, so the agent can rephrase or tell the user.

Configuration

Setting	Type	Default	Description
max_images_per_turn	int	2	Images the agent may generate in one answer
request_timeout_seconds	float	180	Give up on a generation that does not finish within this time

Quality, output format and moderation strictness live on the LLM configuration's image_settings, see Image models.

---

SQL Database Tools

Explore schemas and query SQL databases — filter, sort, aggregate, join, and insert without writing raw SQL.

Optional extra

Install with pip install zetaalpha.agents[sql_tools]. For databases other than PostgreSQL, install the appropriate SQLAlchemy dialect driver.

za agents capabilities tool-sets configure sql-database-tools

Tools

Tool	Description
sql_list_tables	List accessible tables
sql_get_table_schema	Get column names and types for a table
sql_preview_data	Preview the first few rows of a table
sql_read_data	Read rows with pagination
sql_count_rows	Count total rows
sql_get_row_by_pk	Get a single row by primary key
sql_select_columns	Select specific columns (deferred plan)
sql_get_column_values	Get distinct values of a column
sql_filter_table_rows	Filter rows using conditions (deferred plan)
sql_sort_table_rows	Sort rows (deferred plan)
sql_aggregate_column	Sum, mean, min, max, count with optional group-by (deferred plan)
sql_join_tables	Join two tables/plans on shared columns (deferred plan)
sql_insert_row	Insert a single row

Tools that produce intermediate results return a named reference for subsequent operations (e.g., filter → aggregate → sort → read).

Configuration

Setting	Type	Default	Description
connection_string	str	"" (required)	SQLAlchemy connection string
allowed_schemas	list[str] or null	null (all)	Restrict access to these schemas
allowed_tables	list[str] or null	null (all)	Restrict to these tables (schema.table)
max_rows_per_query	int	10000	Maximum rows returned per read
query_timeout_seconds	int	30	Query timeout in seconds

Security

Always use allowed_schemas and/or allowed_tables to restrict access. Use a read-only database user when the agent only needs to query.

---

Platform Documentation Tools

Browse and read the Zeta Alpha platform documentation, giving the agent self-knowledge about the platform.

za agents capabilities tool-sets configure platform-docs

Tools

Tool	Description
list_platform_doc_pages	List all available documentation pages from the sitemap
read_platform_doc	Read a documentation page and return its content as text

Configuration

Setting	Type	Default	Description
docs_base_url	str	"https://docs.zeta-alpha.com"	Base URL of the documentation site
sitemap_path	str	"/sitemap.xml"	Path to the sitemap XML
max_content_chars	int or null	null	Truncate fetched page content
cache_max_size	int	50	Maximum cached pages
cache_ttl_seconds	float	900.0	Cache TTL for fetched pages
sitemap_cache_ttl_seconds	float	3600.0	Cache TTL for the parsed sitemap
timeout_seconds	float	30.0	HTTP request timeout

tip

Pair with the Platform Docs instruction source for a complete self-knowledge setup — instructions tell the agent what the platform can do, tools let it look up how.

---

Onboarding

Drives the guided new-user onboarding flow: injects step-by-step behavioral guidance into the system prompt and provides a tool the agent calls to report progress, which the platform UI renders as a progress bar. The steps list is the single source of truth — step prose, counters, and the generated progress calls all derive from it.

za agents capabilities tool-sets configure onboarding

Tools

Tool	Description
update_onboarding_status	Reports the step the user is moving to; reaching the last step marks onboarding complete

Configuration

Setting	Type	Default	Description
steps	list	built-in 4-step flow	Ordered steps, each with title, content, and optional status_label (progress-bar label, falls back to title)
instructions	str or null	null	Cross-cutting instructions inserted before the steps (e.g. language, terminology)

Custom steps and the opening message

The onboarding chat opens with a static greeting, not one generated from steps: the onboarding bot's bot_params.initial_message (in client_settings.bot_configurations), falling back to the locale bundle's chat.json onboarding.defaultMessage. The agent treats the conversation as already inside step 1, and the default greeting ends with the default flow's first question — so when you override steps, also set initial_message to a greeting that ends with your first step's question. Otherwise the transcript opens with a question that contradicts step 1's instructions, and the agent's first replies become unpredictable.

warning

The platform frontend enables this source at runtime — only for onboarding conversations — by injecting onboarding_tools_source_configuration: { "enabled": true } into the chat's bot params. Two configuration rules follow:

• Leave enabled unset in the agent configuration. An explicit value there takes precedence over the runtime flag: "enabled": true puts onboarding guidance and the progress tool in every conversation with that agent, and "enabled": false disables onboarding entirely. Configure only steps/instructions.
• Do not add onboarding to the tools provider's include_sources allowlist. An allowlist overrides the enabled flag entirely, so listing it activates onboarding for every conversation, and defining an allowlist without it silently disables onboarding. Agents used for onboarding should not define an include_sources allowlist.

---

Sub-Agent

Spawn isolated sub-agents to perform focused, parallel work.

za agents capabilities tool-sets configure sub-agent

Tools

Tool	Description
task	Launch an isolated sub-agent with a prompt and description for a focused unit of work

Configuration

Setting	Type	Default	Description
verbose	bool	true	Include detailed behavioral guidance in tool description
include_in_prompt	bool	true	Inject delegation instructions into the system prompt
extra_instructions	str or null	null	Append additional delegation guidance
tool_description	str or null	null	Fully replace the default tool description
allow_llm_selection	bool	false	Let the agent pick the sub-agent's LLM by name, within its allowed names
sub_agent_approvals	ask, decline, run	ask	What a sub-agent does with a tool call that needs the user's approval, as for delegated agents

Sub-agents run in isolated context: they receive the task prompt and what the user attached to the chat, not the parent conversation. By default a sub-agent cannot launch sub-agents of its own, and task and delegate share one budget per turn, counted across every agent the turn starts: see Sub-Agent Limits. Protected parameters (tenant, auth headers, index configuration) are carried through automatically.

Looking for named agent delegation?

The delegate tool (routing to named specialized agents) comes from the delegation provider, not the sub-agent tool source. See Configuring Delegation.