Channel Tagging System

Configure services for deployment channels (voice, text, async) with LLM preset validation.

Channel tags tell Amigo how your service will be used: over voice, over text, or asynchronously. Those tags drive validation and pick LLM presets suited to each channel's latency and capability profile.

Overview

Different deployment channels have distinct requirements:

• Voice channels need ultra-low latency and restrict which state types you can use.

• Text channels support the full feature set at moderate latency.

• Async channels (email, API) have relaxed latency requirements and the largest capability surface.

The channel tagging system helps you configure services appropriately and validates configurations before sync.

Channels

Channel	Type	Typical Use Case
phone	voice	Telephony (PSTN / VoIP - Voice over IP)
web_voice	voice	Browser WebRTC
mobile_voice	voice	Mobile app voice
sms	text	SMS messaging
whatsapp	text	WhatsApp
web_chat	text	Web chat widget
mobile_chat	text	Mobile app chat
email	async	Email
api	async	Direct API integration

Channel Profiles

Each channel type has a profile that defines its constraints.

Voice Channels

• Max states: 5

• Allowed state types: action, annotation, tool-call

• Memory retrieval: disabled

• Dynamic behaviors: not supported

• Recommendation: configure keyterms for transcription accuracy

Text Channels

• Max states: unlimited

• Allowed state types: all

• Memory retrieval: supported

• Dynamic behaviors: supported

Async Channels

• Max states: unlimited

• Allowed state types: all

• Memory retrieval: supported

• Dynamic behaviors: supported

• Maximum capabilities with relaxed latency requirements

Version Set Presets

Presets configure LLM models optimized for each channel type.

Tier	Voice	Text	Async
Standard	voice	text	async
Premium	voice_premium	text_premium	async_premium
Economy	voice_economy	text_economy	async_economy
Ultra-Low	voice_ultra_low	-	-
Ultra-Low Premium	voice_ultra_low_premium	-	-

Regional Availability

Some presets use LLMs that are not available in all regions. See LLM Regional Availability for the full availability matrix.

Premium Model Regional Restriction

The following presets use premium-tier models that are only available in US and EU regions:

• text_premium

• async

• async_premium

These presets cannot be deployed to CA or AU regions. Use economy or standard presets for those regions instead.

Ultra-Low Latency Presets

The voice_ultra_low and voice_ultra_low_premium presets require single-state context graphs.

Single-State Requirements

To use ultra-low latency presets:

• All action states must have exactly 1 action.

• All action states must have 0 exit conditions.

• Set skip_active_memory_retrieval: true.

This triggers the backend fast path, which skips the select_next_action LLM call and saves 100-500ms latency per turn.

Tag Format

Services support two tag formats in local JSON/YAML files.

Simple String Format (Recommended)

{
  "tags": ["phone", "voice_premium"]
}

Or in YAML:

tags:
  - phone
  - voice_premium

Object Format (Legacy)

{
  "tags": [
    {"key": "phone", "value": null},
    {"key": "voice_premium", "value": null}
  ]
}

Use the simple string format for easier editing. Both formats are automatically converted to the API format during sync.

Tags encode two things:

1. Channel (e.g., phone, web_chat): which deployment channel the service runs on.

2. Preset (e.g., voice_premium, text): which LLM configuration to apply.

Service Environment Tags

Services can be tagged with dev or production to enforce different validation rules for version set pinning.

Environment Tag Options

Tag	Description	Validation Rules
dev	Development/sandbox services	No version pinning required. Can push directly to release.
production	Production services	Must have preview defined. release must match preview. All version sets must be pinned.

Adding Environment Tags

Add an environment tag alongside your channel tags:

tags:
  - phone
  - voice_premium
  - production  # or 'dev'

No environment tag? Services without an environment tag skip environment-specific validation entirely.

Production Service Requirements

When a service is tagged production, the following rules are enforced during forge sync-to-remote:

1. Preview version set required: a preview version set must be defined.

2. Release matches preview: the release configuration must exactly match preview (agent version, context graph version, LLM preferences).

3. Versions pinned: all version sets (except edge) must have explicit pinned version numbers. No latest.

Example validation error:

Service: My Production Service
  ! Production service missing required 'preview' version set.
  ! Release version set does not match preview configuration.
  ! Version set 'release' must have pinned agent version for production services.

Dev Service Flexibility

Services tagged dev have no version set restrictions:

• Can use unpinned versions (latest) in any version set.

• No preview requirement.

• Can push directly to release without going through a promotion workflow.

Use dev only for sandbox or development environments. Production services should always use the production tag to enforce proper promotion workflows.

LLM Validation

Service tags drive LLM validation at the version set layer. LLM preferences then have to match the channel and cost expectations for those tags.

Voice-Optimized LLMs

Voice channels need a low Time-To-First-Token (TTFT) for real-time conversation, so only a subset of available LLMs meet the latency bar. Run forge channel llm-info --channel phone to see the current list of voice-optimized models.

Non-voice-optimized LLMs will cause validation errors for services with voice channel or voice preset tags. Premium-tier and high-capability models generally have higher latency and are not suitable for voice.

Cost Tier Classifications

LLMs are classified into cost tiers for validation against preset expectations.

Tier	Description	Price Range (per 1M input)
Economy	Lightweight, low-cost models optimized for speed	$0.05-$0.40
Standard	Balanced cost and capability	$0.25-$2
Premium	Highest capability models	$1.25-$15

Run forge channel llm-info to see the current model-to-tier mapping.

Validation Rules

Tag	Validation	Severity
Voice channel (phone, web_voice, mobile_voice)	Non-voice-optimized LLMs	ERROR
Voice preset (voice, voice_premium, etc.)	Non-voice-optimized LLMs	ERROR
Economy preset (*_economy)	Premium-tier LLMs	ERROR
Premium preset (*_premium)	Only economy-tier LLMs	ERROR
Production environment	release LLM prefs != preview	ERROR
Empty llm_model_preferences (voice)	System defaults may not be voice-optimized	WARNING
No channel/preset tags	LLM preferences cannot be validated	WARNING

Example Validation Output

!! CHANNEL VALIDATION ERRORS !!

  Entity: Cardi (68bb4c7fb3c5a689980b217f)
    ✗ ERROR: Version set 'release' uses non-voice-optimized LLM
      for 'backend.chat_agent_engage_user'.
      Voice preset 'voice' requires voice-optimized LLMs for low latency.

~~ CHANNEL VALIDATION WARNINGS ~~

  Entity: SDK Test Service (689b81e7afdaf934f4b48f81)
    ⚠ WARNING: Version set 'edge' has empty llm_model_preferences.
      System defaults may include non-voice-optimized LLMs.

System Defaults vs Preset Defaults

Important. Empty llm_model_preferences does NOT use preset defaults. It uses system defaults, which may not match your channel or preset requirements.

For voice services, always configure LLM preferences explicitly to make sure voice-optimized models are used.

Validation

Services with channel tags are validated against channel constraints:

• Preset compatibility: voice presets only work with voice channels.

• Regional LLM availability: presets are validated against the target region's LLM availability.

• LLM preferences: voice channels require voice-optimized LLMs, and cost tiers must match preset expectations.

• Channel constraints: context graphs are checked against channel profile limits.

• Keyterms warning: voice services without keyterms trigger a warning.

• Untagged LLM preferences: services with LLM preferences but no tags trigger a warning.

• Errors block sync. Warnings prompt for confirmation.

Standalone Validation

Use forge validate to check services locally before syncing.

# Validate all services
forge validate --entity-type service --env production

# Validate all entity types
forge validate --all --env production

# Also check references against remote
forge validate --entity-type service --env production --check-references

# Validate service dependencies against channel constraints
forge validate --entity-type service --env production --check-dependencies

This catches issues early without making any changes to the remote.

Dependency Validation (--check-dependencies)

The --check-dependencies flag validates that a service's linked assets are compatible with its channel constraints. It's essential for voice services, which have strict latency requirements.

What gets validated:

Check	Voice Channels	Severity
Context graph state count ≤ 5	✓	Warning
No decision/reflection/recall states	✓	Error
No active memory retrieval	✓	Warning
No dynamic behaviors applied	✓	Error
Single-state for ultra-low presets	✓	Error

Example output:

── Validating service dependencies ──
  Loaded 12 context graphs
  Loaded 148 dynamic behaviors

  Service: Cardi
    Context graph: Cardi POC Check In
    ! Context graph 'Cardi POC Check In' contains state types not allowed
      for phone channel: decision (1), reflection (1).
    ~ Context graph 'Cardi POC Check In' has 10 states, exceeds recommended
      max of 5 for phone channel.

  Service: Reactive Support
    Dynamic behaviors applied: 145
    ! Voice channel 'phone' does not support dynamic behaviors.

============================================================
Validation complete: 3 error(s), 28 warning(s)

Voice Services with Dynamic Behaviors

Voice channels do not support dynamic behaviors due to latency requirements. If you have dynamic behaviors applied to a voice service, you must either:

1. Remove the dynamic behaviors from the service, or

2. Change the service to a text or async channel.

Validation Flow

CLI Commands

Use forge channel commands to explore and validate configurations.

List Channels

forge channel list-channels

Shows all supported channels with their profiles.

List Presets

# All presets
forge channel list-presets

# Filter by type
forge channel list-presets --type voice

# Show LLM configurations
forge channel list-presets --verbose

Show Channel Profile

forge channel show-profile phone

Displays constraints and recommendations for a specific channel.

Show Tags

# Default preset
forge channel show-tags phone

# Specific preset
forge channel show-tags phone --preset voice_premium

Outputs the JSON tags to add to your service.

Validate Preset

# Validate preset for channel
forge channel validate-preset voice_premium phone

# Validate preset for channel AND region
forge channel validate-preset text_premium web_chat --region ca

Checks whether a preset is compatible with a channel, and optionally validates regional LLM availability.

Validate Context Graph

# Basic validation
forge channel validate-context-graph phone \
  --state-type action \
  --state-type annotation \
  --state-count 3

# Validate for ultra-low latency
forge channel validate-context-graph phone \
  --state-type action \
  --state-count 1 \
  --single-state-eligible \
  --preset voice_ultra_low

Validates context graph characteristics against channel constraints.

LLM Info

# All models
forge channel llm-info

# Voice-optimized models
forge channel llm-info --channel phone

Shows the LLM catalog with voice-optimized recommendations.

Best Practices

Voice Channel Optimization

1. Use keyterms: configure domain-specific vocabulary for better transcription.

2. Minimize states: keep context graphs under 5 states for voice.

3. Consider ultra-low presets: if your workflow is single-state, use voice_ultra_low to save 100-500ms.

4. Avoid memory retrieval: set skip_active_memory_retrieval: true for voice.

Preset Selection Guide

Scenario	Recommended Preset
Production voice with quality focus	voice_premium
High-volume voice, cost-sensitive	voice_economy
Single-state voice flows	voice_ultra_low
Standard text chat	text
Complex reasoning (email, API)	async_premium

Example: Configuring a Voice Service

1. Check channel constraints:

   forge channel show-profile phone

2. Get tags for your preset:

   forge channel show-tags phone --preset voice_premium

3. Add tags to your service in local/<env>/entity_data/service/<service>.yaml:

   tags:
     - phone
     - voice_premium

4. Validate locally (catches issues without touching remote):

   forge validate --entity-type service --env production

5. Validate dependencies (makes sure the context graph is compatible):

   forge validate --entity-type service --env production --check-dependencies

6. Preview sync changes:

   forge sync-to-remote --entity-type service --env production

7. Apply changes:

   forge sync-to-remote --entity-type service --env production --apply

Related Documentation

Version Sets & Promotion