Components

What a Component Is

A Greentic component is a portable WebAssembly component that implements Greentic’s component ABI and runs inside the Greentic runtime. Components are the executable building blocks called from flows: they render templates, call APIs, transform data, create Adaptive Cards, route work, and encapsulate custom business logic.

Components are:

Sandboxed - Runtime access is controlled through declared capabilities.
Portable - Built as WASI Preview 2 components.
Composable - Called from .ygtc flows and reusable across packs.
Schema-driven - Inputs, config, operations, and setup questions are described in generated metadata.
Agent-friendly - Coding agents can use the wizard schema and replay answers instead of hand-editing manifests and bindings.

Start Here

The component docs are ordered by the surfaces most teams touch first:

Templates

Render deterministic Handlebars text from flow payloads and message envelopes.

Adaptive Cards

Store card JSON in packs, render and validate it, then deliver native or transformed UI through messaging extensions.

Define setup, update, remove, and validation questions for components and extensions.

After those, the section covers existing components and tools such as fast2flow, cards2pack, flow2flow, component-llm-openai, and component-script-rhai.

Create Custom Components

Pack-Owned Component

Use the top-level launcher when the component is part of an application or extension pack:

gtc wizard --schema
gtc wizard --answers pack-with-component.answers.json

gtc wizard delegates to the pack wizard, and the pack wizard can delegate component creation through component_wizard_answers. This keeps the pack manifest, component files, flows, doctor checks, and build steps aligned.

Standalone Component

Use the component wizard directly when you are working in a component project:

greentic-component wizard --schema
greentic-component wizard --answers component-create-answers.json

The current direct create answer shape is:

{
  "wizard_id": "greentic-component.wizard.run",
  "schema_id": "greentic-component.wizard.run",
  "schema_version": "1.0.0",
  "answers": {
    "mode": "create",
    "fields": {
      "component_name": "research-analyst",
      "output_dir": "./components/research-analyst",
      "advanced_setup": true,
      "abi_version": "0.6.0",
      "operation_names": "answer,score_sources",
      "filesystem_mode": "none",
      "http_client": true,
      "http_server": false,
      "messaging_inbound": true,
      "messaging_outbound": true,
      "events_inbound": false,
      "events_outbound": false,
      "secrets_enabled": true,
      "secret_keys": "openai_api_key",
      "secret_format": "text",
      "state_read": true,
      "state_write": true,
      "state_delete": false,
      "telemetry_scope": "node",
      "config_fields": "model:string,temperature:number"
    }
  },
  "locks": {}
}

Do not copy this blindly for future versions. Ask the agent or developer workflow to run greentic-component wizard --schema first and fill the current schema.

Wizard Modes

greentic-component wizard supports these modes:

Mode	Purpose
`create`	Scaffold a component project.
`add-operation`	Add a new user operation to an existing component.
`update-operation`	Rename or update operation metadata.
`build-test`	Run build/test-oriented wizard steps.
`doctor`	Run validation-oriented wizard steps.

Use validate for a no-side-effect plan and apply for execution:

greentic-component wizard validate --answers component-create-answers.json
greentic-component wizard apply --answers component-create-answers.json

The CLI also supports --emit-answers for capturing a reusable AnswerDocument.

What the Wizard Generates

The current Rust template generates a component project with Greentic conventions:

research-analyst/
├── Cargo.toml
├── component.manifest.json
├── Makefile
├── assets/
│   └── i18n/
│       ├── en.json
│       └── locales.json
├── schemas/
│   └── component.schema.json
├── src/
│   ├── i18n.rs
│   ├── i18n_bundle.rs
│   ├── lib.rs
│   └── qa.rs
└── tests/
    └── conformance.rs

The generated files cover:

component operation scaffolding
component.manifest.json
ABI version metadata, currently 0.6.0 by default
config schema fields
host and WASI capability declarations
secret requirements
telemetry scope
QA specs and answer application hooks
i18n bundles and i18n key checks
build, test, and doctor wiring

Capabilities

Capabilities describe what the component may ask the runtime to provide. Declare only what the component actually needs:

Capability	Use it when
HTTP client	The component calls external APIs.
Messaging inbound/outbound	The component reads or emits channel message envelopes.
Events inbound/outbound	The component receives or emits event envelopes.
State read/write/delete	The component stores session, tenant, or workflow state.
Secrets	The component needs runtime secrets such as API keys.
Filesystem	The component reads from or writes to a permitted filesystem mount.
Telemetry	The component emits spans/logs under tenant, pack, or node scope.

Existing Components and Tools

Page	What it is for
Templates	Handlebars text rendering with `payload` and `msg` context.
Adaptive Cards	Card assets, rendering, validation, transformation, and complex card flows.
QA	Component setup/update/remove questions and answer validation.
fast2flow	Intent routing and flow dispatch.
cards2pack	Convert Adaptive Card directories into pack assets and flows.
flow2flow	Flow-to-flow routing patterns.
LLM OpenAI	LLM call patterns for OpenAI-compatible models.
Script Rhai	Lightweight script-style logic in flows.

Build and Validate

From a wizard-generated component:

make wasm
greentic-component doctor ./dist/research-analyst__0_6_0.wasm

You can also call the component CLI directly:

greentic-component build --manifest ./component.manifest.json
greentic-component test \
  --wasm ./dist/research-analyst__0_6_0.wasm \
  --op answer \
  --input ./tests/fixtures/answer.json

Best Practices

Start with gtc wizard --schema or greentic-component wizard --schema.
Replay answers with --answers so the work is reproducible.
Keep operations small and explicit.
Declare only the capabilities the component needs.
Put setup questions and validation in QA, not in prose instructions.
Use i18n keys for user-facing setup text.
Run build, tests, and doctor before packaging.