# tool_v0

A RocketRide tool node that exposes Vercel's v0 generative UI API to an AI agent.

## What it does

Lets an agent generate React + Tailwind CSS UI components from natural-language
prompts. The agent describes the desired component with `generate_ui` and receives
production-ready code, the full set of generated files, and a live preview URL. It can
then iterate with `refine_ui`, sending follow-up instructions to the same v0 chat.

Talks to the **v0 Platform API** (`https://api.v0.dev/v1/chats`) over plain HTTPS using
**requests**, no Vercel SDK is required. Chats are stateful **server-side**: each
generation returns a `chat_id`, and refinements reuse it, so the agent never has to
replay prior context.

Requests use a 120-second timeout (generation can take a while) and are retried via the
shared `post_with_retry` helper. API and transport failures raise rather than returning
error payloads, the agent framework converts the exception into a structured error for
the model. Response bodies are never logged, even on malformed responses.

This node is marked **experimental**: v0 API availability and behavior may change.

---

## Configuration


| Field | Type | Description |
|---|---|---|
| `apikey` | string | Default empty. Vercel v0 API key |


The node fails at pipeline start if `apikey` is empty, and config validation warns
about a missing key before that.

This node has no lanes: it is invoke-only and is called exclusively through its agent
tools.

---

## Available tools

### `generate_ui`

Generate a React UI component from a natural-language description.


| Tool | Description |
|---|---|---|
| `generate_ui` | Generate a React UI component from a natural-language description. Provide a detailed prompt describing the desired UI and receive production-ready React + Tailwind CSS code, a live demo URL, and a chat_id for follow-up refinements via refine_ui. |
| `refine_ui` | Refine a previously generated UI component by sending follow-up instructions to an existing v0 chat. Requires the chat_id from a prior generate_ui call. The v0 chat is stateful server-side, so prior context need not be replayed. |


Returns:

| Output | Description |
|--------|-------------|
| `success` | `true` on success |
| `chat_id` | v0 chat ID, pass to `refine_ui` to iterate |
| `code` | Primary generated React component code (content of the first generated file) |
| `files` | All generated files as `{name, content}` objects |
| `demo_url` | Live preview URL for the generated UI |

### `refine_ui`

Refine a previously generated component by sending follow-up instructions to an
existing v0 chat.

| Input | Required | Description |
|-------|----------|-------------|
| `prompt` | yes | Follow-up instructions describing how to change the component. |
| `chat_id` | yes | The `chat_id` returned from a previous `generate_ui` or `refine_ui` call. |

Returns the same shape as `generate_ui`. If the v0 follow-up response omits the chat
id, the tool falls back to the `chat_id` it was given, so the value the agent holds
always stays valid for further refinements.

---

## Error behavior

- An empty `prompt` (or missing `chat_id` for `refine_ui`) raises a validation error
  before any API call is made.
- v0 Platform API errors (`{"error": ...}` payloads), non-JSON response bodies, and
  unexpected payload types raise a `RuntimeError` with a descriptive message.
- A generation that returns no files raises `v0 returned no files` rather than
  returning empty code.

---

## Authentication

Provide a Vercel v0 API key in the `apikey` field. The key is sent as a
`Authorization: Bearer <apikey>` header on every request and is cleared from memory
when the pipeline ends.

---

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `tool_v0.apikey` | `string` | **API Key**<br/>Vercel v0 API key | `""` |

## Dependencies

- `requests`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/tool_v0)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->