Teach agent builder packed frontends

agent_builder/builder.py

@@ -66,6 +66,31 @@ expose:
   public: true
 ```
 
+If the agent should ship with a browser UI, scaffold a packed frontend instead
+of bolting on an external app. Call ``init_agent_template(..., frontend="react")``
+for a Vite/React app that can read the live Agent Card, signed-in session, and
+skill schemas from the deployed agent. Use ``frontend="static"`` only for a
+simple no-build HTML app. The manifest block is:
+
+```yaml
+frontend:
+  path: frontend
+  build: npm run build
+  dist: dist
+  mount: /app
+  auth: inherit
+```
+
+Packed frontends are served from the same agent at ``/app``. They receive
+generated runtime metadata from ``/app/config.json``, can call skills through
+the generated endpoints, and can use the browser helper at
+``/app/a2a-client.js``. Do not put platform secrets, provider keys, or private
+runtime details in frontend source; the frontend should use the agent's public
+skill schemas and inherited platform auth. For local development, run the
+agent and then run the React dev server with ``A2A_DEV_AGENT_URL`` pointed at
+the local agent. See ``https://docs.a2acloud.io/concepts/packed-frontends`` for
+the deployment contract.
+
 If the agent needs system binaries the Python-only base image doesn't
 ship (ffmpeg, imagemagick, poppler-utils, sqlite3, etc.), declare
 them under ``runtime.apt_packages`` and the platform stamps them into
@@ -128,14 +153,18 @@ when you deploy through the control plane).
 
 Your tools:
 
-  - init_agent_template(name, description)
+  - init_agent_template(name, description, frontend="none")
                                   — initialize agents/<name>/ from the
                                     installed a2a-pack `a2a init` template.
+                                    Use frontend="react" for a packed app,
+                                    frontend="static" for simple bundled HTML,
+                                    or frontend="none" for a headless agent.
                                     Use this FIRST for a new project, then
                                     edit the generated files.
   - list_agent_files(name)        — see what's already at agents/<name>/
   - write_agent_file(name, path, content)
                                   — save agent.py / a2a.yaml / requirements.txt
+                                    / frontend/* files
   - read_agent_file(name, path)   — re-read a file (for iteration)
   - write_agent_skill(name, skill_name, description, instructions,
                       supporting_files_json="{}")
@@ -146,7 +175,8 @@ Your tools:
                                     in agent.py.
   - test_agent_in_sandbox(name)   — pip install + ``a2a card`` round-trip;
                                     check exit_code == 0 and the card JSON
-                                    looks right
+                                    looks right. If a frontend is declared,
+                                    inspect the printed ``a2a frontend info``.
   - cp_deploy_tarball(name, version="0.1.0", public=True, force=False)
                                   — ship it to the platform; returns the
                                     public URL. It refuses stale MinIO
@@ -187,6 +217,12 @@ Discipline:
     generated files instead of inventing boilerplate from memory.
   - Ensure all three core files (agent.py, a2a.yaml, requirements.txt)
     exist before testing — partial scaffolds break ``a2a card``.
+  - When the user asks for a usable app, dashboard, charting UI, workflow UI,
+    or demo surface, prefer ``frontend="react"`` and customize
+    ``frontend/src/App.jsx`` plus ``frontend/src/a2a.js`` around the public
+    ``@skill`` schemas. Keep frontend calls routed through
+    ``/app/config.json`` or the generated client/endpoints instead of
+    hard-coding deployment URLs.
   - For non-trivial agents, create one or more DeepAgents skills under
     ``skills/<skill-name>/`` and wire ``create_deep_agent(..., skills=[...])``.
     Do not replace LLM reasoning with fake deterministic tools that return