CompanyOS Agent System Understanding

CompanyOS Agent System Understanding

Current State

The agent tooling now has a generic entity-discovery baseline:

• explore_modules returns a compact inventory of visible module identifiers so agents can discover modules without relying on exact user wording.
• inspect_entity reads a concrete entity by module identifier and real entity id, including requested non-scalar fields such as list fields and relation references.
• inspect_layout_json reads raw module layout JSON and returns derived markable layout targets for tabs, rows, columns, components, and fields.
• explore_module_relations exposes outgoing and incoming relation paths, including nested list paths and search_entities_filter hints for records that reference a known target.
• search_entities supports scalar filters and relation-id filters like <relation_field>.id = <target_id>.
• search_entities rejects bare relation filters before query compilation and returns a structured hint instead of allowing invalid SQL.
• The agent prompt now tells agents not to answer from the currently open SPA context when the user names a different target record, and not to answer from target metadata alone when related records may contain the requested answer.

These changes are deliberately generic. Brezel API core must not hardcode system-specific module or field identifiers from any concrete customer system.

Known Gap

The current flow still depends too much on the LLM choosing the right sequence:

1. Find the named target entity.
2. Explore relations for the target module.
3. Pick relevant incoming or outgoing relation paths.
4. Query related records via relation-id filters.
5. Inspect related records and nested fields.
6. Follow additional references when needed.

This is brittle for composed business objects where the user asks about what a record contains, but the answer is stored on records that reference the target entity.

Planned Tool

Add a higher-level related-content exploration tool, working name:

explore_related_entities

Proposed input:

• module_identifier
• entity_id
• optional intent
• optional limit

Proposed behavior:

• Use the runtime module schema and permissions, not raw .bake.json as LLM context.
• Traverse incoming and outgoing relation paths for the concrete entity.
• Return visible related entity candidates with module identifier, entity id, display name, relation path, and compact scalar fields.
• Rank candidates by structural relevance and optional intent text.
• Include next-step hints such as which entity and fields to inspect.

This should make the agent’s next action data-driven instead of relying on raw schema dumps or system-specific ontology.

Why Not Raw Bake Files First

Raw bakery files are useful for authoring and root-only debugging, but they should not be the primary runtime context for normal agent understanding:

• They can expose source that non-root users should not read.
• They are authoring format, not a compact runtime graph.
• They increase token load and still require the LLM to infer live entity relationships.
• They do not encode visibility and permissions for the current acting user.

The preferred direction is a normalized, permission-aware runtime graph API backed by modules, fields, relations, and live entities.