agentuity add – Composable Agent Import

[nnance]

Feature Name
agentuity add – Composable Agent Import

---

1 . Problem statement

Developers currently build higher‑order (multi‑tool, multi‑skill) agents by manually copying reference code from agentuity/examples or other repos into their projects. The manual process is error‑prone, slows experimentation, and fractures best‑practice patterns that the Agentuity ecosystem is trying to standardise. The CLI already scaffolds new projects and agents — it should also be able to pull‑in vetted “building‑block” agents the way the shadcn/ui tool pulls React components. ([github.com]1)

---

2. Goals & success metrics

Goal	Metric
Import a foundational agent (code, tests, config) with one command	agentuity add search/web completes in ≤5 s on typical broadband
Zero follow‑up edits required for a default import	Project builds & agentuity dev starts without errors
Discoverability	agentuity add --list shows >90 % of agents published in agentuity/examples main branch
Extensibility	CLI accepts any public Git URL that contains a valid agent.yml manifest

---

3. User stories

• Dev: “As an LLM engineer, I want to compose a RAG agent and a Planner agent so that I can build a domain assistant in one afternoon.”
• Template author: “As a community contributor, I want my repo to be imported by others via agentuity add gh:user/my‑agents, without them changing one line.”
• CI/CD owner: “As a DevOps lead, I need deterministic imports so that production builds are reproducible.”

---

4. Solution overview

Area	Design
CLI syntax	agentuity add <source>[#<branch>] <path>/<agent‑name> [--as <local‑name>] [--no‑install]
Supported sources	1. agentuity/examples (default) 2. Any Git URL 3. Local filesystem path
Import flow	1. Fetch repo/branch 2. Parse agent.yml (schema already used by agent create) 3. Copy agents/<agent‑name> folder into the caller’s project, preserving relative imports 4. Merge/extend agentuity.toml and requirements.txt / package.json 5. Run dependency install unless --no‑install
Conflict handling	* If agents/<name> exists: prompt (--force to overwrite). * Dependency version clash: warn and write to IMPORT_CONFLICTS.md.
Discoverability	agentuity add --list [--search <term>] queries the examples repo’s /agents directory and prints name, brief description, tags. ([github.com]2)
Un‑add	agentuity remove <name> deletes files and rolls back dependency pins recorded in .agentuity-lock.json.
Telemetry (opt‑in)	Emit anonymised events: source, agent_name, duration_ms, success/fail_reason.

---

5. Foundational‑agent catalog

Below agents are delivered in examples and should be first‑class import targets.

Agent	Purpose	Typical higher‑order use
memory/vector‑store	Embeds & stores conversation or doc chunks; supports semantic recall	All RAG and long‑context assistants
retriever/web‑search	Queries Bing/Brave API, extracts, cleans HTML	Up‑to‑date knowledge lookup
summariser/document	Maps/reduces large text into tldr + key points	Meeting‑minutes bot; inbox‑zero bot
planner/task‑decompose	Creates stepwise execution plans from a high‑level goal	Autonomous multi‑step agents
executor/python	Runs arbitrary trusted Python in a sandbox and streams stdout	Data‑analysis or code‑generation agents
classifier/intent	Zero‑shot or few‑shot classification of user intents	Routing user queries to sub‑agents
translator/lang‑detect	Detects and translates between 30+ languages	Multilingual concierge agents
notifier/email‑send	Sends SMTP or SendGrid mail with templating	Alerting, report delivery
calendar/ical	Reads & writes iCal/Google Calendar events	Scheduling assistants
monitor/healthcheck	Pings endpoints & reports latency/uptime	Self‑healing orchestration agents

These are intentionally atomic, letting teams compose “Planner ➜ Retriever ➜ Summariser” chains or substitute bespoke variants without touching orchestration code.

---

6. Non‑functional requirements

• Language‑agnostic: Must import both Python and TypeScript agents (trees may include tsconfig.json or pyproject.toml).
• Deterministic: Same git commit → same file hash in destination.
• Offline support: If repo already cloned (~/.agentuity/cache), perform import without network.
• Security: Warn on post‑install scripts; block imports from private repos unless --allow‑private flag and OAuth token present.

---

7. Open questions

1. How should we surface versioning? (e.g., agentuity add web‑search@v0.3.2)
2. Should we automatically register imported agents in the Agentuity Cloud dashboard, or leave that to agentuity deploy?
3. Conflict‑resolution UX for JSON/YAML merge (three‑way vs. ours‑theirs).

---

By delivering agentuity add, we give the community a friction‑free way to compose rather than reinvent, accelerating innovation on top of the Agentuity platform.