Skip to content
BlazorUI

AI

AiToolCallView

Bit.BlazorUI.AIFunctionCall

BitAiToolCallView shows a tool call as one card: what is being called, what it was given, how it is going and what came back. The arguments are shown as the model writes them, the progress a running tool reports as a bar, the result as text or a JSON tree, a failure as a compact error, and a call waiting for a human decision closes with a BitAiToolApproval. The card starts collapsed and opens by itself when something needs attention. A renderer registered for a tool replaces the card wherever that tool is called.

Notes

To use this component, you need to install the Bit.BlazorUI.AI(opens in a new tab) nuget package, as described in the Optional steps of the Getting started page.

BitAiChat and BitAiMessageList render a card for every tool call of a conversation; render one yourself to lay tool calls out your own way. The card listens to its call, so a call that changes - streamed in by a BitAiChatSession, or driven by your own code as on this page - redraws its own card and nothing else. An approval only takes effect through the Session waiting for it. The arguments and the result come from the model and the tool, so they are shown as text and as a JSON tree, never as markup. See the Tools, Tool approval, Custom tool UI and Parallel tools scenarios.

Usage

Every example is live. Open its code to see exactly what produced the component running underneath.

Basic

Hand it a Call (a BitAiToolCallPart). The header names the tool - the Title of its definition, else its name - and says how long the call took; it starts collapsed, and the header opens it on the arguments and the result. Under a BitAiOptionsProvider whose options turn CollapseToolCalls off, every card starts open.

Arguments
"city": "Oslo"}
Result
"city": "Oslo""degrees": -3"condition": "Snow""humidity": 81}

Tool definition

The header is drawn from the BitAiToolDefinition of the tool (its table is on the AiToolApproval page): its DisplayName - the Title, else the Name - and its Icon, a Fabric MDL2 icon name drawn in place of the default wrench. A call carries the definition as its Definition, which a session sets as it starts running the call; until then - and for a call no session runs, such as one a server ran - the card reads the definition registered for the tool (IBitAiToolRegistry). Below: a tool nobody defined (its raw name under the wrench), a call with a definition of its own that names an icon, and a call with no definition whose tool this site registers (get_weather, titled Weather, with a globe).

Lifecycle

A call moves through Streaming (the model is still writing the arguments, shown as they arrive), Pending, Running and Completed - see the BitAiToolCallStatus table. While it runs, the BitAiToolProgress a tool reports is a bar under the header, which sweeps while it has no Fraction; its Message names the bar for assistive technology and leads the body. Nothing on the page re-renders the card: it follows its call by itself, at most once per render interval. Here the page drives the call; in a conversation the session does.



Failure & cancellation

A call whose result failed (BitAiToolOutcome.Failure) is outlined in the error color and opens by itself, its result a compact BitAiErrorView - only as it moves into that status, so a card the reader closes again stays closed. A call the user declined is Rejected: outlined the same way, with the failure the session records for it as its result. A call that was running when the user stopped the turn is Cancelled: the header says so, without a duration, and the card goes back to the outline at rest, since nothing went wrong.

Arguments
"city": "Atlantis"}
Result

Approval

A call that waits for a human decision (AwaitingApproval) is outlined in the warning color, opens by itself and ends in a BitAiToolApproval: decline, always allow, or allow. Hand the card the Session that is waiting, and the decision goes to it: the turn stays paused until then. delete_records is declared Destructive (BitAiToolDefinition.Risk), so the default approval policy asks before every call and the allow button is drawn in the error role. Always allow is remembered by the policy: the next call runs without asking. While it waits, the header says so and the prompt asks the question; once it is answered, the prompt goes and the header takes the focus it had.



Custom renderer

A renderer registered for a tool (BitAiRendererRegistry.RegisterTool, see the tables below) replaces the card wherever that tool is called. It is drawn in the card's place - with no frame, header or approval of the card's own - inside a BitAiRendererBoundary, so a renderer that throws on a shape it did not expect is replaced by a notice rather than taking the page down. It is handed a BitAiToolCallContext: the call, its Message and the Session. This site registers a SearchResultCard for search_docs at startup, so the call below - run by a session, with the progress the tool reports - is drawn by it.



Disabled

Disabled turns the header and the approval buttons off: the card stays as it is and no decision can be made. An open card keeps its arguments and its result readable; a collapsed one stays collapsed.

Arguments
"[email protected]""[email protected]""[email protected]"]"subject": "Weekly summary"}
Send the summary to the 3 people on the thread?

Cascading parameters

BitParams with a BitAiToolCallViewParams sets the defaults of every card inside it - here a region whose cards are disabled and drawn with a style of their own. It is a default, not an override: a card keeps what it sets itself (the last one is enabled).

Arguments
"city": "Atlantis"}
Result

Style & Class

Style and Class land on the root, Styles and Classes on every part: the header, its icons, title and status, the progress bar and busy dots, the body with its sections, labels and raw text, and the approval prompt. The public --bit-AiToolCallView-* variables (see the CSS variables table) inherit, so setting them on :root or a container restyles every card under it; the outline of a status wins over the one at rest.


Arguments
"city": "Atlantis"}
Result

RTL

In right-to-left text the chevron points the other way and the card is laid out from the right. Its own words come from the BitAiStrings of the options in force - here a subclass of them, cascaded by a BitAiOptionsProvider.

ورودی‌ها
"city": "آتلانتیس"}
نتیجه

CSS variables

The public custom properties this component reads off its root, for what no parameter covers.

Every variable is read with a fallback and never declared by the component, so it inherits like any other custom property: set one on :root (or in a [bit-theme] block) to restyle every instance, on any ancestor to restyle the ones inside it, or on the Style of one instance to restyle it - and any instance nested inside it, which inherits the value too; a parameter changes one alone, as does the real CSS property on the instance's Style / Styles when that property does not inherit (opacity: 1 keeps one disabled instance undimmed without undimming a disabled one inside it), while an inherited one such as color or font-family also reaches the nested instances that do not set it themselves. Leave a variable unset and the component falls back to the theme token beside it.

BitAiToolCallView CSS variables

Name Default value Description
--bit-AiToolCallView-background var(--bit-clr-bg-sec) Surface of the card.
--bit-AiToolCallView-border-color var(--bit-clr-brd-sec) Outline of the card at rest, and the rules under its header and above its approval prompt. The outline of a running, failed or waiting call wins over it.
--bit-AiToolCallView-running-border-color var(--bit-clr-pri) Outline of the card of a call that is streaming its arguments or running.
--bit-AiToolCallView-failed-border-color var(--bit-clr-err) Outline of the card of a call that failed or was declined.
--bit-AiToolCallView-approval-border-color var(--bit-clr-wrn) Outline of the card of a call awaiting a decision.
--bit-AiToolCallView-radius var(--bit-shp-radius-surface) Corner radius of the card.
--bit-AiToolCallView-header-color var(--bit-clr-fg-sec) Text and icons of the header.
--bit-AiToolCallView-header-hover-color var(--bit-clr-fg-pri) Text and icons of the header under the pointer.
--bit-AiToolCallView-header-hover-background var(--bit-clr-bg-sec-hover) Surface of the header under the pointer.
--bit-AiToolCallView-body-background var(--bit-clr-bg-pri) Surface of the expanded body.
--bit-AiToolCallView-label-color var(--bit-clr-fg-ter) Labels of the arguments and the result sections.

API

Every parameter, public member, sub-class and enum this component exposes.

BitAiToolCallView parameters

Name Type Default value Description
Call BitAiToolCallPart The tool call to render (required): its tool, arguments, status, progress, result and approval. The card subscribes to the call and re-renders itself whenever it changes - at most once per BitAiUiOptions.RenderInterval - so nothing has to re-render it while the call streams or runs. Its Definition names the tool (Title, else the tool name) and picks the icon of the header (Icon) - until a session sets it, the definition registered for the tool does - and the Risk of the Definition decides how an approval prompt looks.
Classes BitAiToolCallViewClassStyles? null Custom CSS classes for different parts of the tool call view.
Message BitAiMessage? null The message the call belongs to. Only a custom tool renderer reads it (BitAiToolCallContext.Message); left unset, the renderer is handed an empty assistant message.
Session BitAiChatSession? null The session driving the conversation. The approval prompt of a call awaiting a decision hands the decision to it (BitAiChatSession.Approve), which is what lets the paused turn carry on; without one the decision is only recorded on the call. A custom tool renderer is handed it as well (BitAiToolCallContext.Session).
Styles BitAiToolCallViewClassStyles? null Custom CSS styles for different parts of the tool call view.

BitComponentBase parameters

Name Type Default value Description
AriaLabel string? null Gets or sets the accessible label for the component, used by assistive technologies.
Class string? null Gets or sets the CSS class name(s) to apply to the rendered element.
Dir BitDir? null Gets or sets the text directionality for the component's content.
Disabled bool false Gets or sets a value indicating whether the component is disabled and cannot respond to user interaction.
ForceAnimation bool false Gets or sets a value indicating whether the component's animations play at their full duration even when reduced motion is requested.
HtmlAttributes Dictionary<string, object> new Dictionary<string, object>() Captures additional HTML attributes to be applied to the rendered element, in addition to the component's parameters. An attribute written on the component wins over an entry of the same name.
Id string? null Gets or sets the unique identifier for the component's root element.
Style string? null Gets or sets the CSS style string to apply to the rendered element.
TabIndex string? null Gets or sets the tab order index for the component when navigating with the keyboard.
Visibility BitVisibility BitVisibility.Visible Gets or sets the visibility state (visible, hidden, or collapsed) of the component.

BitComponentBase public members

Name Type Default value Description
UniqueId Guid Guid.NewGuid() Gets the readonly unique identifier for the component's root element, assigned when the component instance is constructed.
RootElement ElementReference Gets the reference to the root HTML element associated with this component.

BitAiToolCallViewClassStyles properties

Name Type Default value Description
Root string? null Custom CSS classes/styles for the root element of the BitAiToolCallView.
Header string? null Custom CSS classes/styles for the header (the button that expands and collapses the card) of the BitAiToolCallView.
ExpanderIcon string? null Custom CSS classes/styles for the expander chevron of the BitAiToolCallView.
Icon string? null Custom CSS classes/styles for the tool icon of the BitAiToolCallView.
Title string? null Custom CSS classes/styles for the title of the BitAiToolCallView.
Status string? null Custom CSS classes/styles for the status (the busy dots, or the duration of a finished call) of the BitAiToolCallView.
Spinner BitLoadingClassStyles? null Custom CSS classes/styles for the busy dots (a BitBouncingDotsLoading) of a running call of the BitAiToolCallView.
Progress BitProgressClassStyles? null Custom CSS classes/styles for the progress bar (a BitProgress) of the BitAiToolCallView.
Body string? null Custom CSS classes/styles for the body of the BitAiToolCallView.
ProgressMessage string? null Custom CSS classes/styles for the progress message in the body of the BitAiToolCallView.
Section string? null Custom CSS classes/styles for each section (the arguments, the result) of the body of the BitAiToolCallView.
Label string? null Custom CSS classes/styles for the label (the heading) of each section of the BitAiToolCallView.
RawText string? null Custom CSS classes/styles for the raw text of the arguments (before they parse) or of a textual result of the BitAiToolCallView.
Approval BitAiToolApprovalClassStyles? null Custom CSS classes/styles for the approval prompt (a BitAiToolApproval) of the BitAiToolCallView.

BitAiToolCallPart properties

A tool call and everything that happens to it - streaming arguments, an approval decision, progress and finally a result - as one message part (Kind "tool-call"). A session creates and drives it from the events of its transport; a page or a test can drive one by hand with the methods below. Every change raises the part's Changed event, which is what the card listens to. Thread-safe: the arguments may stream in on the transport's thread while the card reads them.

Name Type Default value Description
BitAiToolCallPart(toolCallId, toolName, partId?) constructor Creates a call in the Streaming status, with no arguments yet. toolCallId is the provider's identifier of the call (a result is matched back to the call by it), toolName the tool being called; partId is generated when left out.
ToolCallId string The call identifier used by the provider.
ToolName string The tool being called, which is also what a custom tool renderer is registered against.
Definition BitAiToolDefinition? null The definition of the tool, resolved from the tool registry when the session starts running the call. The card is headed by its DisplayName and draws its Icon, and its Risk decides how the approval prompt looks. Until it is set, the card reads the definition registered for the tool with AddBitBlazorUIAIServices (IBitAiToolRegistry, see its table); a tool the host does not know is shown by its raw name, under the wrench.
Status BitAiToolCallStatus BitAiToolCallStatus.Streaming Where the call is in its lifecycle, which decides the heading, the outline and whether the card opens by itself.
IsStreaming bool true Whether the arguments are still streaming (Status is Streaming).
RawArguments string "" The raw JSON argument text received so far.
Arguments JsonElement? null The parsed arguments, available once CompleteArguments has been called.
DisplayArguments JsonElement? null The best view of the arguments there is: the parsed ones once complete, else a lenient parse of the partial JSON received so far - which is how the card shows city: "Os..." while the model is still writing. Recomputed at most once per change, and only when read.
Approval BitAiApprovalDecision BitAiApprovalDecision.Undecided The human decision on the call, when one was asked for.
ApprovalReason string? null Why the approval was asked for. The approval prompt shows it in place of its own question.
Progress BitAiToolProgress? null The latest progress the running tool reported, drawn as a bar under the header. Cleared when the result arrives.
Result BitAiToolOutcome? null The result, once the tool has produced one.
StartedAt DateTimeOffset? null When the call first moved to Running.
CompletedAt DateTimeOffset? null When the result was recorded.
Duration TimeSpan? null How long the call took: the Duration of its Result, else the time between StartedAt and CompletedAt. The header of a finished call shows it.
AppendArguments(delta) void Appends a fragment of the raw JSON arguments. An empty fragment is ignored.
CompleteArguments(arguments?) void Marks the arguments complete - the parsed value given, or a parse of the text received so far - and moves a Streaming call to Pending.
SetStatus(status) void Moves the call to a status. Moving it to Running records StartedAt.
SetApproval(decision) void Records a human decision: Rejected moves the call to Rejected, Approved and ApprovedAlways to Pending. A session records it through BitAiChatSession.Approve, which also resumes the turn waiting for it.
SetProgress(progress) void Records a progress report of the running tool. A tool reports through BitAiToolInvocation.Progress, which the session forwards here.
SetResult(outcome) void Records the result, clears the progress and moves the call to Completed or, for a failed outcome, Failed.
PartId string The identifier of the part (inherited from BitAiMessagePart, like the four members below): the partId given to the constructor, else a generated one. A good @key for the card.
Kind string "tool-call" The kind of the part (BitAiMessagePartKinds.ToolCall), which BitAiMessagePartView renders with this card.
Version int 0 Increments on every change, for a cheap ShouldRender of a view of the app's own.
Message BitAiMessage? null The message the call belongs to, once it has been added to one.
Changed event Action<BitAiMessagePart> Raised after every change of the call, synchronously on the thread that made it. The card subscribes to it, so it follows its call without the page re-rendering it.

BitAiToolProgress properties

One progress report of a running tool (a readonly record struct), sent through BitAiToolInvocation.Progress.

Name Type Default value Description
Fraction double? null How much is done, from 0 to 1 (clamped). Null when the tool cannot measure it, which the bar shows by sweeping.
Message string? null A short status line, such as the current sub-step. It is the accessible name of the bar and leads the body of an open card.

BitAiToolOutcome properties

The result of one tool call: the structured Value that goes back to the model and the optional Text the card shows instead of it. Created through its factory methods.

Name Type Default value Description
IsSuccess bool Whether the call succeeded.
Value JsonElement? null The structured result, sent back to the model. The card shows it as a JSON tree when there is no Text.
Text string? null A human-readable rendering of the result, which the card shows in place of the Value, as it was written.
Error BitAiError? null The failure, when IsSuccess is false. The card shows it as a compact BitAiErrorView.
Citations IReadOnlyList<BitAiCitation>? null The sources the tool consulted, merged into the citations of the message.
Duration TimeSpan? null How long the call took. The session fills it in when the tool does not.
Metadata IReadOnlyDictionary<string, object?>? null Values of the application's own, carried through to custom renderers.
Success(value, text?) BitAiToolOutcome A successful outcome carrying a JsonElement, and optionally the text to show for it.
Success<T>(value, typeInfo) BitAiToolOutcome A successful outcome serialized with the JsonTypeInfo<T> of the app's own JsonSerializerContext, which is safe to trim. An overload taking JsonSerializerOptions serializes by reflection instead.
FromText(text) BitAiToolOutcome A successful outcome carrying only text (sent to the model as a JSON string).
Failure(error) BitAiToolOutcome A failed outcome carrying a BitAiError; Failure(message) makes one of the Tool kind from a message.
GetDisplayText() string? The text to display for the outcome: its Text, else the message of its Error, else its Value (a string as it is, anything else as JSON).

IBitAiToolRegistry properties

The set of tools available to a conversation, found by the name the model calls them by (case does not matter). AddBitBlazorUIAIServices registers BitAiToolRegistry as a singleton, filled with the tools added through ai.AddTool(...) (BitAiTool.Create makes one); a session runs the tools it finds in it, and a card whose call carries no Definition yet reads the definition of its tool from it.

Name Type Default value Description
Tools IReadOnlyCollection<IBitAiTool> Every registered tool, each with its Definition.
Find(name) IBitAiTool? The tool registered under that name, or null - in which case a card with no Definition on its call shows the raw name of the tool under the wrench.
Register(tool) void Adds a tool, or replaces the one registered under its name - at runtime too, which is how an app enables a capability for some users or conversations only.
Unregister(name) bool Removes a tool; true when one was removed.

BitAiRendererRegistry properties

Where an app registers its own renderers, which the components resolve before their built-in views. A singleton: register at startup (AddBitBlazorUIAIServices(ai => ai.ConfigureRenderers(renderers => ...))) and treat the entries as fixed afterwards. These are its tool members; the part members are on the AiMessagePartView page.

Name Type Default value Description
RegisterTool(toolName, renderer) void Registers a BitAiToolCallRenderer for one tool, matched by the name the model calls it by (case does not matter). Every BitAiToolCallView of that tool renders it in place of its card, inside a BitAiRendererBoundary; a later registration replaces an earlier one.
RegisterTool<TComponent>(toolName) void Registers a component as the renderer of one tool. The component is handed the BitAiToolCallPart as a parameter named Call.
FindTool(toolName) BitAiToolCallRenderer? The renderer registered for a tool, or null when the built-in card draws it.

BitAiToolCallContext properties

What a custom tool renderer is handed (a sealed record).

Name Type Default value Description
Call BitAiToolCallPart The tool call, with its arguments, status, progress and result.
Message BitAiMessage The message the call belongs to - the card's Message, or an empty assistant message when it has none.
Session BitAiChatSession? null The session driving the conversation, when there is one - so a renderer of its own can approve, decline or retry as well as display.

BitAiToolCallRenderer properties

The delegate a custom tool renderer is: public delegate RenderFragment BitAiToolCallRenderer(BitAiToolCallContext context). It is called each time the card's parameters are set, and the markup it returns is rendered again on every change of the call - so read what the markup needs off the call as it renders, rather than when the delegate runs.

Name Type Default value Description
context BitAiToolCallContext The call and its surroundings.
(return value) RenderFragment The markup drawn in place of the card.

BitAiToolCallStatus enum

Name Value Description
Streaming 0 The model has named the tool and is still writing the arguments. The card is outlined as running and shows the busy dots.
Pending 1 The arguments are complete and the call has not started running.
AwaitingApproval 2 The call waits for a human to approve or decline it. The card is outlined in the warning color, opens by itself and shows the approval prompt.
Rejected 3 A human declined the call, so it will not run. The card is outlined in the error color.
Running 4 The tool is running. The card is outlined as running and shows the busy dots and the progress the tool reports.
Completed 5 The tool produced a result. The header shows how long it took.
Failed 6 The tool threw or returned a failure. The card is outlined in the error color and opens by itself.
Cancelled 7 The turn was stopped before the tool produced a result.

BitVisibility enum

Name Value Description
Visible 0 The content of the component is visible.
Hidden 1 The content of the component is hidden, but the space it takes on the page remains (visibility:hidden).
Collapsed 2 The component is hidden (display:none).

BitDir enum

Name Value Description
Ltr 0 Ltr (left to right) is to be used for languages that are written from the left to the right (like English).
Rtl 1 Rtl (right to left) is to be used for languages that are written from the right to the left (like Arabic).
Auto 2 Auto lets the user agent decide. It uses a basic algorithm as it parses the characters inside the element until it finds a character with a strong directionality, then applies that directionality to the whole element.

Feedback

Found a mistake, a gap, or something that could be clearer? Every page and every component is one click from its source.