Simple Agent Designer Documentation
Index

Built-in Tools

Simple Agent Designer includes a set of built-in tools that give agents the ability to interact with Business Central data. This page provides a reference for each built-in tool, grouped by purpose.

The Data-Context Model

Before reading the individual tools, it is important to understand how the built-in tools work together. The tools are data-context based, not record-addressed. This is the single most important concept for understanding the built-in toolset.

  • A tool that creates or finds a record (for example create_data, create_sales_document, find_data_set_as_current_context, create_journal_line) sets a current data context — a single record that the agent is now "working on".
  • Follow-up tools such as update_field, update_fields, add_document_line, update_document_line, get_dimension_set_id, and upload_document_to_current_datacontext operate on that current context. They do not take a table name or record identifier — they always act on whatever record is currently in context.

A typical flow therefore looks like this:

  1. Create or find a record — this becomes the current context.
  2. Set field values on the context with update_field / update_fields.
  3. For documents, append and edit lines with add_document_line / update_document_line.

Keeping this model in mind explains why many of the tools below take no parameters, or only take the values that belong on the record itself.

Data & Context

find_data_set_as_current_context

Purpose: Find a record by its primary key and set it as the current data context.

Parameters:

Parameter Type Required Description
table string Yes Name of the BC table
key_value1 string Yes First primary-key value
key_value2 string No Second primary-key value
key_value3 string No Third primary-key value

Behavior:

  • Locates the record whose primary key matches the supplied key values.
  • Sets it as the current data context for subsequent tool calls.

Example Use Case: An agent needs to work with a specific customer across several tool calls, so it sets the customer as the current context first, then updates fields on it.

create_data

Purpose: Create a new record in a Business Central table and set it as the current context.

Parameters:

Parameter Type Required Description
table string Yes Name of the BC table
key_value_1 string Yes First primary-key value for the new record
key_value_2 string No Second primary-key value

Behavior:

  • Inserts a new record, setting only the primary-key fields from the supplied key values.
  • Sets the new record as the current data context so that follow-up update_field / update_fields calls can populate the remaining fields.

Important: This is a generic record insert. It is not intended for journals or sales/purchase documents — use the dedicated document and journal tools for those.

Example Use Case: An agent creates a new item record, then sets the description, unit price, and other fields with update_fields.

update_field

Purpose: Update a single field on the current data-context record.

Parameters:

Parameter Type Required Description
field string Yes Name of the field to update
value string Yes New value for the field

Behavior:

  • Updates the named field on the current context record using a type-aware validate.
  • Returns the updated record as JSON.

Example Use Case: After creating a sales header, an agent sets the customer number with update_field.

update_fields

Purpose: Update multiple fields on the current data-context record in a single call.

Parameters:

Parameter Type Required Description
fields object Yes An object of field name / value pairs

Behavior:

  • Applies each name/value pair to the current context record.
  • Returns the updated record.

Example Use Case: An agent populates several header fields — customer number, posting date, and external document number — at once after creating a document.

lookup_data

Purpose: Perform a fuzzy, free-text lookup to resolve a value against common master-data tables.

Parameters:

Parameter Type Required Description
table string Yes The table to search
search string Yes Free-text search term

Behavior:

  • Performs a fuzzy free-text search across a set of special-cased tables, including Customer, Vendor, Item, G/L Account, Bank Account, Dimension, Dimension Value, Customer Ledger Entry, Item Reference, Item Attribute, and generic table/field lists.
  • Returns the matching records to help the agent resolve names to numbers.

Important: This is a fuzzy lookup tool, not a filter-expression or field-projection query. To run structured queries with filters, joins, and aggregates, use run_sql_query.

Example Use Case: The workload mentions "Contoso" and the agent uses lookup_data with table: "Customer", search: "Contoso" to find the customer number.

Querying Data (SQL)

These tools let an agent explore the data model and run structured, read-only queries.

run_sql_query

Purpose: Run a read-only SQL SELECT query against Business Central tables.

Parameters:

Parameter Type Required Description
query string Yes A SQL SELECT statement

Behavior:

  • Executes the query through an internal AL SQL engine against BC tables.
  • Read-only: the result set is capped at 1000 rows.
  • Table and field names that contain spaces or special characters must be wrapped in square brackets, for example:
SELECT [No.], Name FROM [G/L Account] WHERE [Balance] > 0

Supported: SELECT with WHERE; INNER, LEFT, LEFT OUTER, and CROSS joins; GROUP BY; HAVING; ORDER BY; DISTINCT; TOP; OFFSET/FETCH; the aggregates COUNT, SUM, AVG, MIN, MAX; arithmetic and CASE; uncorrelated subqueries; EXISTS, IN, BETWEEN, LIKE, IS [NOT] NULL; and UNION/INTERSECT/EXCEPT.

Not supported: INSERT/UPDATE/DELETE (the engine is read-only), derived tables (subqueries in the FROM clause), and RIGHT/FULL joins.

Example Use Case: An agent needs total sales per customer for a period and runs a GROUP BY query joining the header and line tables.

find_table

Purpose: Discover table numbers and names by searching on a name or caption.

Parameters:

Parameter Type Required Description
search string Yes Name or caption to search for

Behavior:

  • Returns the table numbers, names, and captions that match the search term.
  • Use this to discover the correct table names to feed into run_sql_query or get_fields_in_table.

get_fields_in_table

Purpose: List the fields of a table.

Parameters:

Parameter Type Required Description
table string Yes The table whose fields to list
search string No Optional term to filter the returned fields

Behavior:

  • Returns the fields of the table with their No., Name, Caption, Type, Class, and Length/Options.
  • Optionally filters the field list by the search term.

Example Use Case: Before writing a run_sql_query, an agent lists the fields of a table it discovered with find_table to learn the exact field names.

Financial

get_gl_account_balances

Purpose: Retrieve G/L account balances and net change for a date range.

Parameters:

Parameter Type Required Description
start_date string Yes Start of the date range
end_date string Yes End of the date range
account_filter string No Optional account No. filter

Behavior:

  • Returns the Balance and Net Change for each G/L Account over the specified date range.
  • Applies the optional account No. filter, and skips rows with zero values.

Example Use Case: An agent checks the net change of expense accounts for the month before categorizing new expenses.

get_dimension_set_id

Purpose: Produce a Dimension Set ID for a combination of dimension values, based on the current context.

Parameters:

Parameter Type Required Description
dimensionsetid integer Yes The existing dimension set ID to merge the new values into
dimensions object Yes An object of dimension code / value pairs

Behavior:

  • Merges the supplied dimension code/value pairs into the existing dimension set.
  • Returns a new Dimension Set ID along with the resolved global dimensions.

Example Use Case: An agent building a journal line resolves department and project dimensions into a Dimension Set ID before assigning it.

Documents & Journals

These tools follow the data-context model. Several of them take no parameters — they create a blank record and set it as the current context, after which you populate fields with update_field / update_fields.

create_journal_line

Purpose: Create a general journal line.

Parameters: None

Behavior:

  • Creates a Gen. Journal Line in the configured journal template and batch.
  • Assigns a document number, sets the line as the current context, and adds a workload link to track it.
  • Set the account, amount, description, and other fields afterward with update_field / update_fields.

Example Use Case: An agent records an expense: it calls create_journal_line, then sets the account number, amount, and description on the resulting context.

create_item_journal_line

Purpose: Create an item journal line for inventory transactions.

Parameters: None

Behavior:

  • Creates an Item Journal Line, sets it as the current context, and adds a workload link.
  • Set the item, quantity, entry type, and other fields afterward with update_field / update_fields.

Example Use Case: An agent creates inventory adjustment entries from an uploaded stock count.

create_sales_document

Purpose: Create a sales document header and set it as the current context.

Parameters:

Parameter Type Required Description
type string Yes One of quote, order, invoice, creditmemo

Behavior:

  • Creates a Sales Header of the requested type and sets it as the current context.
  • Does not take a customer number or other header fields — set those afterward with update_field / update_fields.

Example Use Case: An agent creates an order with create_sales_document {type: "order"}, then sets the customer number with update_field.

create_purchase_document

Purpose: Create a purchase document header and set it as the current context.

Parameters:

Parameter Type Required Description
type string Yes One of quote, order, invoice, creditmemo

Behavior:

  • Creates a Purchase Header of the requested type and sets it as the current context.
  • Set the vendor and other header fields afterward with update_field / update_fields.

add_document_line

Purpose: Append a new line to the current document context.

Parameters: None

Behavior:

  • Appends a blank line to the current Sales or Purchase Header context and returns it.
  • Set the line values afterward with update_document_line.

Example Use Case: After creating a sales order and setting the customer, an agent calls add_document_line to start a new line, then fills it in.

update_document_line

Purpose: Update fields on a line of the current document context.

Parameters:

Parameter Type Required Description
line_number number Yes The line number to update
fields object Yes An object of field name / value pairs

Behavior:

  • Locates the line by its line number on the current document context and applies the supplied field values.

Example Use Case: After add_document_line, an agent sets Type, No., and Quantity on the new line with update_document_line.

Reports

get_reports

Purpose: Find reports by name or description.

Parameters:

Parameter Type Required Description
search string Yes Name or description to search for

Behavior:

  • Searches both Report Metadata and Financial Reports and returns the matches.

get_report_parameters

Purpose: Get the request-page definition for a report.

Parameters:

Parameter Type Required Description
provider string Yes Either report or financialreport
reportno string Yes The report number

Behavior:

  • Returns the report's request-page as XML, which the agent can adapt and pass to run_report.

run_report

Purpose: Run a report and save its output to Agent Work.

Parameters:

Parameter Type Required Description
provider string Yes Either report or financialreport
format string Yes Output format: text or PDF
reportno string Yes The report number to run
parameters string Yes The request-page XML text (not a JSON object)

Behavior:

  • Runs the specified report with the supplied request-page XML.
  • Saves the output to Agent Work. A PDF is made viewable by the user; XML output is converted to markdown and returned to the AI.

Example Use Case: An agent finds a report with get_reports, retrieves its request page with get_report_parameters, adjusts the filters, and runs it with run_report.

Skills

get_skill

Purpose: Retrieve a skill's full instructions.

Parameters:

Parameter Type Required Description
skill_code string Yes The code of the skill to retrieve

Behavior:

  • Looks up the skill by code and returns its full instructions text, which the agent then follows.

Example Use Case: An agent encounters a bank reconciliation task and retrieves the "BANK-RECON" skill for step-by-step guidance. See Skills for more on creating and managing skills.

Files & Excel Output

upload_document_to_current_datacontext

Purpose: Attach a user-supplied file to the current context record.

Parameters:

Parameter Type Required Description
file_name string Yes The name of the conversation file to attach

Behavior:

  • Attaches a file supplied in the conversation as a Document Attachment on the current data-context record.

Example Use Case: After creating a purchase invoice, an agent attaches the original vendor PDF to it.

create_new_sheet

Purpose: Start a fresh in-memory Excel sheet.

Parameters: None

Behavior:

  • Begins a new, empty in-memory Excel sheet that subsequent update_cell calls write into.

update_cell

Purpose: Set the value of a single cell in the current sheet.

Parameters:

Parameter Type Required Description
cell string Yes Cell reference in A1 notation, e.g. B3
value string Yes The value to place in the cell

Behavior:

  • Sets the cell value. A value prefixed with = is treated as a formula; a numeric string is stored as a number; anything else is stored as text.

save_sheet

Purpose: Save the buffered sheet as a downloadable .xlsx file.

Parameters:

Parameter Type Required Description
name string Yes The file name for the workbook

Behavior:

  • Writes the in-memory sheet to an .xlsx file and saves it to the Agent Work list, where the user can download it.

Note: Together, create_new_sheet, update_cell, and save_sheet let an agent generate an Excel workbook. This is separate from the Excel Splitter, which ingests Excel rows for processing. See Data Splitting.

Email

send_email_notification

Purpose: Email the workload's configured recipients.

Parameters:

Parameter Type Required Description
subject string Yes The email subject
body string Yes The email body
html boolean No Whether the body is HTML

Behavior:

  • Sends an email to the recipients configured on the workload's Email Recipients field (split on ; or ,). The AI does not choose the recipients.
  • Requires a standard Business Central Email Account to be configured.

Important: This tool is offered to the agent only when the current workload has an Email Recipients value set. If the field is empty, the tool does not appear in the agent's catalog.

A Note on compact_conversation

Earlier documentation described a compact_conversation tool for compressing conversation history. A handler for this exists in the code, but its registration is commented out — the tool is not currently exposed to agents and cannot be called. It is documented here only to correct earlier references.

Tool Availability

All built-in tools are available to any agent with Use Tools set to Yes, with one exception: send_email_notification is only offered when the workload has Email Recipients configured. There is no other per-agent filtering for built-in tools — the AI model decides which tools to call based on the task and instructions.

To see the complete list of tools available in your environment (including custom tools), use the Tools Available page on the Role Center.