feat: context files for A2UI format, artifact conventions, researcher instructions
This commit is contained in:
Ken
@@ -0,0 +1,145 @@
|
||||
# A2UI Block Format
|
||||
|
||||
A2UI (AI-to-UI) lets you generate interactive UI controls directly in the chat. The
|
||||
frontend parses `a2ui` code blocks and renders them as Tabler components — filter
|
||||
toggles, sortable tables, card grids, and forms — without any page reload.
|
||||
|
||||
## How to Generate
|
||||
|
||||
Wrap a JSON object in a fenced code block with the language tag `a2ui`:
|
||||
|
||||
````
|
||||
```a2ui
|
||||
{ "type": "...", ... }
|
||||
```
|
||||
````
|
||||
|
||||
The JSON must be a single object with a `type` field. The frontend selects the
|
||||
renderer based on `type` and passes the remaining fields as props.
|
||||
|
||||
---
|
||||
|
||||
## Block Types
|
||||
|
||||
### filters
|
||||
|
||||
Renders a row of toggle chips. Use for quick category or attribute filtering.
|
||||
|
||||
```a2ui
|
||||
{
|
||||
"type": "filters",
|
||||
"options": [
|
||||
{ "label": "Toyota", "active": true },
|
||||
{ "label": "Honda", "active": false },
|
||||
{ "label": "Hyundai", "active": false },
|
||||
{ "label": "Under $5K", "active": false }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `options` | array | List of filter chips |
|
||||
| `options[].label` | string | Display text for the chip |
|
||||
| `options[].active` | boolean | Whether the chip is pre-selected |
|
||||
|
||||
---
|
||||
|
||||
### table
|
||||
|
||||
Renders a sortable data table. Use for structured comparisons across multiple items.
|
||||
|
||||
```a2ui
|
||||
{
|
||||
"type": "table",
|
||||
"headers": ["Make/Model", "Year", "Price", "MPG", "Mileage"],
|
||||
"rows": [
|
||||
["Toyota Prius", "2019", "$8,500", "52 mpg", "61,000 mi"],
|
||||
["Honda Insight", "2018", "$9,200", "49 mpg", "55,000 mi"],
|
||||
["Hyundai Ioniq", "2019", "$8,900", "55 mpg", "48,000 mi"],
|
||||
["Toyota Camry Hybrid", "2017", "$7,800", "46 mpg", "72,000 mi"],
|
||||
["Ford Fusion Hybrid", "2018", "$7,200", "42 mpg", "68,000 mi"]
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `headers` | string[] | Column header labels |
|
||||
| `rows` | string[][] | Data rows; each row must match header count |
|
||||
|
||||
---
|
||||
|
||||
### cards
|
||||
|
||||
Renders a card grid. Use for item listings where each result deserves its own tile.
|
||||
|
||||
```a2ui
|
||||
{
|
||||
"type": "cards",
|
||||
"items": [
|
||||
{
|
||||
"title": "2019 Toyota Prius LE",
|
||||
"description": "61,000 miles · Hybrid · Clean title · Seattle, WA",
|
||||
"price": "$8,500",
|
||||
"url": "https://www.cargurus.com/Cars/listings/prius-example"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `items` | array | List of card objects |
|
||||
| `items[].title` | string | Card heading |
|
||||
| `items[].description` | string | Supporting detail text |
|
||||
| `items[].price` | string | Price label (formatted string, e.g. `"$8,500"`) |
|
||||
| `items[].url` | string | Link destination for the card action |
|
||||
|
||||
---
|
||||
|
||||
### form
|
||||
|
||||
Renders a data-collection form. Use when you need user input to refine a search or
|
||||
configure a follow-up action.
|
||||
|
||||
```a2ui
|
||||
{
|
||||
"type": "form",
|
||||
"fields": [
|
||||
{ "name": "max_price", "type": "number", "label": "Max Price ($)", "value": 10000 },
|
||||
{ "name": "radius", "type": "number", "label": "Search Radius (miles)", "value": 25 },
|
||||
{
|
||||
"name": "fuel_type",
|
||||
"type": "select",
|
||||
"label": "Fuel Type",
|
||||
"options": ["hybrid", "electric", "any"]
|
||||
}
|
||||
],
|
||||
"submitLabel": "Search"
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `fields` | array | Ordered list of form fields |
|
||||
| `fields[].name` | string | Field identifier (sent on submit) |
|
||||
| `fields[].type` | string | `"number"`, `"text"`, `"select"` |
|
||||
| `fields[].label` | string | Human-readable label |
|
||||
| `fields[].value` | any | Default value (for `number`/`text` fields) |
|
||||
| `fields[].options` | string[] | Choice list (for `select` fields) |
|
||||
| `submitLabel` | string | Text on the submit button |
|
||||
|
||||
---
|
||||
|
||||
## Rules
|
||||
|
||||
- **Always use the `a2ui` language tag.** Any other tag (e.g. `json`) will render as
|
||||
plain code; the frontend will not parse it.
|
||||
- **JSON must be a single object with a `type` field.** Arrays and multi-root
|
||||
documents are not supported.
|
||||
- **Generate A2UI when the user benefits from interactive controls.** Filter chips,
|
||||
sortable tables, card grids, and forms add real value when the user is comparing
|
||||
options or needs to refine results.
|
||||
- **Don't overuse.** Plain markdown lists and tables are fine for simple answers. Use
|
||||
A2UI only when interactivity meaningfully improves the experience.
|
||||
@@ -0,0 +1,84 @@
|
||||
# Artifact Conventions
|
||||
|
||||
Artifacts are persistent markdown documents written to the filesystem. They appear
|
||||
in the right panel and survive across sessions, making them ideal for research worth
|
||||
saving: comparison guides, curated lists, reports, and actionable recommendations.
|
||||
|
||||
## Writing Pattern
|
||||
|
||||
Use the `write_file` tool to create artifacts:
|
||||
|
||||
```python
|
||||
write_file("artifacts/<session_id>/<name>.md", content)
|
||||
```
|
||||
|
||||
The `session_id` is available in your context. Use it to namespace files per session
|
||||
so multiple sessions don't overwrite each other's work.
|
||||
|
||||
## File Naming
|
||||
|
||||
- **Format**: kebab-case
|
||||
- **Extension**: `.md`
|
||||
- **Style**: Descriptive, specific — say what the file contains
|
||||
|
||||
```
|
||||
artifacts/<session_id>/hybrid-cars-under-10k-woodinville.md
|
||||
artifacts/<session_id>/project-management-tools-comparison.md
|
||||
artifacts/<session_id>/seattle-tokyo-flights-may-2025.md
|
||||
```
|
||||
|
||||
## Content Format
|
||||
|
||||
Each artifact should follow this structure:
|
||||
|
||||
1. **H1 title** — Clear, specific heading
|
||||
2. **Date and scope summary** — When the research was done and what it covers
|
||||
3. **Markdown tables** for side-by-side comparisons (price, features, ratings)
|
||||
4. **Bullet points** for recommendations, pros/cons, and key takeaways
|
||||
5. **Source URLs** — Link to each page or listing referenced
|
||||
6. **Closing section** — End with "Next Steps" or "Summary"
|
||||
|
||||
```markdown
|
||||
# Hybrid Cars Under $10K — Woodinville WA (May 2025)
|
||||
|
||||
**Researched:** May 2025 · **Scope:** CarGurus, Autotrader, Craigslist within 30 mi
|
||||
|
||||
## Comparison
|
||||
|
||||
| Make/Model | Year | Price | MPG | Mileage |
|
||||
|---|---|---|---|---|
|
||||
| Toyota Prius LE | 2019 | $8,500 | 52 | 61,000 mi |
|
||||
| Honda Insight EX | 2018 | $9,200 | 49 | 55,000 mi |
|
||||
|
||||
## Recommendations
|
||||
|
||||
- **Best value**: 2019 Prius LE — lowest price/mile ratio, clean title
|
||||
- **Best mileage**: Hyundai Ioniq at 55 mpg city/highway combined
|
||||
|
||||
## Sources
|
||||
|
||||
- https://www.cargurus.com/Cars/new/nl-Hybrid-d2335
|
||||
- https://www.autotrader.com/cars-for-sale/hybrid
|
||||
|
||||
## Next Steps
|
||||
|
||||
- Schedule test drives for the Prius and Ioniq listings
|
||||
- Verify CarFax reports before committing
|
||||
```
|
||||
|
||||
## When to Create an Artifact
|
||||
|
||||
Create an artifact when the output is:
|
||||
|
||||
- A **guide, report, or summary** the user will want to reference later
|
||||
- A **comparison table** across multiple options or products
|
||||
- **Actionable recommendations** with supporting evidence
|
||||
- Something **printable or shareable** with others
|
||||
|
||||
## When NOT to Create an Artifact
|
||||
|
||||
Skip artifact creation for:
|
||||
|
||||
- **Simple answers** — a one-sentence reply doesn't need a file
|
||||
- **Intermediate research steps** — notes you take while browsing, not the final output
|
||||
- **Status updates** — progress messages mid-task
|
||||
@@ -0,0 +1,24 @@
|
||||
# Research Workbench — Session Context
|
||||
|
||||
This session runs inside the **Research Workbench**. You have access to the
|
||||
following capabilities:
|
||||
|
||||
## Available Capabilities
|
||||
|
||||
**Browser** — Live Chromium browser controlled via `playwright-cli -s=research`.
|
||||
The browser is persistent across commands and visible to the user via VNC (noVNC
|
||||
panel). The user can take over at any time.
|
||||
|
||||
**Artifacts** — Persistent markdown documents written to `artifacts/<session_id>/`.
|
||||
They appear in the right panel and survive across sessions.
|
||||
|
||||
**A2UI** — Inline interactive controls (filter chips, tables, card grids, forms)
|
||||
rendered directly in chat via `a2ui` code blocks.
|
||||
|
||||
**Inline Visuals** — Rich visual output (charts, maps, comparison tables with color
|
||||
coding) rendered directly in chat via `visual` code blocks.
|
||||
|
||||
## Full Command Reference
|
||||
|
||||
For complete command syntax, workflow guidance, and best practices, see the
|
||||
researcher agent system prompt.
|
||||
Reference in New Issue
Block a user