awslabs / awslabs/cli-agent-orchestrator
Add optional friendly names for agent instances (display_name) independent of role/profile
- Dominant language
- Python
- Stars
- 1.3k
- Forks
- 267
- Avg merge
- 1d 23h
- Merged PRs (30d)
- 70
Description
## Problem
Currently, agents are identified only by technical IDs and profile names:
- **Session names**: auto-generated UUIDs (`cao-3a2f8c1b`)
- **Terminal IDs**: 8-char hex strings (`a1f2c8d3`)
- **Agent profile**: role template (`developer`, `reviewer`, `code_supervisor`)
This makes it hard for teams to coordinate when multiple instances of the same role are active. A supervisor or human operator can't easily say: *"Toast is working on the API refactor, Mapple is reviewing PRs"* — they're left with cryptic GUIDs.
**Key insight**: Roles (permissions) and instance names (identity) should be orthogonal. A `developer` role is generic and reusable; a **display name** is a user-facing label for a specific worker in a session.
## Solution
Add an optional **`display_name`** field to agent instances, separate from `agent_profile` (the role template) and technical IDs. This enables natural team coordination while keeping roles generic.
### Design
1. **Terminal model** — add optional `display_name: Optional[str]` field
- Stores the user-friendly name for an agent instance
- Separate from `agent_profile` (which names the role template)
- Separate from `id` (technical UUID)
2. **Agent profile YAML** — optional `displayName` field in frontmatter
```markdown
---
name: developer
displayName: Toast # Optional; used when spawning this profile
role: developer
---
```
3. **CLI flags** — `cao launch --display-name ` and future `--agents-with-names`
```bash
cao launch --agents code_supervisor --display-name "Mayor"
```
4. **MCP orchestration tools** — `handoff()` and `assign()` accept optional `display_name` parameter
```python
# In supervisor agent:
assign(agent_profile="developer", display_name="Toast")
handoff(agent_profile="reviewer", display_name="Mapple")
```
5. **Session creation API** — propagate display names to worker terminals
```python
POST /sessions/{session_name}/terminals?provider=...&agent_profile=...&display_name=Toast
```
6. **UI components** — show friendly name prominently, fallback to profile name
- Dashboard: **Toast** (developer) instead of `developer-a2f3`
- Terminal detail: display name in header
- MCP Apps fleet view: agent status cards show display name
7. **CLI session commands** — accept terminal reference by display name (fallback to ID)
```bash
cao session send cao-my-session "message" --target Toast
```
### Backwards Compatibility
- Entirely optional; omit `display_name` and system works as-is
- Defaults to `agent_profile` name in UI if not set
- No breaking changes to existing APIs or profiles
- Existing sessions/terminals without a display_name continue to work
### Use Cases
- **Gas Town naming** — *Mayor (supervisor), Toast (developer), Mapple (reviewer), Chef (test engineer)*
- **Team coordination** — *"Toast finished core API, passing to Mapple for review"*
- **Supervisor context** — Supervisor can see and reason about named workers: *"Available workers: Toast (developer), Mapple (reviewer)"*
- **Session tracking** — Humans can quickly identify who's working on what without reading hex IDs
- **Cross-provider workflows** — Pin friendly names to specific provider+profile combos
## Implementation Scope
### Phase 1: Core Model & Storage
- [ ] Add `display_name: Optional[str]` field to `Terminal` model
- [ ] Extend database schema: add `display_name VARCHAR(64)` column to `terminals` table (with migration if using Alembic)
- [ ] Update `terminal_service.create_terminal()` to accept and store `display_name` parameter
### Phase 2: Input Surfaces
- [ ] Add `--display-name` flag to `cao launch` CLI
- [ ] Add optional `displayName` field to agent profile YAML frontmatter (docs + schema validation)
- [ ] Update MCP server tools (`handoff`, `assign`) to accept optional `display_name` parameter
- [ ] Update REST API `POST /sessions/{session_name}/terminals` to accept `display_name` query param
### Phase 3: UI & Output
- [ ] Update `AgentStatus` component to render `display_name` (with fallback to `agent_profile`)
- [ ] Update terminal list views to show friendly names
- [ ] Update MCP Apps fleet dashboard to display names
- [ ] Update CLI session management output to show display names
### Phase 4: Terminal Reference by Name
- [ ] Update CLI commands to accept `--target ` (with fallback to numeric ID)
- [ ] Update MCP tools to support terminal reference by display name
### Phase 5: Documentation & Tests
- [ ] Add examples to `docs/agent-profile.md` with `displayName` usage
- [ ] Update `docs/control-planes.md` to mention display names in session coordination
- [ ] Add unit tests for Terminal model + display_name handling
- [ ] Add integration tests for multi-agent scenarios with friendly names
## Files to Modify
- `src/cli_agent_orchestrator/models/terminal.py` — add field
- `src/cli_agent_orchestrator/services/terminal_service.py` — propagate through creation flow
- `src/cli_agent_orchestrator/api/main.py` — `/sessions/{name}/terminals` POST endpoint
- `src/cli_agent_orchestrator/mcp_server/server.py` — `handoff`/`assign` tool signatures
- `cao_mcp_apps/src/shared/AgentStatus.tsx` — display name in UI
- `cao_mcp_apps/src/dashboard/DashboardView.tsx` — terminal cards
- `web/src/components/AgentPanel.tsx` — web UI terminal listing
- `docs/agent-profile.md` — document `displayName` field
- `test/models/test_terminal.py` — model tests
- `test/services/test_terminal_service.py` — integration tests
## Example Workflow
```bash
# Operator launches supervisor with a friendly name
cao launch --agents code_supervisor --display-name "Mayor"
# Inside Mayor's chat:
# (Mayor is aware of worker names via MCP tools and system prompt injection)
assign(agent_profile="developer", display_name="Toast")
assign(agent_profile="reviewer", display_name="Mapple")
# Supervisor output:
# "Assigned Toast to implement auth middleware (dev-a1f2)"
# "Assigned Mapple to review the auth changes (rev-c8d3)"
# Operator can see in dashboard/CLI:
# Mayor (code_supervisor) — PROCESSING
# Toast (developer) — PROCESSING
# Mapple (reviewer) — IDLE
```
## Related Discussion
This proposal keeps roles (permissions) generic and orthogonal from instance names. It aligns with CAO's design principle: a supervisor-worker hierarchy where the supervisor understands task delegation, and names are a human-convenience layer on top.
**Note on naming**: "display_name" follows Pydantic/DB conventions. Alternative considered: `friendly_name`, `label`, `alias` — happy to align on preferred terminology.
Contributor guide
Assessment
This issue has not been assessed yet.