Skip to main content
An entity is a structured object type the agent can create, read, and update as it works. Entities give an agent a durable model of the things it’s tracking, separate from the free-form chat. The most common built-in entities are WorkItem and WorkItemGroup, used to track work items across chats. Custom entities extend the same idea to whatever your domain cares about: opportunities, tickets, inspections, assets, customers. Use custom entities when the agent needs to track objects that have consistent fields, change state over time, and relate to one another: work you’d otherwise do in a spreadsheet or a side system.
Entity configuration is gated behind a feature flag. If you don’t see the Entities section in the agent editor, you’ll see the message “Entity configuration is not currently enabled. Contact your administrator to enable this feature.” Reach out to your Circuit contact to turn it on for your workspace.

​
The Entities section

Open the agent and find the Agent Entities card. The card’s description reads “Define the data entities this agent works with, including their properties and relationships.” Each entity shows as a card with its name and description in the header and a trash icon to remove it. Inside the card, entities are organized into two subsections: Properties (the fields an instance of this entity has) and Relationships (how it connects to other entities).

​
Adding an entity

1

Click + Add Entity

A new entity card opens with blank fields for Entity Name and Entity Description.
2

Name and describe the entity

  • Entity Name: a short, lowercase identifier. The placeholder in the field is entity_name. Use singular nouns: opportunity, inspection, asset. The name is how the agent refers to the entity when it creates or queries instances.
  • Entity Description: two sentences on what this entity represents and when the agent should create one. The placeholder reads “Describe this entity.” Agents use this description to decide whether a given piece of information belongs in this entity type or a different one, so be specific about scope.
3

Define properties

In the Properties subsection, click Add Property for each field the entity should have. For every property, set:
  • Name: the field identifier (for example, customer_name, status, due_date).
  • Type: choose from the dropdown: String, Integer, Float, Boolean, Datetime, or Array.
  • Description: one sentence on what goes in this field and what valid values look like. This is what the agent reads when deciding how to populate the property.
  • Required: check if the agent must set this when creating an instance.
Keep properties focused. If you find yourself adding more than eight or ten to a single entity, the entity is probably doing too much; consider splitting it or moving some fields into a related entity.
4

Define relationships (optional)

In the Relationships subsection, click Add Relationship for each connection this entity has to another. For each relationship:
  • Type: a verb or phrase describing the connection. The placeholder in the field is e.g., has_many. Examples: belongs_to, contains, blocks, reviewed_by.
  • Direction: Outgoing if this entity points at the target, Incoming if the target points at this entity.
  • Target Entity: the other entity this connects to. If you’ve already defined other entities, pick from the dropdown; otherwise enter the target name directly.
  • Description: one sentence on what the relationship means and when the agent should create it.
Relationships let the agent navigate between related records: given a project, find its open inspections; given an asset, find the customer that owns it. They’re also what makes aggregate questions (“how many open inspections does Acme have?”) answerable.
5

Save the agent

Changes to entity definitions save with the rest of the agent’s configuration. They take effect on the next chat message.

​
How the agent uses entities

Once entities are defined, the agent can create, read, update, and relate instances of them as a natural part of working with the user. A user might say:
Log a new inspection for asset A-1472. Start date today, technician Sam, outcome pending.
The agent creates an inspection record with those properties, linked via the belongs_to relationship to the asset A-1472, and confirms back. Later:
What inspections do we have open for Acme’s sites?
The agent navigates relationships (inspections → assets → customer) to answer, without you having to spell out the join. Entities don’t replace documents. Documents (product manuals, datasheets, contracts) still live in indexes and are searched as usual. Entities are for structured records that change over time and have a known shape.

​
Built-in entities

Every agent starts with two built-in entities: WorkItem and WorkItemGroup. These power the agent’s Work items panel and are managed by the agent on your behalf. You don’t need to define them in the Entities section; they’re always available. If you want the agent to track work and record structured data of your own (for example, link each work item to a custom opportunity entity), define the opportunity entity here and give it a relationship back to WorkItem or WorkItemGroup.

​
Tips

Model the real-world object, not the screen. An entity should represent something the business cares about (an opportunity, an asset, an inspection), not a UI artifact like “the current filter” or “the page the user is viewing.”
  • Use descriptions like prompts. The agent reads every description when deciding what to create and how to fill it in. Write them the way you’d instruct a new hire.
  • Name relationships from the subject’s perspective. inspection belongs_to asset reads more naturally than inspection asset or inspection relates_to asset.
  • Start small. Ship one entity, use it in real chats for a week, and add more only when you feel the gap. Custom entities are easy to add and hard to remove once the agent has created real instances.
  • Prefer few, well-described properties over many, thinly described ones. Agents perform best when each field’s purpose is clear.