| name | add-agent |
| description | Use when creating a new pure-WASM agent module (no external service) under crates/runtara-agents. An agent is a logical grouping of capabilities (e.g. xml, csv, http, crypto). For adding a capability to an existing agent, use add-capability instead. For agents that talk to an external service, use add-integration. |
Add a new agent
An agent is a Rust module under crates/runtara-agents/src/agents/ that exposes one or more #[capability] functions. Agents compile to WASM and run inside the workflow runtime.
When to use this vs other skills
- Pure utility / transformation logic (no external HTTP) → this skill. Examples:
xml, csv, crypto, text, transform.
- Talks to a third-party service (Shopify, OpenAI, Slack, ...) → use
add-integration instead.
- Adding a function to an existing agent → use
add-capability instead.
Steps
1. Create the agent file
Add crates/runtara-agents/src/agents/<name>.rs. Reference template: xml.rs.
Minimum boilerplate:
use crate::types::AgentError;
use runtara_agent_macro::{CapabilityInput, CapabilityOutput, capability};
use serde::{Deserialize, Serialize};
2. Re-export from lib.rs
Add to crates/runtara-agents/src/lib.rs following the existing #[path = "agents/MODULE.rs"] pub mod MODULE; pattern. Pick a category section that matches the agent's role.
3. Add the first capability
Follow add-capability for the function shape, input/output structs, and #[capability(...)] attributes. Capabilities auto-register at compile time via inventory — there is no manual registry.
4. WASM constraints (critical)
The agent compiles to wasm32-wasip2. Avoid:
std::thread::sleep (blocks the runtime)reqwest directly — use the workflow runtime's HTTP facilities- Native-only crates (anything pulling
tokio features that aren't WASI-safe, OS-specific syscalls)
Wrap any native-only code in #[cfg(not(target_family = "wasm"))].
5. Tests
Test framework lives at crates/runtara-agents/tests/custom_module_registration_test.rs. Add a unit test inside the new module for pure-logic verification, and an integration test that exercises capability registration if the agent introduces new patterns.
6. Verify
After build, regenerate the frontend API client (regen-frontend-api) so the new capabilities show up in the Step Picker, then run e2e-verify to confirm a workflow can compile and execute against the new agent. Unit tests alone are not sufficient — see the always-e2e-verify rule.
Files touched
crates/runtara-agents/src/agents/<name>.rs — newcrates/runtara-agents/src/lib.rs — add pub mod line- (optional)
crates/runtara-agents/tests/... — new test
