← Back to Guide Docs

⚠️ IMPORTANT: All features are experimental, under active development. Use at your own risk. Customization to your workflow required. © 2026 GLG, a.s. | ← Back to Index

15. Orchestration Rules — Agent Behavior Control (Team+)

Orchestration rules define how agents interact, coordinate, and behave in a team. They are the policy layer that enforces your coordination decisions.

15.1 Rule Types

Type Purpose Example
lock Prevent concurrent access to a scope "Only one agent can edit src/*.py at a time"
halt Stop an agent from acting "Marketing agent pauses during server maintenance"
allow Explicitly permit an action "Coder can always read architecture docs"
notify Alert when something happens "Notify leader when any agent finishes a task"
sanitize Wrap untrusted input "Sanitize all email content before processing"

15.2 Creating Rules

from uaml.coordination import CoordinationDetector

coord = CoordinationDetector(db_path="coordination.db")

# Rule: Only one agent can work on the API at a time
coord.add_rule(
    rule_type="lock",
    trigger_pattern="CLAIM",
    action="lock",
    scope="src/api/*",
    channel="*",
    priority=80,
    description="Exclusive lock on API source files"
)

# Rule: Halt marketing during deployment
coord.add_rule(
    rule_type="halt",
    trigger_pattern="HALT",
    action="halt",
    scope="deployment/*",
    channel="*",
    priority=100,
    description="Stop marketing during deploy — no web edits"
)

# Rule: Notify leader on task completion
coord.add_rule(
    rule_type="notify",
    trigger_pattern="RELEASE",
    action="notify",
    scope="*",
    channel="*",
    priority=50,
    description="Alert coordinator when any task completes"
)

15.3 Presets

Three built-in orchestration presets:

Preset Rules Best For
Conservative Strict locking, all notifications, aggressive sanitization Production teams, regulated
Standard Normal locking, leader notifications, email sanitization General teams
Permissive Minimal locking, no auto-notifications, basic sanitization Small trusted teams 
# Apply a preset:
requests.post("http://localhost:8780/api/v1/coordination/presets",
    json={"preset": "conservative"})

15.4 Dashboard UI — Agent Orchestration

The Orchestration page (/orchestration) provides:

15.5 Scope Matching

Rules match scopes using three patterns:

Pattern Example Matches
Exact src/api.py Only src/api.py
Glob src/*.py All .py files in src/
Directory src/api/ Everything under src/api/
Wildcard * Everything (catch-all) 
# Check what rules apply to a scope:
rules = coord.get_rules_for_scope("src/api/v2/recall.py")
# Returns rules matching: exact, "src/api/*", "src/", "*"

15.6 Rule Priority

Higher priority = higher precedence. When multiple rules match:

Priority 100: HALT (deployment in progress) → blocks everything
Priority  80: LOCK (src/api/*) → prevents concurrent edit
Priority  50: NOTIFY (on RELEASE) → informational only

A HALT at priority 100 overrides a LOCK at priority 80.

15.7 Audit Trail

Every rule change and every coordination event is logged:

# Query orchestration audit:
GET /api/v1/rules-log?limit=20

# Returns:
# - Who changed which rule, when, and why
# - Which agent triggered which event
# - Conflict resolutions and their outcome

15.8 Practical Example: Deployment Pipeline

# 1. Leader initiates deployment
coord.halt(target="marketing", reason="Deployment starting — no web edits")
coord.halt(target="support", reason="Deployment starting — hold responses")

# 2. Coder deploys
coord.claim(agent="coder", scope="deployment/production", reason="Deploying v2.1")
# ... deploy steps ...
uaml.learn("Deployed v2.1 successfully. 0 errors, 3 warnings.",
           topic="deployment", confidence=0.95)
coord.release(agent="coder", scope="deployment/production")

# 3. Leader verifies and resumes
# HALT events auto-resolve when coder releases deployment scope
# Or manually:
requests.post(f"{COORD}/events/42/resolve", json={"resolved_by": "leader"})

# 4. All agents resume normal work
← Previous Next →