session-mesh
Purpose
This skill manages session topologies in distributed communication systems. It enables discovery of active sessions, maintains a specialization registry, allows steering or terminating sub-agents, and handles session keys for secure interactions. Use it to build resilient mesh networks where agents communicate dynamically.
When to Use
- When monitoring or managing distributed sessions in real-time, such as in IoT fleets or multi-agent AI systems.
- For tasks involving sub-agent control, like rerouting traffic or scaling resources in a mesh topology.
- In scenarios requiring session key management for authentication, e.g., secure data exchange between agents.
- Avoid if you're working with isolated, non-distributed systems; this is optimized for interconnected environments.
Key Capabilities
- Discover alive sessions: Query active sessions using GET /api/session-mesh/alive with query parameters like?filter=active.
- Specialization registry: Register sub-agent specializations via POST /api/session-mesh/registry with a JSON body, e.g., {"specialization": "image-processing", "agent_id": "123"}.
- Steer sub-agents: Redirect agents using CLI flag --direction (e.g., north/south) or API endpoint POST /api/session-mesh/steer with payload {"agent_id": "456", "direction": "east"}.
- Kill sub-agents: Terminate agents via CLI command session-mesh kill --agent-id 789 or API DELETE /api/session-mesh/agents/789.
- Session keys: Generate keys with POST /api/session-mesh/keys, returning a secure token for authentication.
Usage Patterns
- Basic workflow: First, discover sessions with a GET request, then use the response to steer or kill agents as needed. Always check for alive status before actions.
- Registry pattern: Register specializations during setup, then query the registry before assigning tasks to ensure compatibility.
- Error-resilient pattern: Wrap API calls in try-catch blocks and retry on transient errors; use session keys in every authenticated request.
- Sub-agent management: For mesh networks, periodically poll alive sessions and steer agents based on load, e.g., every 30 seconds via a scheduled script.
- Key handling: Always generate a new session key per interaction and store it securely; use it in headers for subsequent API calls.
Common Commands/API
- CLI Commands:
- List alive sessions: session-mesh list --filter alive --output json. Requires $SESSION_API_KEY set in environment. - Steer an agent: session-mesh steer --agent-id 123 --direction west. Example: First run export SESSION_API_KEY=your_key then execute. - Kill an agent: session-mesh kill --agent-id 456 --force. Use --force for immediate termination without confirmation. - Register specialization: session-mesh register --spec "data-analysis" --agent-id 789. Config format: YAML file with key-value pairs, e.g., spec: data-analysis.
- API Endpoints:
- Discover sessions: GET https://api.example.com/api/session-mesh/alive?filter=active. Headers: {'Authorization': 'Bearer $SESSION_API_KEY'}. - Code snippet (Python): import requests; import os response = requests.get('https://api.example.com/api/session-mesh/alive', headers={'Authorization': f'Bearer {os.environ.get("SESSION_API_KEY")}'}) print(response.json()) - Steer agent: POST https://api.example.com/api/session-mesh/steer with body {"agent_id": "123", "direction": "north"}. Response includes status code 200 on success. - Code snippet (curl): curl -X POST https://api.example.com/api/session-mesh/steer \ -H "Authorization: Bearer $SESSION_API_KEY" \ -d '{"agent_id": "123", "direction": "north"}' - Config format: JSON payloads for API, e.g., {"session_key": "abc123", "ttl": 3600} for key generation.
Integration Notes
- Authentication: All commands and APIs require a session key. Set it via environment variable:
export SESSION_API_KEY=your_secure_key. Never hardcode keys; use secure vaults. - Dependencies: Integrate with distributed-comms cluster by including the skill ID "session-mesh" in your AI agent's config file, e.g., JSON: {"skills": ["session-mesh"], "cluster": "distributed-comms"}.
- Configuration: Use a YAML config for multi-session setups, e.g.:
sessions: - id: 123 - filter: aliveLoad it withsession-mesh load-config path/to/config.yaml. - Testing: Run integration tests in a sandbox environment; mock API responses for endpoints like /api/session-mesh/alive to simulate failures.
Error Handling
- Common errors: HTTP 404 for non-existent agents (e.g., when killing an invalid ID); handle by checking response.status_code == 404 and logging the error.
- Authentication failures: If $SESSION_API_KEY is invalid, expect 401 Unauthorized; resolve by regenerating the key via POST /api/session-mesh/keys and retry.
- Prescriptive steps: Always validate inputs before commands, e.g., check if agent_id exists via a prior GET request. For CLI, use --verbose flag to debug, e.g.,
session-mesh list --filter alive --verbose. In code, wrap calls like this:try: response = requests.post(url, headers=headers) response.raise_for_status() except requests.exceptions.HTTPError as e: print(f"Error: {e.response.status_code} - {e.response.text}") - Retry logic: Implement exponential backoff for network errors; limit retries to 3 attempts.
Graph Relationships
- Related to cluster: "distributed-comms" for interconnected agent management.
- Connects with tags: "sessions" (shares data with session-based skills), "topology" (links to network mapping tools), "mesh" (integrates with peer-to-peer systems), "subagents" (depends on sub-agent control skills like agent-lifecycle).