Tutorial 30 — Agent Lifecycle Management: Birth to Retirement¶

Request → Approve → Provision → Activate → Monitor → Rotate → Decommission
    │                                         │
    │                                    Orphan Detection
    └── Reject                           (heartbeat monitoring)

from agentmesh.lifecycle import LifecycleManager, LifecyclePolicy, CredentialPolicy
from datetime import timedelta

# Configure policy
policy = LifecyclePolicy(
    require_approval=True,           # Human must approve new agents
    require_owner=True,              # Every agent needs an owner
    heartbeat_interval=timedelta(minutes=5),
    orphan_threshold=timedelta(hours=24),
    max_inactive_days=90,
    credential_policy=CredentialPolicy(
        max_credential_ttl=timedelta(hours=24),   # Short-lived credentials
        auto_rotate=True,                          # Rotate before expiry
        revoke_on_decommission=True,               # Clean up on shutdown
    ),
)

manager = LifecycleManager(
    policy=policy,
    storage_path="~/.agentmesh/lifecycle.json",  # Persistent storage
)

# Developer requests a new agent
agent = manager.request_provisioning(
    name="Code Review Agent",
    owner="alice@company.com",
    purpose="Automated PR review for the platform team",
    agent_type="langchain",
    actor="alice@company.com",
    tags={"team": "platform", "env": "production"},
)

print(f"Agent {agent.agent_id}: {agent.state.value}")
# → Agent agent:a1b2c3d4e5f6: pending_approval

# Admin approves the request
agent = manager.approve(agent.agent_id, actor="admin@company.com")
print(f"State: {agent.state.value}")  # → provisioned

# Or reject it:
# manager.reject(agent.agent_id, reason="Duplicate of existing agent")

# Activate the agent — issues short-lived credentials
agent = manager.activate(agent.agent_id)
print(f"State: {agent.state.value}")          # → active
print(f"Credential: {agent.credential_id}")    # → cred:abc123...
print(f"Expires: {agent.credential_expires_at}")  # → 24h from now

# Agent sends periodic heartbeats to prove it's alive
agent = manager.heartbeat(agent.agent_id)
print(f"Heartbeats: {agent.heartbeat_count}")  # → 1

# In production, agents call this on a timer:
# while running:
#     manager.heartbeat(my_agent_id)
#     await asyncio.sleep(300)  # every 5 minutes

from agentmesh.lifecycle import CredentialRotator

rotator = CredentialRotator(manager)

# Check fleet and rotate expiring credentials
results = rotator.check_and_rotate()
for r in results:
    print(f"  {r['agent_id']}: {r['action']} — {r['detail']}")

# Manual rotation
agent = manager.rotate_credentials(agent.agent_id)
print(f"New credential: {agent.credential_id}")

from agentmesh.lifecycle import OrphanDetector

detector = OrphanDetector(manager)

# Scan for orphaned agents
candidates = detector.detect()
for c in candidates:
    print(f"  ⚠ {c.agent.name}: {c.reason}")
    if c.days_silent:
        print(f"    Silent for {c.days_silent:.1f} days")

# Mark as orphaned (restricts operations)
detector.mark_orphaned(silent_agent_id)

# Reclaim with new owner
detector.reclaim(orphan_id, new_owner="bob@company.com")

# Clean decommission — revokes credentials, records audit trail
agent = manager.decommission(
    agent.agent_id,
    reason="Feature sunset — migrating to new agent",
    actor="alice@company.com",
)
print(f"State: {agent.state.value}")         # → decommissioned
print(f"Credential: {agent.credential_id}")  # → None (revoked)
print(f"Retired: {agent.decommissioned_at}")

trail = manager.get_audit_trail(agent.agent_id)
for event in trail:
    print(f"  [{event.timestamp}] {event.event_type.value}")
    print(f"    Actor: {event.actor}")
    print(f"    {event.previous_state} → {event.new_state}")

# Output:
#   [2026-04-11T04:30:00Z] requested
#     Actor: alice@company.com
#     None → pending_approval
#   [2026-04-11T04:31:00Z] approved
#     Actor: admin@company.com
#     pending_approval → provisioned
#   [2026-04-11T04:32:00Z] activated
#     Actor: system
#     provisioned → active
#   ...

                    ┌─────────┐
                    │REQUESTED│
                    └────┬────┘
                   approve│reject
              ┌──────────┴──────────┐
              ▼                     ▼
        ┌───────────┐        ┌──────────────┐
        │PROVISIONED│        │DECOMMISSIONED│
        └─────┬─────┘        └──────────────┘
         activate│                    ▲
              ▼                       │
        ┌──────────┐    decommission  │
   ┌───►│  ACTIVE  ├─────────────────►│
   │    └──┬───┬───┘                  │
   │  suspend│  │orphan               │
   │       ▼  │  ▼                    │
   │ ┌─────────┐ ┌────────┐          │
   │ │SUSPENDED│ │ORPHANED├──────────►│
   │ └────┬────┘ └───┬────┘          │
   │ resume│     reclaim│              │
   └──────┘      └──────┘