---
name: prix-builder
description: "Build and publish AI agents on Prix (prix.dev) — the Agent Cloud. Triggers on: 'build an agent', 'publish an agent', 'Prix agent', 'Rush agent', 'agent.yaml', 'rush publish', or when the user wants to ship an agent to the Rush registry."
author: prix
version: 1.0.0
homepage: https://prix.dev
---

# Prix Agent Builder

Build AI agents as YAML files. Test locally. Publish to the Rush registry with one command.

## Core Concepts

- **Agent** — a YAML-defined AI app with tools, memory, prompt, and UI. Runs on Rush.
- **Registry** — prix.dev/docs/publishing. Signed containers, public distribution.
- **Harness** — the Go runtime that executes agents (`rush run`, `rush serve`, `rush deploy`).
- **Skills** — bundles of tools + knowledge an agent uses. Defined alongside the agent.
- **Subagents** — agents inside agents. Delegate tasks via multi-agent orchestration.

## The Only CLI You Need

```bash
# Install (one line, no package manager)
curl -fsSL https://cdn.getrush.ai/install.sh | bash
```

One binary does everything:

| Command | What it does |
|---|---|
| `rush init <name>` | Scaffold a new agent (agent.yaml + prompt.yaml) |
| `rush run ./path --prompt "..."` | Run locally with full harness |
| `rush build ./path` | Validate + LLM-powered quality check |
| `rush publish ./path` | Sign + upload to registry |
| `rush serve ./path` | Expose as local A2A endpoint |
| `rush deploy <handle>/<name>` | Deploy as hosted A2A endpoint |
| `rush install <slug>` | Install someone else's agent |

## Agent File Layout

```
my-agent/
  agent.yaml        # Config: name, tools, models, metadata
  prompt.yaml       # Prompt: identity, workflow, constraints
  ux.yaml           # (Optional) UI components, artifact actions
  CHANGELOG.md      # Required for publishing — one entry per version
  assets/           # Required for publishing — logo, cover, gallery
    logo.png        # min 256x256 square
    cover.png       # store hero
    gallery/*.png   # screenshots or short videos
  skills/           # (Optional) bundled skills
    my-skill/
      SKILL.md
```

## Minimal agent.yaml

```yaml
name: my-researcher
title: My Researcher
subtitle: Quick answers with sources
description: Research agent that searches the web and delivers concise, cited answers.
version: 1.0.0
developer: YourName
category: Research

models:
  anthropic/claude-sonnet-4:
    provider: openrouter

tools:
  - name: web_search
  - name: web_fetch
  - name: artifacts
```

## Minimal prompt.yaml

```yaml
version: 2
role: user
sections:
  - name: identity
    content: |
      You are a research assistant. You find accurate, well-sourced
      answers. You don't guess — you search, verify, and cite.
  - name: workflow
    content: |
      1. Understand the user's question.
      2. Search the web for relevant sources.
      3. Read and verify the most promising ones.
      4. Write a concise answer with inline citations.
      5. Save substantial answers as artifacts.
  - name: constraints
    content: |
      - Always cite sources with URLs.
      - If you can't find a reliable answer, say so.
      - Prefer recent sources over older ones.
```

## Workflow

```bash
# 1. Scaffold
rush init my-researcher && cd my-researcher

# 2. Iterate locally — sub-second feedback loop
rush run ./. --prompt "What is quantum computing?" --non-interactive
rush run ./. --prompt "..." --verbose --stream-events   # see tool calls live

# 3. Validate (auto-formats YAML, runs LLM-powered quality review)
rush build ./.

# 4. Enable developer mode once (required to publish)
rush dev enable

# 5. Publish to the registry
rush publish ./.

# 6. (Optional) expose as an A2A endpoint
rush serve ./.                        # local, prints bearer token
rush deploy <handle>/my-researcher    # hosted, public HTTPS URL
```

## Common Tool Categories

| Category | Examples |
|---|---|
| Web | `web_search`, `web_fetch` |
| Storage | `artifacts`, `memory` |
| HTTP | `http_get`, `http_post` (via skills) |
| Shell | `bash` |
| Media | `audio_transcribe`, `camera_capture` |
| UI | `ui_components` (generative UI) |

Full list: https://prix.dev/docs/tools

## Hard Rules (pitfalls the validator catches)

- `ui_components:` NOT `ui:` — the `ui:` key is silently ignored.
- `ui_components` MUST be a map keyed by component name. NOT an array.
- `artifact_actions` MUST be an array; each action needs a `matches` field.
- Actions with a `tool:` field run sync in the harness. Without it, they dispatch to an agent.
- CHANGELOG.md MUST have an entry matching the current `version:` before `rush publish` will succeed.
- NEVER pass `--skip-quality`, `--skip-lock`, or `--force` to `rush build`. These skip safety checks.

## Multi-Agent (delegation)

Subagents live in `agents/<parent>/subagents/<child>/`. Parent calls a child via the `delegate` tool:

```bash
rush run ./my-orchestrator --sub researcher --prompt "Research X"
```

See https://prix.dev/docs/multi-agent for orchestrator patterns.

## Skills (bundle tools + knowledge)

Inside an agent, constrain what it can do and package domain knowledge:

```
agents/my-agent/skills/test-helper/
  SKILL.md                 # description + allowed tools
  scripts/verify-tools.sh  # optional verification
```

See https://prix.dev/docs/skills.

## Debugging

```bash
# Stream every event, tool call, token usage
rush run ./. --prompt "..." --verbose --stream-events --non-interactive

# Tail the runtime logs
tail -f ~/.rush/logs/*.log

# Inspect a session after the fact
ls ~/.rush/sessions/<id>/
cat ~/.rush/sessions/<id>/messages.jsonl | jq
```

## When Asked to Build an Agent

1. **Clarify the job.** What does the agent do? Who uses it? What tools does it need?
2. **Scaffold** with `rush init`.
3. **Write `prompt.yaml` first.** Identity → workflow → constraints. Keep it mindset-driven, not rigid rules.
4. **Pick tools.** Start with the minimum. Add as needed.
5. **Run locally** after every meaningful change. Use `--verbose --stream-events`.
6. **Build.** Let the quality review catch prompt issues.
7. **Prepare assets** before publish: logo, cover, gallery, CHANGELOG entry.
8. **Publish** with `rush publish`. Users can now `rush install <your-handle>/<name>`.

## Reference

- Quickstart: https://prix.dev/docs/quickstart
- Agent structure (all fields): https://prix.dev/docs/agent-structure
- Prompt design: https://prix.dev/docs/prompt-design
- Tools: https://prix.dev/docs/tools
- Skills: https://prix.dev/docs/skills
- Multi-agent: https://prix.dev/docs/multi-agent
- Publishing: https://prix.dev/docs/publishing
- Serve & deploy (A2A): https://prix.dev/docs/serve-deploy
- CLI reference: https://prix.dev/docs/cli-reference
- Developer mode: https://prix.dev/docs/developer-mode