Inflow.aiDocs

App Chat record tools and provider routing

This reference is for platform administrators and developers who need to understand how App Chat answers record questions. For publisher setup and user journeys, start with the App Chat chapter in the consultant assistant guide and the App Shell build tutorial.

What tool calling changes

App Chat can ask an AI model to select a read or draft operation from a fixed server-side tool catalog. This lets a person ask a natural-language question such as “How many high or medium priority requests are pending?” without repeating a manually authored query syntax. The model proposes the source, filters and operation; Inflow validates them and performs the read using the same source, actor, row, field and AI-disclosure rules that govern other App Chat evidence.

Tool calling does not create a new data source, grant record access, broaden an App Shell binding, or provide general SQL/database access. The publisher still selects the App Shell's sources, allowed operations, optional field allowlists and configured actions. Each user request runs as the authenticated actor, and prior or newly retrieved references are rechecked before the model receives another turn of data.

Service configuration and routing

The application assembly enables the feature by default through:

inflow.app-chat.tools.enabled=true

This is a service-level property, not a per-App-Shell Studio control. Setting it to false selects the existing conservative App Chat query path. The App Shell's own chat switch, sources, operations and actions continue to govern which user-facing operations are available.

When enabled, a tool turn asks the AI Gateway for both CHAT and TOOL_CALLING capabilities. Provider/model selection still follows the normal AI Gateway connection, workspace policy, data classification and capability rules. A pre-dispatch routing/capability refusal falls back to the conservative query path. A model that does not use the expected JSON tool protocol on its first reply is not immediately retried through that path: a safe plain-text answer may stand subject to grounding, while an empty or malformed reply produces the existing unfinished response. A second consecutive protocol refusal from the same model in the workspace pauses tool requests for one hour; the refusal turn and later turns during that pause use the conservative path. A successful protocol reply clears the consecutive-refusal count. This fallback is intentionally conservative and should not be described as proof of a full search unless the returned evidence establishes that.

Fixed tool catalog

Operation Purpose and bound Required configuration
search_records Return matching rows from one bound record source. Source permits READ; requested fields and filters pass disclosure and schema validation. Limit 1–20, default 10.
count_records Return the exact number of matching rows. Source permits AGGREGATE; server performs the aggregate.
aggregate Return exact sum, average, min or max for a numeric measure. Source permits AGGREGATE; measure is numeric, readable and AI-disclosable.
get_record Read one record by a supported key from a bound source. Source permits READ; target is resolved through the pinned read path.
list_my_tasks List open tasks available to the authenticated person in an eligible inbox. Inbox is bound and readable; canonical task membership and partial-visibility outcomes are preserved. The caller cannot name another person's actor.
propose_action Prepare a configured action draft against a validated record/task target. Action is bound; target belongs to that action's source/inbox; only declared input names are accepted. The operation does not execute the action.

Linked-record enrichment for task lists

list_my_tasks can attach a recordKey when the server can prove one unique link from a task's disclosed subject values to a currently readable record in a bound READ source. It also returns recordLinksPartiallyUnavailable. If that flag is true, at least one task/source lookup could not establish a complete answer; a missing recordKey is not proof that the task has no linked record. The model is instructed to ask the person to choose rather than infer a task-record relation from partial coverage. The task and record remain subject to ordinary authorization, row admission, field disclosure and App Shell source bindings.

The list enrichment batches task subjects instead of issuing one lookup per task: for each eligible source, it selects the most common disclosed subject field and queries its distinct values together. A batch is limited to 100 values; the safe per-turn linked-record query budget is 128. A link is complete only when the lookup has all required subject fields in the row-admission projection, returns an OK page with no more rows, and yields zero or one match. Multiple matches, unavailable source metadata/read, omitted fields, exceeded bounds, or incomplete results mark the link as unavailable rather than as a definitive no-link. These limits apply to task-list enrichment; action target resolution still follows the separate current-record/prior-answer/open-task rules below.

Record filters are limited to five filters per call and the operators eq, neq, in, contains for text, and range for numeric/date fields. Date-only alternatives on date-time fields can expand into separate branches (for example, neq one date means before-or-after that whole day); a call is refused if that expansion would exceed eight branches. The server rejects unknown sources, fields, operators, values outside a field's declared values, or fields that fail the current read/disclosure policy before issuing the corresponding read. Free-text equality filters use the case-insensitive matching described below. Date-only boundaries use the authenticated user's or workspace's configured time zone. Do not copy values from a different record type or assume that a visually similar field has the same schema.

Per-turn bounds and evidence

A turn may make at most four model calls that request tools. Each such reply may contain up to four tool calls; additional calls in the same reply are ignored. The service then makes one final answer call with tools unavailable. Thus, the maximum tool-mode sequence is four tool-request steps plus a final response call. The ordinary conservative path uses its existing single model response path.

Search accepts at most 20 requested results per call, and at most 40 record/task rows are supplied to the model across the whole turn. Results beyond a display/model bound are marked as more or counted as not shown; the assistant must not call such a subset the complete list. count_records and aggregate return exact server-side values for the authorized query; never infer a total from the visible search page or guidance passages. A task listing can carry a partial/unavailable signal and must be described as partial when it is.

Every returned row or aggregate contributes evidence and source lineage. The service live-checks contributing references before the first provider call, refreshes that gate before a later tool-loop provider call when more than 10 seconds have elapsed since the last gate, and checks again after the final provider call before committing or emitting the answer. It also rechecks prior-turn lineage before the assistant reuses that answer. Quick tool-loop calls may reuse the previous gate: already admitted results can therefore remain in a later provider request until the next refresh or final check. Withholding a later answer cannot retract content already sent to the provider. Each new tool read still uses the actor's current source and field authorization. If the final check finds access revoked or deleted during the turn, the dependent answer/history block is withheld. Each gate deduplicates references using source, lineage identity/version, kind, target and contributing fields. The turn starts a shared 45-second revalidation budget. The gate checks that deadline before each distinct live-access call; it does not interrupt a live-access call already in progress. When the budget is spent, a later gate fails closed and the dependent answer is withheld. Model-generated tool arguments and tool results are data, not instructions; tool output is not appended as trusted system policy. Cancellation, publication scope and lineage checks occur before provider calls and action proposals remain drafts until the actor confirms them through the supported action flow.

Values, task context and record citations

For free-text fields without declared allowed values, eq, neq and in match without regard to letter case. Fields with declared values still require one of their allowed values. For example, if a free-text status is stored as Pending, asking for pending can still match that row. Category values can also be selected through paraphrases in the language of the current question: “waiting for review” can select Pending, and an Arabic question can select an Arabic value such as معلق when that is the value present in the readable rows. The server checks the model-selected eq, neq and in values for category fields against the question and earlier turns. A value is accepted when it is written in the question's script (including the same-language normalization used for Arabic), or when that value was named in an earlier turn. A different-language free-text value is not silently added: an English “pending” does not also select قيد الانتظار. The model is instructed to choose values grounded in the question and conversation, but the server-side check compares scripts; it does not verify that the exact word or phrase was present. A same-script value can therefore pass even if the person did not write it in the question. Values with no letters, such as numbers and scriptless codes, are treated as language-neutral and can also pass without being written in the question. This check does not prove that such a value was intended. The implementation can recognize a localized label declared on the same schema option, but the current production schema path does not populate those labels; cross-language category mapping is therefore not available to configure today.

For a free-text category in list, the server reports different-script values to the model and retains same-script or scriptless values. A same-script value or code may remain even if not written by the person; the guard is not an exact word-presence check. If no value passes the language check, the filter is refused rather than removed, since removing it could broaden the read. For a field with declared options, a value not in the declared options or a declared label is not pruned as a language mismatch: it reaches schema validation and the filter is rejected. The assistant should ask which value the person means or invite them to restate it in the language used by the records.

Inflow does not simply lowercase a query and assume that it found every spelling: it discovers spellings from the same actor-authorized rows, then applies the filter. That discovery is bounded at 200 rows. If many look-alike values fill the bound before a later spelling is found, an exact count or aggregate is withheld and a search is marked as possibly incomplete. Do not present a partial search as proof that no matching records exist. Category hints are considered only for schema-described, AI-disclosable text/string fields with no declared values, that are not unique or auto-numbered and whose field key does not match the identifier/reference pattern. From the actor's readable rows, a field is omitted if any observed non-null value is blank, non-string or longer than 40 characters, or if more than eight distinct values appear. A field is included only when its observed nonblank rows are at least twice its distinct-value count. The values are drawn from the bounded readable-row probe; names are not independently excluded based on their content.

When the person asks about their open tasks, task rows can include an about summary—for example, a leave-request employee and number of days—only when those values are AI-disclosable in a record source bound to the App Shell. It does not expose arbitrary task form contents. A configured action may target a lifecycle's state task (for example, leave-approval.state.review) when that task is actually part of the matching lifecycle. The server checks that membership again for listing/drafting/confirmation paths; a similarly named task from another lifecycle does not qualify. The task's current authorization and the explicit confirmation requirement still apply.

Record citations use a safe display name: one AI-disclosable business key when available, otherwise a suitable disclosed display value. They never show a sealed/internal locator or an aggregate locator. Duplicate citations are collapsed, and no more than ten chips are displayed. If the answer names records, only those records' chips are shown; when it names none, up to the first three are shown. When at least one named record or task chip is displayed, count and grouped- aggregate citations from the same answer are withheld from the chip row. They remain uncited contributing references in lineage with visibleCitation=false, so they are still revalidated. An aggregate-only answer can still show its aggregate citation. The remaining contributing records stay in lineage even when their chips are not displayed. A citation name is a navigation aid, not an access grant: opening it checks current access again. A task citation may use its AI-disclosable subject label rather than the generic action title. The chip row deduplicates repeated citations and can collapse tasks from one inbox with the same label; chip count is not a task count. Use the current task list/card to identify and review the exact task before deciding.

This behavior is implemented by DefaultAppChatService.focusRecordCitations and withholdAggregateCitations (platform-services-runtime/src/main/java/com/inflowai/platform/agent/appchat/DefaultAppChatService.java:4324-4385) and covered by AppChatLaneR2Test.aSingleRecordAnswerDoesNotCiteAnAggregateBesideIt and anAggregateAnswerStillCitesTheAggregate (platform-services-runtime/src/test/java/com/inflowai/platform/agent/appchat/AppChatLaneR2Test.java:211-244).

Worked examples

Exact count from a declared schema

Assume the connected Leave request source has readable, AI-disclosable fields priority and status, with declared priority values High, Medium and Low. The user asks: “How many high or medium requests are pending?” The total covers only rows the signed-in actor is authorized to read. If the answer must mean requests owned by that person, the source's row-level access policy must limit the readable rows to that actor. Tool filters do not map the word “my” to an actor identifier; without a confirmed row policy, do not claim an owner-specific total.

  1. The model selects the bound Leave request source and proposes priority in [High, Medium] plus status eq Pending.
  2. The server checks that the source permits aggregation, that each filter field is admissible, that in is valid for priority, and that High, Medium and Pending are declared values.
  3. The server performs the exact authorized count and returns that scalar as evidence. The model answers with the returned number and any available citation.

If Pending is not a declared status value, the service refuses the filter rather than silently translating it to another status. When the current conversation makes the intended status field clear, the assistant should answer the follow-up with a short stated assumption rather than ask the user to repeat it; ask only when two readings remain equally likely. A count returns an exact scalar, not the matching records: if the user follows “How many?” with “Which one?”, App Chat must run a new bounded search against the same connected source and filter, then answer only from the newly returned, currently authorized rows. This applies to both the tool-calling and conservative keyword paths. A ranked follow-up carries the validated filter set only when the immediately preceding answer still passes lineage/access revalidation. If the in-memory query frame is absent, a new process can recover the filter from that answer's durable lineage event after revalidation; the event stores a validated source ID and field/operator/value tuples, not an authorization grant or the old record result. A withheld/refused answer or one without a saved validated filter supplies nothing to carry. A follow-up that names a new stored value clears the previous filter set rather than combining incompatible values. Every new read still passes current source, row, field and disclosure checks. If the search is incomplete, qualify the answer as covering only those rows. If the source has no AGGREGATE operation, a search of the first 20 matching rows is not a substitute for an exact count.

Text fields without a declared value list can contain inconsistent capitalization. If the user's readable rows contain Pending, Approved and Rejected, the model may be told those short recurring categories. A count for pending matches Pending. If the bounded spelling read cannot prove it saw every spelling, the answer must not claim an exact count; the user should narrow the question or use the ordinary filtered record view.

Category-language examples

These examples assume the named category field is readable and AI-disclosable for the signed-in actor. The user-visible phrases are examples of the model's proposed filters; the server still validates each proposal before reading.

What the person asks Safe filter behavior
“How many requests are waiting for review?” For a same-language category such as Pending, a paraphrase can select status eq Pending. The count still requires the source's AGGREGATE operation and covers only the actor's authorized rows.
“كم عدد الطلبات المعلقة؟” (“How many requests are awaiting?”) If the actor-readable values contain the Arabic category معلق, the same-language Arabic normalization can select that value. This does not grant access to other users' rows or non-disclosable fields.
“How many requests are pending?” where some stored values are قيد الانتظار The English question does not silently add the Arabic value. If Pending is the safe named value, the read remains limited to that value. Current production schema assembly does not supply localized option labels, so do not expect an English label to map to an Arabic stored value.
“Show Pending or قيد الانتظار” as a free-text category question in English Pending may remain while the Arabic value is reported to the model. Same-script values not literally written, and scriptless codes, can pass the language check; inspect the results and name codes explicitly. If no value passes, the filter is refused. For a declared-choice field, an unknown Arabic value is rejected by schema validation rather than pruned from the list.
Earlier: “Show pending requests.” Follow-up: “Which one has the longest delay?” The prior filter can be reused, and the carried query continues to constrain each read. The service checks the contributing lineage before the first provider call and again after the final call; it rechecks prior-turn lineage before reuse. It withholds the dependent answer if the final check finds revoked or deleted access.

The Arabic normalization is a comparison aid, not translation: it removes selected diacritics and normalizes common letter and word-form variants before checking whether a value occurs in the question. It does not translate a value across languages. Localized option labels are represented in the schema type, but this current production path leaves that map empty; the examples above therefore do not imply that administrators can configure cross-language mappings.

Identify a task before proposing its decision

Sara asks: “Approve Huda's four-day leave request.” The app has a permitted task inbox and a configured approval action. The model can use the task's disclosed about values to distinguish the task from another request, but it cannot search unrelated task contents or another employee's inbox. Action target resolution is stricter than ordinary informational follow-up. When a current record is open, “this request” selects that record only when the action applies; otherwise the target stays unresolved and the resolver does not substitute another task or an older answer.

For “approve it” after the previous answer was about exactly one record, a task action can link the record to the signed-in person's own open tasks. The server compares task subject/business-key values with fields that are AI-disclosable in currently readable, App Shell-bound READ record sources and runs an access-checked unique-record lookup for each. It accepts a link when exactly one lookup returns one match. An ambiguous result or a source-read failure contributes no match for that source; it does not prove the unavailable source has no competing record. This link comes from task values, not a model-generated target guess, and the person still verifies the exact task before confirmation.

If exactly one applicable task links to the record and the open-task list is complete, the server may select it for a draft proposal. If several tasks link, or one links while the task list may be incomplete, App Chat asks the person to choose among the linked tasks. The resolver receives a linksComplete result and skips linked-task selection when that result is false; it does not use a partial link as proof. Its separate no-link fallback still considers action-applicable open tasks. If the open-task list is complete and contains one task, that task may be proposed even when the record-link lookup was incomplete or unavailable, so the proposal does not prove the task belongs to the discussed record. The person must inspect the exact task, record and action in the proposal, and cancel or identify the intended task when that relationship is unclear. The task-list recordLinksPartiallyUnavailable flag separately informs list enrichment; it does not disable this resolver fallback. A task already named in the immediately previous answer is considered first. Older answers are never searched. Before preparing the proposal, the server rechecks current task authorization and verifies that the task belongs to the lifecycle covered by the configured action.

Sara reviews the named request, decision, required inputs and current task state in the proposal, then confirms explicitly. If confirmation returns APP_CHAT_NOT_SENT / NOT_EXECUTED, the server reports that no dispatch occurred and the existing proposal remains confirmable; she reviews the target and values before trying again. If the server returns APP_CHAT_OUTCOME_UNKNOWN / OUTCOME_UNKNOWN, the request may already have been dispatched. The UI blocks another confirmation and offers Check status; Sara checks the task/action receipt or ordinary task page before taking any further action. A request refusal or unavailable target remains a neutral refusal, not a retry invitation.

For a confirmed task decision or comment, the server creates a human-readable receipt label, for example Approved: Huda Nasser · Approve leave request or Comment added: Huda Nasser · Approve leave request. The UI suppresses action IDs, proposal IDs, task IDs and machine-shaped labels from that receipt. Treat it as a readable summary; confirm the durable task state or authoritative receipt for the business result.

Live progress, proposal card and receipt (SCRUM-5106/5107)

While a turn is in flight, the panel polls the App Chat progress route for its clientRequestId. The response is a step name or null; it contains no record or task payload. The client maps known steps to reader text such as Finding the task…, Checking allowed decisions…, Preparing the action… and Reading records…. Unknown or absent steps use the ordinary Thinking… cue. A progress label describes work in progress; it is not a result, authorization decision or approval. The server sets those steps as it begins the corresponding task lookup, decision resolution, proposal creation, record read or answer. The task-resolution path may use the previous answer and the signed-in person's open tasks to resolve an eligible follow-up without asking the model to choose the target again.

An eligible greeting, acknowledgement or goodbye can take a shorter path: the server stores a simple answer without record reads, tool calls or a provider/model call. This applies only when the entire message is recognized as small talk by the current source: “Hello there” is a greeting, while “Hello there, what is the status of LR-1005?” asks for record information and follows the normal evidence path. It is a latency behavior, not evidence of a record or task lookup.

When the server resolves one configured task action, the proposal presentation may include the task's disclosable subject/details, a linked record only when the linkage is established, an optional comment field accepted by that decision, and the action's own submit label. Values come from the permitted task summary and access-checked record read; machine IDs are not rendered. The card lets the person inspect the named record through its ordinary access check. A task-related answer can therefore identify a specific decision without claiming that all tasks or records were searched. If the server cannot determine one safe target, the person must clarify or select the target as shown; the model does not invent a task ID.

Before confirmation, the assistant message above the card says Check the details, then confirm below; the card itself shows the action details and its own button, such as Approve leave. While the confirmation request is running, Cancel is hidden because the action may already be executing. On a confirmed result, the pending prompt is removed and a success receipt displays the action outcome, the acting person and server time; where a linked record is available, the receipt offers Open with current access checked again. The receipt is a presentation of the reported result, not a substitute for the durable task state. An uncertain result uses the existing status-reconciliation path; do not repeat confirmation merely because a response was interrupted.

Short refinements and task-completion presentation

After an answer that cited records, a short follow-up of up to three words may refine the immediately preceding record question (for example, “Sami” after “Show me Nasser's leave request”). This applies even when that answer listed several records as bullets. The server accepts the interpretation only when the phrase matches a whole word or phrase in a text field that is both readable and AI-disclosable in a cited, App Shell-bound record source. It runs the lookup under the current actor and field policy; the match is not restricted to the exact record IDs named in the answer and may come from another row in that same source. If the bounded eligible-source lookup returns no match, the message is not treated as a refinement. Greetings, acknowledgements and commands such as “My tasks” are excluded. A short name is a filter hint, not evidence that the result is unique or permission to search a different source. See AppChatFollowUps and the access-checked matcher in DefaultAppChatService.

For example, a cited list may contain Huda Nasser and Sami Nasser. If the user replies “Sami,” the server may refine the previous question and answer from currently authorized results in that cited source. The answer still needs its own evidence and citations; the name alone does not establish a unique row. “Perfect” and “My tasks” are not refinements: the former is an acknowledgement and the latter is a new command.

A back-referencing task command such as “Approve it” skips the unrelated five-row record listing in the conservative path; otherwise its cap could produce a misleading Partial coverage notice for an answer that did not need that listing. Genuine partial task listings and unavailable source reads retain their partial/unavailable status. This rule does not make an incomplete task inbox complete and does not prove that the assistant searched all workspace records.

When a task-completion proposal is confirmed or accepted, the App Chat task panel removes that task from the open list and decrements the open count immediately. A stale in-flight listing is filtered so it cannot bring the completed task back as a disabled card or a retry action. This is presentation of the confirmed/accepted result, not a substitute for the task's durable state. The receipt uses a readable outcome and can append the linked record's AI-disclosable business key (for example, Approved: Huda Nasser · LR-1005); machine-shaped case/action labels are suppressed. See AppChatPanel and its AppChatLaneR5 regression tests.

Draft an action, do not execute it

The user asks: “Prepare an approval for request LR-017.” The model may use get_record or search_records to identify an authorized record and propose_action to prepare a configured draft. The service validates the action's target source or task inbox and drops input names the action did not declare. Repeating an identical draft request in the same turn reuses the original proposal rather than creating a second proposal. The resulting proposal is shown for review. The user must check the precise action, target, revision and required fields, then explicitly confirm. A model response or tool call alone is not approval.

When the server has resolved exactly one task proposal, it composes the assistant message from that proposal without requesting a provider-generated final answer for it. Example: “Approve leave” is ready for Huda Nasser (LR-1005). Check the details, then confirm below. The subject is taken from a disclosable task summary when available, and the linked record key is included only when the permitted lookup supplies one. A generic action-only sentence is used when no safe subject or key is available. Before returning the answer, the service strips standalone or labeled machine-shaped UUIDs used as internal task/case/proposal/record identifiers from assistant text while preserving disclosed business values; for example, LR-1005 remains when it is a cited, disclosed key. This controls wording consistency and identifier exposure. It does not confirm the action: only the explicit proposal confirmation path can dispatch it.

For a task comment, Inflow binds the dispatch marker and comment row to one stable operation identity derived from the workspace, App Shell, publication version, actor, proposal, action and task. Replaying that same operation after a comment committed but its App Chat receipt did not returns the existing comment row rather than appending a duplicate, provided the actor still passes current task authorization and the task remains bound to the same App Shell action. If access or target binding changed, treat the task as unavailable; do not retry the old operation. Reusing the identity with different comment content raises a conflict that is surfaced as Outcome not confirmed (OUTCOME_UNKNOWN), not as a clean Not sent refusal; inspect the task and status before taking another action. If the prior dispatch ledger is incomplete or unavailable, the outcome also remains unknown and the user checks the task before proceeding. A new comment or changed target is not a safe retry. Verify the authoritative task/action receipt or business state after confirmation.

Source map

This is a source-based technical explanation. It is not runtime verification of a provider connection or a published App Shell.

Try “document generation”, “integrations” or “first form”.