feat: add agent specs

specs/DESIGN.md

@@ -11,7 +11,8 @@ specs/designs/
 ├── 10-layout/         — overall UI designs
 ├── 11-models/         — model page designs
 ├── 12-tools/          — tool page designs
-└── 13-kbs/            — knowledge base page designs
+├── 13-kbs/            — knowledge base page designs
+└── 20-agents/         — agent page designs
 ```
 
 ---

specs/designs/20-agents/detail.md

@@ -0,0 +1,47 @@
+# Agent Detail Page
+
+## Overview
+
+Single agent detail view.
+
+Follows the layout of `specs/designs/10-layout/detail.md`, only the details are documented in this spec.
+
+## Page Name
+
+"{agent.name}" for title and breadcrumb
+
+## Page Header (always shown)
+
+```
+[Icon] Agent Name                       [status badge] [Edit] [⋮]
+```
+
+- Icon: agent icon
+- Agent name (primary)
+- Status badge (right, when `agent.status` is set)
+- Edit button: navigates to the edit page
+- ⋮ menu: includes Delete and a context action (`Test` for deployed agents, `Deploy` otherwise)
+
+## Config Panel
+
+Always shown.
+
+- model link
+- knowledge base links (or None)
+- tool links (or None)
+
+## System Prompt Panel
+
+Always shown. Renders `agent.systemPrompt` as plain text.
+
+## Deployment Panel
+
+Always shown. Shows deployment/runtime configuration.
+
+## Management Tabs
+
+Always shown.
+
+## Delete Confirmation Dialog
+
+Destructive confirmation. On success, returns to the agents list.

specs/designs/20-agents/domain.md

@@ -0,0 +1,31 @@
+# Agent Domain
+
+Agents are managed deployments.
+
+## Core Fields
+
+All agents share these core fields:
+
+- identity: id, name
+- presentation: icon, description, tags
+- behavior inputs: systemPrompt
+- references: model, tools, kbs
+- deployment: runtime
+- placement: stack
+
+## References
+
+Agent references include:
+
+- model: one language model reference
+- tools: zero or more tool references
+- kbs: zero or more knowledge base references
+
+## Runtime and Status
+
+- runtime is required
+- deployment status is optional
+
+## Agent Type
+
+- Agent is a single managed agent type (no mode-based union)

specs/designs/20-agents/form.md

@@ -0,0 +1,42 @@
+# Agent Form Page
+
+## Overview
+
+Shared `<AgentForm>` handles both create and edit.
+
+Follows the form layout in `specs/designs/10-layout/form.md`, only the details are documented in this spec.
+
+## Form Layout
+
+Basic Information → Config → Deployment
+
+## Panels
+
+### Basic Information
+
+Beyond the standard Icon + Name fields described in the layout spec:
+
+- **Icon**
+- **Name**
+- **Description**
+- **Tags**: optional list input
+
+### Config
+
+- **System Prompt**: textarea, 5 rows, placeholder `You are a helpful assistant...`
+- **Language Model** selector
+- **Knowledge Bases** selector
+- **Tools** selector
+
+### Deployment
+
+- Optional runtime settings
+
+## Validation
+
+- Name is required
+
+## Breadcrumb
+
+- Create: `Agents / [New Agent]`
+- Edit: `Agents / Edit [{agent.name}]`

specs/designs/20-agents/list.md

@@ -0,0 +1,73 @@
+# Agents List Page
+
+## Overview
+
+Card grid list of all agents.
+
+Follows the layout of `specs/designs/10-layout/list.md`, only the details are documented in this spec.
+
+## Page Name
+
+"Agents" for title and breadcrumb
+
+## Filters
+
+| Row  | Mode  | Values                             | Default | Extra                         |
+| ---- | ----- | ---------------------------------- | ------- | ----------------------------- |
+| Tags | Multi | the tags present across all agents | None    | row hidden when no tags exist |
+
+## Card Anatomy
+
+Card height is fixed at 256 px to leave room for the references footer.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ [icon]  Agent Name                              [status]    │
+│                                                             │
+│ Description, clamped to three lines…                        │
+│                                                             │
+│ [tag] [tag]                                                 │
+│                                                             │
+│ 🔧 tool-one, tool-two +3                                    │
+│ 📚 kb-one, kb-two                                     [▒▒]  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+The card is clickable as a whole and links to `/workloads/agents/[id]`.
+
+### Header
+
+- Small icon (size 36)
+- Agent name (line-clamp-2 if long)
+- Status badge (right, when set)
+
+### Body
+
+- Description, clamped to three lines
+
+### Tags
+
+- tag chips (only rendered when there are tags)
+
+### References Footer
+
+- Tools row: `WrenchIcon` + first 2 tool names joined with `, ` + `+N` for any overflow (only rendered when `tools.length > 0`)
+- KBs row: `DatabaseIcon` + first 2 KB names + `+N` overflow (only rendered when `kbs.length > 0`)
+
+## Empty States
+
+**No agents at all:**
+
+```
+BotIcon (muted)
+"No agents yet."
+[New Agent button]
+```
+
+**No match:**
+
+```
+BotIcon (muted)
+"No agents match your filters."
+[Clear filters link]
+```

specs/designs/20-agents/testing.md

@@ -0,0 +1,56 @@
+# Agent Test Page
+
+## Overview
+
+A sandbox for testing agent chat by selecting an agent and interacting through a streaming chat interface.
+
+## Route
+
+`/utilities/testing/agent`
+
+Optional query parameter `?agent=<agentId>` pre-selects the agent on load (used when navigating from an agent's detail page).
+
+## Page Name
+
+"Agent Chat" for title and breadcrumb
+
+## Page Layout
+
+```text
+[Agent Chat]                         (page title / breadcrumb)
+
+┌─────────────────────────────────────────────────────────────┐
+│  Agent                                                      │
+│  [Selected agent button]               [Select agent]       │
+└─────────────────────────────────────────────────────────────┘
+
+ (no selection)          (agent selected)
+┌──────────────┐         ┌──────────────────────────────────────┐
+│  Select an   │   →     │  Chat panel                           │
+│  agent above │         │                                       │
+└──────────────┘         └──────────────────────────────────────┘
+```
+
+## Agent Selector
+
+The selected agent is shown in the top selector button (icon + name). If no agent is selected, the page shows a placeholder prompt to select one.
+
+## Chat Panel
+
+Provides a chat thread for sending messages to the selected agent.
+
+Behavior:
+
+- Supports optional system prompt input.
+- User messages are appended to the thread.
+- Assistant responses stream incrementally.
+- Send switches to Stop while a request is in flight.
+- Clear session resets messages, system prompt, and errors.
+- Enter sends and Shift+Enter inserts a newline.
+- Request errors are shown inline.
+
+## API Behavior
+
+### `POST /api/workspaces/[workspaceId]/agents/[id]/test`
+
+Runs a streaming chat completion request for the selected agent and returns assistant output as an event stream. Non-success responses return an error payload.