Assistant Organization: Metadata & Tags

Overview

As you build up more assistants and more call volume, it helps to have a consistent way to identify, label, and slice your data. This page covers how an assistant's name and description are used for identification, how to attach custom metadata and tags via observabilityPlan, and how to organize the widgets on a Boards dashboard once you have that data flowing in. For the core walkthrough of building Boards widgets, logs, and the Analytics API, see Observability: Boards, Logs & Analytics — this page is specifically about labeling assistants and organizing dashboards, not the underlying Boards mechanics that page already covers.

Every assistant has a name and a description. Beyond being cosmetic, these fields serve a functional purpose:

• In the dashboard, the name is how you identify an assistant in lists, call logs, and Boards filters — a clear naming convention (e.g., including the environment or use case) makes it much easier to find the right assistant as your account grows.
• In tool-call payloads sent to your server, the assistant's name and description travel along with the request, which lets a single server endpoint shared across multiple assistants tell which assistant is calling and route or log accordingly without needing a separate lookup.

Sulus automatically attaches a baseline set of metadata fields to each call's observability trace, without any extra configuration:

• Call-level metadata
• Assistant-level metadata
• Any assistant override metadata applied for that specific call
• Any variable values used for that call

This default metadata is always present; custom metadata (below) is additive on top of it.

Beyond the default fields, you can attach your own custom key-value metadata to an assistant using its observabilityPlan.metadata field. Common use cases:

• "experiment": "v2.1" — track which prompt or configuration experiment a call belongs to
• "user_type": "beta_tester" — track a user segment
• "env": "production" — track which environment the call ran in

Custom metadata shows up alongside the default trace metadata described above, giving you a consistent place to look for both.

observabilityPlan.tags lets you attach searchable labels to a call, distinct from key-value metadata. Common use cases:

• "priority" — flag important runs you want to review later
• "onboarding", "a-b-test" — group related sessions together
• "voice-assistant" — filter down to a specific feature area

Because tags are simple labels rather than key-value pairs, they're best suited for filtering and grouping rather than storing structured values — use metadata for that instead.

Once your calls carry consistent metadata and tags, Boards gives you several ways to organize how that data is displayed:

• Drag and resize widgets — reposition a widget using its header handle, and resize it by dragging the bottom-right corner
• Delete or edit insights — remove a widget you no longer need, or edit its data source, metric, or filters without rebuilding it from scratch
• Global filters — a time-range and granularity filter at the top of the board applies to every widget at once, so you don't have to configure the time window widget by widget
• Fullscreen mode — expand the board to fill the screen, useful for a shared status display or a review meeting

• Lead with your top metrics — place the 1–2 numbers you check most often (e.g., total calls, average cost) at the top of the board as Text widgets
• Group related metrics together — keep, for example, cost-related widgets near each other and call-outcome widgets near each other, rather than interleaving unrelated metrics
• Keep widget sizing consistent — a common pattern is KPI Text widgets at 1–2 grid columns wide and charts at 3–4 columns wide, so the board reads cleanly at a glance
• Start small — 3–5 key metrics on a first board is usually more useful than a board that tries to show everything at once; add more widgets once you know which ones you actually check regularly

In summary: name and description identify an assistant in the dashboard and in your own server's tool-call payloads; default and custom observabilityPlan metadata and tags give you structured and searchable labels on top of that; and thoughtful widget organization on Boards turns that labeled data into a dashboard people actually use.