Knowledge Graphs — Admin Dashboard

The Knowledge Graphs section of the admin dashboard lets you inspect deployed bundles, browse the entities inside them, and bind bundles to agents through the capability picker. In the MVP release, the UI is read-only for bundle content — mutations happen through brewctl kg apply (see the quickstart). Agent bindings are managed through the regular agent editor.

Open the sidebar and click Knowledge Graphs under the Resources group. You will see the list of bundles in your current tenant. Each row shows:

Bundle name — the identifier you set in manifest.yaml
Version — customer-defined version string
Entity types — how many schemas the bundle contains
Entities — total instances across all types
Updated — last apply timestamp

If you have not applied any bundles yet, the page shows an onboarding empty state with a link to the quickstart tutorial and a hint to use brewctl kg apply.

Bundle detail page

Click any bundle to drill in. The bundle detail page is organised into three sections:

Entity Schemas

A table of all schemas in the bundle, one row per entity type. Each row shows:

Entity type name (e.g. category)
Number of entities of this type
The x-id-field value (which field is the primary ID)
A summary of indexed fields (x-index properties)
An Inspect button → schema detail page

The Inspect drawer shows the raw JSON Schema document plus the parsed annotations (indexed fields, refs, derived fields) in a more readable layout.

Manifest

A collapsible JSON viewer showing the bundle’s manifest — the summary stored in kg_bundle.manifest. Read-only; use brewctl kg apply to update.

Stats

Quick numbers — entity types count, total entities, last apply timestamp, schema hashes per entity type. Useful for verifying that an apply landed as expected.

Schema detail page

From a bundle, click the schema Inspect button to see one entity type in detail. This page has four sections:

Schema JSON — the raw JSON Schema document with syntax highlighting
Indexed Fields — properties marked x-index: true, with their types and (if applicable) enum values. These are the filter parameters customers can pass to list_<entity_type>.
References — properties marked x-ref. Each reference is clickable; clicking navigates to the target entity type’s schema.
Auto-generated Tools — preview of the MCP tools the engine generates from this schema (list_<entity_type>, get_<entity_type>, optionally list_<entity_type>_ids). This is what bound agents will see.

Entities list

Click into a schema and choose Browse entities to see the actual entity instances. The page has two parts:

The filter panel is auto-generated from the schema’s x-index properties:

Enum properties → multi-select dropdown
Boolean properties → checkbox
String properties → text input with debounce
Number properties → min/max range inputs

Only x-index properties appear here. Non-indexed properties are returned in entity payloads but cannot be filtered on. Derived fields (x-derived: true) are excluded from filters by design (they are engine-computed, not customer-authored).

Entity table (main)

Paginated table — default 50 rows per page, up to 500. Columns:

Entity ID (x-id-field value)
The first 3-5 non-derived properties (preview)
An Inspect button → drawer with full JSON

In the inspect drawer, properties marked x-ref are rendered as clickable links — clicking navigates to the referenced entity. This is the easiest way to explore relationships visually.

Binding bundles to agents

Bundles do not become visible to agents until you bind them. To bind:

Navigate to Resources → Agents, click the agent you want to extend
Open the Capabilities tab in the agent editor
Click Add capability and choose Knowledge Graphs
In the config panel, select one or more bundles from the dropdown
Save the agent

The next chat session for this agent will see the auto-generated tools from the bound bundles. In-flight sessions continue with their previous tool list (hot reload is not supported in MVP — start a new session to see the new tools).

The agent editor also has a “Manage Knowledge Graphs” link in the capability config panel that takes you back to the bundles list.

Apply via brewctl (recommended)

The admin UI is read-only for bundle content because the source of truth for a Knowledge Graph is the YAML in your git repository (GitOps pattern). To deploy or update a bundle:

# Apply a local bundle directory to the engine
brewctl kg apply ./my-bundle \
  --endpoint http://localhost:18082 \
  --token $BREWCTL_TOKEN

# Show a diff before applying
brewctl kg diff ./my-bundle \
  --endpoint http://localhost:18082 \
  --token $BREWCTL_TOKEN

# Export the current bundle from the engine for review
brewctl kg pull --bundle my-bundle --out ./exported \
  --endpoint http://localhost:18082 \
  --token $BREWCTL_TOKEN

A successful apply takes effect immediately for new chat sessions. The bundle list in the admin UI reflects the new state on the next refresh.

Granular entity edits (advanced)

For ops teams that need to add or remove a single entity without re-importing the whole bundle, the engine exposes granular CRUD endpoints. These are not surfaced in the admin UI in the MVP, but they are available via REST:

# Add one entity
curl -X POST http://localhost:18082/api/v1/knowledge-graphs/my-bundle/entities/brand \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"code":"new-brand","name":"New Brand","category":"apparel","tier":"mid"}'

# Update one entity (replaces in place)
curl -X PUT http://localhost:18082/api/v1/knowledge-graphs/my-bundle/entities/brand/new-brand \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"code":"new-brand","name":"Updated","category":"apparel","tier":"premium"}'

# Delete one entity
curl -X DELETE http://localhost:18082/api/v1/knowledge-graphs/my-bundle/entities/brand/new-brand \
  -H "Authorization: Bearer $TOKEN"

Granular edits validate against the current schema and trigger the same quota / metering hooks as bulk applies. They are not, however, recorded in your git repository — for production deployments where the bundle should match git, prefer brewctl kg apply.

Limits and quotas

The admin UI surfaces tenant-level limits in the bundles header:

Bundles used / 20
Total entities used / quota (Cloud only; CE has no per-tenant limit)
Largest single bundle size / 10 MB

Approaching a limit displays a warning banner with a link to upgrade (Cloud) or trim the bundle (CE).

Troubleshooting

”Bundle apply rejected: tool_name_collision_in_tenant”

Two bundles in the same tenant generated the same MCP tool name. Common cause: both bundles have an entity_type: category schema, both produce list_category. Rename one entity type, or change x-tool-expose to omit list from one of them.

”Agent does not see Knowledge Graph tools after binding”

In-flight chat sessions cache the agent’s tool list at session start. Start a new chat session — the new tools appear immediately.

”Filter returns 0 results but the entity should match”

Filter parameters use JSONB containment (@>). Make sure your filter value matches the entity’s stored value exactly — "high" is not the same as "High". Enum values are case-sensitive.

”Cross-ref target not found”

The x-ref annotation validates at apply time. If you see this error, the entity references an ID that does not exist in the same bundle. Check spelling and case.