The Agent and Sessions

How the Agent works inside a Project, what a Session and a turn are, how Tools are confirmed, and how to give it context.

The Agent is a model that works on your Project through Tools: it reads and edits Scenes, writes and runs scripts, starts solvers and reports Results. It runs inside the Project's own server process, so a turn keeps going if you reload the window.

Sessions and turns#

A Session is one conversation, scoped to one Project. The Projects list shows each Project's Sessions under it. Sessions are stored in the Project's .witwin/ folder.

A turn is one run of the Agent, from your message to its answer, with all the Tool calls in between. A Project runs one turn that may change files at a time, plus up to four read-only turns in other Sessions. While a turn runs, you can send another message to steer it, queue a follow-up, or stop it.

The Agent can split work into subagents: child Sessions that take one part of a task, run in the background if needed, and report back.

Tools and confirmation#

Every Tool call goes through the same permission check, whether the Agent or a Plugin makes it. Editing the Scene and Project files runs directly and can be undone. Running code, and anything destructive, asks for your confirmation first unless you allowed it for the Session. A Turn's file changes can be reverted together.

Plugins add their own Tools. A solver Plugin, for example, gives the Agent Tools to configure and run that solver.

Give the Agent context#

  • Add to Chat: right-click an object, a file, a Result or a selection of text and choose Add to Chat. It appears as a chip in the message box.
  • Attach files and images by dragging them into the message box.
  • Mention a Scene object by name; the Agent can look it up.

Models#

The Agent's model calls go through your WiTwin account. Pick a model in the message box; Auto chooses one per request. Usage is shown on the Usage page of your account.

Tips#

  • Ask for one change at a time when you want to review each edit.
  • Ask the Agent to plan first ("make a plan, then wait") for large changes.
  • Prefer Parameters for values you will tune; the Agent can create and bind them for you.