AutoSwarm Shadow Adapter

What does this agent do, and when should you use it?

AutoSwarm-Shadow-Adapter is an external agent adapter plugin for the AutoSwarm (OpenOPC) agentic DAG runtime, registered through ADAPTER_CLASSES["shadow"] with zero modifications to the core repository. It intercepts tasks for roles configured with preferred_external_agent: shadow, parks them in an isolated SQLite WAL database (shadow_tasks.db) in under 50ms, and returns AWAITING_HUMAN so worker threads are released immediately. Human reviewers claim work through a React 19 portal on top of a FastAPI REST API (shadow-serve, port 8800), where they read generated markdown briefs, inspect inherited upstream artifacts, and upload up to 5 files per submission. Remote GPU machines can join as silicon workers via the shadow-worker daemon, polling by role and running local inference through Ollama, Anthropic, OpenAI, or a custom Python handler. When a deliverable is submitted, OpcResumeRepository writes back to delegation_work_items.phase in the host store.db, waking downstream DAG nodes through AutoSwarm's native phase hooks.

On the engine side, ShadowModeAdapter parses the project goal, builds a markdown task brief with TaskBriefBuilder, persists the record to shadow_tasks.db, and returns AWAITING_HUMAN; ancestor deliverables are packaged as context. On the portal side, the FastAPI server (shadow-serve --port 8800) exposes JWT+bcrypt-authenticated /api/v1 endpoints, and a React 19 TaskWorkspace lets humans claim pending tasks, write solution notes, and attach files that are indexed into CorporateArtifacts with SHA-256 hashes. On the silicon side, shadow-worker logs in with --server-url, --role, --provider and --model, polls the queue, and runs local inference; ShadowWorker(custom_handler=...) embeds the same loop in custom Python pipelines. Submission triggers OpcResumeRepository to update delegation_work_items.phase in the host store.db, so AutoSwarm's native phase hooks resume downstream DAG nodes and pass artifacts forward; a rework_requested transition supports return-for-revision loops.

1. A company runs multi-agent AutoSwarm workflows but needs real people to sign off on legal review or architecture decisions
2. A freelancer juggling several client contracts routes execution to remote silicon nodes and approves deliverables asynchronously
3. Finance, healthcare or legal teams need immutable, attributed audit trails for SOC 2, ISO 27001 or GDPR human-oversight requirements
4. An enterprise has spare GPU workstations or cloud nodes and wants to plug them in as BYOC inference workers without touching the central engine
5. A role is vacant or overloaded, so AI completes most preliminary work and only the final decision is routed to an available manager

How do you install or deploy this agent?

Requires Python 3.10+ and a host project where AutoSwarm (opc) is installed and runnable.

pip install AutoSwarm-shadow-adapter

A JWT signing secret (documented as at least 32 characters) is mandatory:

export SHADOW_JWT_SECRET="a-very-long-secret-at-least-32-chars"

Optional variables include SHADOW_DB_PATH, SHADOW_OPC_STORE_PATH, SHADOW_UPLOAD_DIR, SHADOW_MAX_FILES_PER_SUBMISSION, SHADOW_MAX_FILE_SIZE_MB, SHADOW_MAX_TOTAL_UPLOAD_SIZE_MB and SHADOW_API_PORT.

How do you use this agent?

Register the adapter and start the portal in a background thread from your entry point:

from opc.layer3_agent.adapters.registry import ADAPTER_CLASSES
from shadow_adapter import ShadowModeAdapter, start_server_in_thread

ADAPTER_CLASSES["shadow"] = ShadowModeAdapter
start_server_in_thread(port=8800)

Or run it as a sidecar from a separate terminal:

shadow-serve --port 8800

Point human-backed roles at the shadow adapter in your company config:

roles:
  legal_counsel:
    title: "Human Legal Counsel"
    execution_strategy: external
    preferred_external_agent: shadow

  senior_architect:
    title: "Human Senior Architect"
    execution_strategy: external
    preferred_external_agent: shadow

Join remote compute nodes as silicon workers:

shadow-worker \
  --server-url "http://192.168.1.100:8800" \
  --username "dev_node_1" \
  --password "secure_pass_1" \
  --role "senior_developer" \
  --provider "ollama" \
  --model "llama3.3:70b"

Reviewers then open http://localhost:8800 to claim tasks and submit deliverables; the REST base is http://localhost:8800/api/v1.

What are this agent's strengths and limitations?

How does this agent compare with similar options?

Key facts side by side with the most closely related agents.

How does FollowAgents rate this agent?

FAQ