Sorcha.Agent 1.0.1

Sorcha Agent - Autonomous Actor for Decentralised Workflows

Version: 1.0.0 Status: Production Ready

The Sorcha Agent is a cross-platform CLI tool that runs as an autonomous actor in Sorcha decentralised register workflows. It listens for pending actions, makes decisions using pluggable engines (rules or AI), and submits responses — enabling fully automated multi-participant workflow execution.

Installation

# Install as a global tool
dotnet tool install --global Sorcha.Agent

# Verify installation
sorcha-agent --version

Quick Start

1. Create an Actor Definition

Actor definitions are JSON files that configure identity, inbox discovery, and decision-making:

{
  "actor": {
    "name": "approver",
    "description": "Automated approval agent"
  },
  "connection": {
    "gatewayUrl": "http://localhost",
    "registerId": "your-register-id",
    "credentials": {
      "email": "$env:AGENT_EMAIL",
      "password": "$env:AGENT_PASSWORD",
      "organizationId": "your-org-id"
    },
    "walletAddress": "your-wallet-address"
  },
  "inbox": {
    "signalR": { "enabled": true },
    "polling": { "enabled": true, "intervalSeconds": 30 }
  },
  "mode": "rules",
  "rules": [
    {
      "actionName": "Review Request",
      "condition": { "==": [true, true] },
      "decision": "approve",
      "payload": {
        "approved": true,
        "notes": "Auto-approved by agent"
      }
    }
  ]
}

2. Validate Configuration

sorcha-agent validate --config actor.json

This checks JSON structure, variable resolution, authentication, and SignalR connectivity.

3. Run the Agent

sorcha-agent run --config actor.json

The agent will authenticate, connect to the inbox, and begin processing actions autonomously.

Commands

Options

Decision Engines

Rules Engine (JSON Logic)

Deterministic rule evaluation using JSON Logic syntax. Rules are evaluated top-to-bottom; first match wins.

{
  "mode": "rules",
  "rules": [
    {
      "actionName": "Cost Approval",
      "condition": { ">": [{ "var": "payload.cost" }, 500000] },
      "decision": "reject",
      "payload": { "reason": "Exceeds budget threshold" }
    },
    {
      "actionName": "Cost Approval",
      "condition": { "==": [true, true] },
      "decision": "approve",
      "payload": { "approved": true }
    }
  ]
}

AI Engine (Claude)

LLM-powered decisions using a persona prompt and action context:

{
  "mode": "ai",
  "ai": {
    "provider": "anthropic",
    "model": "claude-sonnet-4-6",
    "temperature": 0.3,
    "personaFile": "./persona.md",
    "apiKeyEnvVar": "ANTHROPIC_API_KEY"
  }
}

Variable Resolution

• $env:VAR_NAME — Resolved from environment variables (recommended for secrets)
• {{placeholder}} — Resolved from a state.json file (useful for dynamic IDs from setup scripts)

Pre-Actions

Hooks that execute before payload submission, e.g. file uploads:

{
  "preActions": [
    {
      "type": "file-upload",
      "config": {
        "fieldName": "document",
        "filePath": "./report.pdf",
        "fileName": "report.pdf",
        "contentType": "application/pdf"
      }
    }
  ]
}

Features

• Dual Inbox Discovery — Real-time SignalR + configurable HTTP polling with automatic deduplication
• Pluggable Decision Engines — Rules (JSON Logic) or AI (Claude) with schema validation
• File Upload Pre-Actions — Chunked encrypted file submission (up to 40MB)
• Resilient Execution — Polly retry/circuit-breaker, SignalR auto-reconnect, JWT auto-refresh
• Audit Logging — JSONL append-only trail of all decisions and submissions
• Cross-Platform — Runs on Windows, macOS, and Linux

Exit Codes

Requirements

• .NET 10 runtime
• Access to a running Sorcha platform instance
• Valid user credentials with wallet access

License

MIT