Knowledge Graphs

Knowledge Graphs store curated, typed entities—such as products, policies, locations, or codes—and expose structured retrieval tools to agents. Use them when an agent needs exact records and identifiers. Use Knowledge instead when the source material is narrative text that should be searched semantically.

Before you begin

A graph is deployed as a bundle. A bundle contains a manifest, JSON Schemas, and entities. Each schema defines an entity type, an ID field, indexed fields, references, and which tools the platform generates. An agent sees those generated tools only after its Knowledge Graphs capability is enabled and the bundle is selected.

Create a scoped API key or complete the coding-agent OAuth flow before using MCP, REST, or brewctl. On the management MCP surface, full-bundle replacement and bundle deletion require manage authority. The REST routes used by brewctl enforce their documented agents:write scope; their full imports are still destructive and must be reviewed accordingly.

Inspect a graph in Admin

Open Knowledge Graphs in the Admin sidebar. The page lists bundle name, version, entity-type count, total entity count, and last update.

1. Select a bundle to view its entity schemas and manifest.
2. Review each schema’s ID field, generated tools, and summary fields.
3. Choose Browse entities to inspect records.
4. Filter on fields marked x-index: true; filters are exact, typed comparisons.
5. Inspect a row to view the complete entity JSON.

The Admin views are read-only for graph content. Apply changes through MCP, REST, or brewctl, then refresh Admin to confirm the resulting version and counts.

Bind a graph to an agent

1. Open Agents and edit the target agent.
2. Add or select the Knowledge Graphs capability.
3. Select one or more bundles under Bound bundles.
4. Save the agent and start a new chat session.

For each exposed entity type, the agent receives list_<entity_type>, get_<entity_type>, and, when enabled by the schema, list_<entity_type>_ids. Existing sessions retain the tool catalog captured when the session started.

If the agent is managed declaratively, record the binding in its configuration too. A later configuration apply reconciles the declared state and can remove an MCP-only binding.

Manage graphs from a coding agent

SyntheticBrew provides nine Knowledge Graph management tools to authorized coding agents:

Tool	Purpose
admin_list_knowledge_graphs	List bundles and entity types.
admin_get_knowledge_graph_schema	Read a schema, ID field, and generated tools.
admin_list_knowledge_graph_entities	List and filter records.
admin_import_knowledge_graph	Atomically import a complete bundle.
admin_upsert_knowledge_graph_schema	Add or replace one entity schema.
admin_upsert_knowledge_graph_entity	Add or replace one record without changing the others.
admin_delete_knowledge_graph_entity	Delete one record.
admin_delete_knowledge_graph	Delete a bundle, its schemas, records, and generated agent tools.
admin_link_knowledge_graph	Enable the capability and bind a bundle to an agent.

A coding agent receives only the tools allowed by its approved access. Read and incremental setup operations work with provision authority. Destructive replacement or deletion requires manage authority.

Import replaces; it does not merge

Importing over an existing bundle removes every existing record that is absent from the new payload. admin_import_knowledge_graph therefore requires both replace_existing: true and manage authority when the bundle already exists. To add or change individual records safely, use admin_upsert_knowledge_graph_entity.

Import updates the schemas supplied in the payload but does not delete an older entity schema merely because that schema was omitted. To remove an entity type entirely, delete and recreate the bundle from a reviewed complete payload. After deleting a bundle, also remove its name from agent capability settings before the next agent edit or declarative apply.

Deleting an entity is idempotent. The result reports whether a record was actually deleted, so a repeated delete can succeed without falsely claiming that data changed.

Apply a bundle with brewctl

Keep the bundle directory in your own configuration repository, review its diff, and apply a pinned version:

brewctl kg diff ./my-bundle \
  --engine "$SYNTHETICBREW_URL" \
  --token "$SYNTHETICBREW_TOKEN"

brewctl kg apply ./my-bundle \
  --engine "$SYNTHETICBREW_URL" \
  --token "$SYNTHETICBREW_TOKEN"

brewctl kg pull --bundle my-bundle --out ./exported \
  --engine "$SYNTHETICBREW_URL" \
  --token "$SYNTHETICBREW_TOKEN"

kg apply has the same full-bundle replacement semantics as the REST import endpoint. Review the diff before applying to an existing graph and use a key authorized for the requested operation. kg pull currently reads at most 500 entities per entity type; use it for inspection or smaller bundles, not as the only backup for a larger graph.

Use the REST API

The REST surface supports bundle inspection, schema inspection, typed entity queries, batch reads, imports, incremental writes, and deletion:

GET    /api/v1/knowledge-graphs
GET    /api/v1/knowledge-graphs/{bundle}
GET    /api/v1/knowledge-graphs/{bundle}/schemas
GET    /api/v1/knowledge-graphs/{bundle}/schemas/{entity_type}
GET    /api/v1/knowledge-graphs/{bundle}/entities/{entity_type}
POST   /api/v1/knowledge-graphs/{bundle}/entities/{entity_type}/batch-get
GET    /api/v1/knowledge-graphs/{bundle}/entities/{entity_type}/{id}
POST   /api/v1/knowledge-graphs/{bundle}/import
PUT    /api/v1/knowledge-graphs/{bundle}/schemas/{entity_type}
POST   /api/v1/knowledge-graphs/{bundle}/entities/{entity_type}
PUT    /api/v1/knowledge-graphs/{bundle}/entities/{entity_type}/{id}
DELETE /api/v1/knowledge-graphs/{bundle}/entities/{entity_type}/{id}
DELETE /api/v1/knowledge-graphs/{bundle}

Equality filters are coerced according to the indexed schema field. For example, filter[active]=true compares a boolean and filter[score]=10 compares a number instead of comparing their string forms. Invalid values are rejected. Range and membership operators are available only for compatible indexed field types; consult the Knowledge Graph schema guide before exposing a filter to an agent.

Expected result

After an apply, Admin displays the updated manifest, schemas, and entity counts. After binding the graph and starting a new session, the agent’s tool catalog includes the generated tools for its selected bundles.

Operational cautions

• Treat full imports as destructive reconciliation. Prefer incremental entity upserts for small changes.
• Omitting an entity schema from an import does not remove that schema; delete and recreate the bundle when retiring an entity type.
• Avoid generated tool-name collisions between bundles in the same tenant.
• Keep entity IDs and reference values case-correct. SyntheticBrew confirms that an x-ref names an entity type in the bundle, but it does not verify each record’s reference value; validate those values in your bundle workflow when strict references are required.
• Filters operate only on indexed fields and use the schema’s declared type.
• Use external MCP services for rapidly changing operational data or graph algorithms such as shortest paths; Knowledge Graphs are optimized for curated typed catalogs.

Troubleshooting

The agent cannot see graph tools: confirm the bundle is selected in the capability, save the agent, and start a new session.

A filter returns no records: inspect the indexed field’s schema and send a value of the correct type and case.

An MCP import is refused: an existing bundle requires replace_existing: true, and destructive replacement requires manage authority. Use an incremental upsert if replacement was not intended. REST and brewctl imports use their REST authorization scopes and should still be treated as destructive full-bundle operations.

A declarative apply removed a binding: add the bundle to the agent’s declared capability configuration, then apply again.

Next steps

• Knowledge Graph quickstart
• Knowledge Graph concepts
• Knowledge Graph or Knowledge?
• API keys and coding-agent OAuth