Sessions
The Sessions screen lets you open a conversation between a user and an agent, read its messages and delete it. Portal path: /agents/sessions. Developers and tenant administrators use it to prepare a session for a run, to read what a channel exchanged with an agent and to clean old conversations. The screen is drawn by portal/src/screens/agents.tsx.
What the screen shows
- Sessions table, read with
GET /v1/sessions(50 rows per call, cursor paging). Columns: Title, Agent id, User id, Channel, Status, Created. - When the list is empty: No session, with the hint Open a session to talk to an agent. and the button New session.
- A click on a row, or the row menu View details, opens a side panel with the session read with
GET /v1/sessions/{session_id}. - New session opens a side panel with the fields Title, Agent id (required), Channel and Metadata (JSON, default
{}).
Actions
| Button or action | What it does | API call | Roles |
|---|---|---|---|
| Refresh (icon) | Reloads the list. | GET /v1/sessions | Any tenant member |
| New session | Creates the session for the agent; the agent is checked first. | POST /v1/sessions | tenant_admin, developer, agent |
| Row click or row menu View details | Opens the detail panel. | GET /v1/sessions/{session_id} | Any tenant member |
| Row menu Messages | Shows the messages of the session, in order, in a side panel. | GET /v1/sessions/{session_id}/messages | Any tenant member |
| Row menu Delete | Opens Confirm a destructive action; type the session id, then Confirm. | GET /v1/lineage/graph, then DELETE /v1/sessions/{session_id} | tenant_admin, developer, agent |
| Retry (error state) | Sends the failed read again. | Same call | Same roles |
Roles
The portal hides no button. In services/control-plane/src/eai/domains/agents/routes.py, create and delete check OPS_ROLES (tenant_admin, developer, agent, from services/control-plane/src/eai/domains/agents/kit.py); reading needs a tenant, and a user sees only the sessions they own, except tenant_admin, auditor and security_officer who see every session (PRIVILEGED in services/control-plane/src/eai/domains/agents/sessions.py). platform_admin passes every role check.
Typical tasks
Open a session, then run the agent in it
- Create the session. A session holds the messages of one conversation and is owned by you. Click New session, fill Agent id and a Title, then click Create. Expected result: the toast Created and a new row with the status of the session. If it fails:
agent_not_found(404) means the agent id is wrong. - Copy its id. The run form asks for it. Open the row with View details and copy
id. Expected result: you have the session id. If it fails: click Retry in the panel. - Start a run in the session. The run is attached to the session. In the Registry, open the agent, click Start run and paste the id in Session id. Expected result: the run starts and its contract shows the
session_id. If it fails:session_not_found(404) means the id is wrong or the session was deleted.
Read what a channel exchanged with an agent
- Find the session. Channel sessions carry the channel name. Read the Channel column. Expected result: you find the conversation. If it fails: the Channels screen lists the sessions of one channel with its Sessions action.
- Read the messages. Messages are kept in order with their role. In the row menu, click Messages. Expected result: the list of messages in JSON. If it fails:
session_not_found(404) means the session was deleted.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
agent_not_found (404) on Create | Agent id names no agent of the tenant. | Copy the id or the name from the Registry. |
session_not_found (404) | The session no longer exists, or it belongs to another user and you do not hold tenant_admin, auditor or security_officer. | Click Refresh, or ask the owner of the session. |
session_closed (409): "The session is closed or expired." | A message was added to a session that is no longer open or whose time to live passed. | Create a new session. |
forbidden (403) with required_roles | Your roles are not tenant_admin, developer or agent. | Ask a tenant administrator for one of these roles. |
| Invalid JSON under Metadata | The metadata is not valid JSON. | Fix the JSON, for example {}. |