Universal tool orchestration layer for agentic AI

Status: Design-phase concept. The Tool Behavior Contract specification exists; implementation has not started. Agent Ether is the agent-orchestration layer (Layer 3) of the Semantic OS. The repository is private while in development.

The Problem

The Fragmented Tool Landscape

AI agents today face unpredictable chaos when using tools:

Result: Agents waste tokens on trial-and-error, make wrong assumptions about tool behavior, and produce brittle workflows that break when tools change.

The Innovation

Tool Behavior Contract (TBC): Unified Metadata-Driven Interface

Agent Ether introduces a specification where every tool declares exactly how it behaves:

The Contract: 5 Questions Every Tool Answers

1. How does it execute?

{
  "execution": {
    "mode": "job"  // sync, async, job, or session
  }
}

2. What channels does it use?

{
  "io": {
    "stdin": "structured",   // JSON input
    "stdout": "structured",  // JSON output
    "progress": "events"     // Progress via event stream
  }
}

3. How do you track progress?

{
  "progress_model": {
    "type": "percent",       // percent, steps, or indeterminate
    "channel": "events"      // Where to read progress from
  }
}

4. What permissions does it need?

{
  "security": {
    "permissions": ["filesystem-read", "network-access"],
    "audit_level": "full",
    "rate_limits": {"max_per_minute": 30}
  }
}

5. How do you invoke and monitor it?

{
  "devices": {
    "invoke": "/dev/agent-ether/tools/fs.search/invoke",
    "events": "/dev/agent-ether/tools/fs.search/jobs/{id}/events",
    "result": "/dev/agent-ether/tools/fs.search/jobs/{id}/result"
  }
}

Agents read the metadata once and know exactly how to use ANY tool.

Four Execution Modes Unified

🟩 Sync (Request → Response)
- Simple queries, calculations, validations
- Blocking call, single request/response
- Example: tool.invoke(input) → output

🟦 Async (Fire and Monitor)
- Background tasks, API calls
- Returns operation ID immediately, produces events asynchronously
- Example: op_id = tool.invoke(input); poll events until done

🟪 Job (Long-Running with Progress)
- Builds, compilations, large searches
- Returns job ID, reports progress via events
- Example: job_id = tool.invoke(input); monitor progress; get result

🟧 Session (Interactive/Stateful)
- REPLs, browsers, debuggers, terminals
- Persistent bidirectional streams, stateful conversation
- Example: session_id = tool.create_session(); write/read loop

One interface. Four modes. Infinite tools.

Tool declares its behavior (/sys/agent-ether/registry/tools.d/fs.search.json):

{
  "id": "fs.search",
  "version": "1.2.0",
  "execution": { "mode": "job" },
  "io": {
    "stdin": "structured",
    "stdout": "structured",
    "progress": "events"
  },
  "progress_model": {
    "type": "percent",
    "channel": "events"
  },
  "security": {
    "permissions": ["filesystem-read"],
    "audit_level": "full"
  },
  "devices": {
    "invoke": "/dev/agent-ether/tools/fs.search/invoke",
    "events": "/dev/agent-ether/tools/fs.search/jobs/{id}/events",
    "result": "/dev/agent-ether/tools/fs.search/jobs/{id}/result"
  }
}

Agent uses metadata to invoke correctly:

from agent_ether import ToolRegistry, ToolInvoker

# 1. Discover tool
registry = ToolRegistry()
tool = registry.get_tool("fs.search")

# 2. Agent reads metadata and knows:
#    - It's a job (long-running)
#    - It reports percent progress via events
#    - It needs filesystem-read permission
#    - Input/output is structured JSON

# 3. Invoke with correct pattern
invoker = ToolInvoker(tool)
job_id = invoker.invoke({
    "pattern": "*.py",
    "path": "/home/user/project"
})

# 4. Monitor progress (metadata told us how)
for event in invoker.stream_events(job_id):
    if event["event"] == "progress":
        print(f"Progress: {event['data']['percent']}%")
    elif event["event"] == "done":
        results = event["data"]["result"]
        break

No guessing. No hardcoded assumptions. Just metadata-driven orchestration.

Status & Adoption

Current Version: v0.1.0-alpha (Design Phase with Complete Specification)

Production Metrics:
- ✅ Complete TBC specification defined
- ✅ Architecture designed (registry, executor, device filesystem, security, tracing)
- ✅ Four execution modes specified (sync, async, job, session)
- ✅ Virtual device filesystem designed (/dev/agent-ether/* paths)
- ✅ Security model complete (permissions, audit levels, rate limits)
- 🔄 Reference implementation in progress (Python SDK)

Novel Research Contributions:

  1. Tool Behavior Contract (TBC) Specification
    - Declarative metadata describes tool execution model
    - Agents discover tools, read contracts, invoke correctly
    - No trial-and-error, no hardcoded tool logic
    - Industry first: Unified interface spanning sync/async/job/session modes

  2. Virtual Device Filesystem (/dev/agent-ether/*)
    - Unix-like device paths for tool interaction
    - Agents write to /dev/agent-ether/tools/{id}/invoke
    - Read progress from /dev/agent-ether/tools/{id}/jobs/{job_id}/events
    - Familiar interface, universal access pattern

  3. Four Execution Modes Unified
    - Sync: Simple request/response
    - Async: Fire-and-forget with event monitoring
    - Job: Long-running with progress tracking
    - Session: Interactive bidirectional streams
    - Same discovery/invocation pattern, different execution models

  4. Metadata-Driven Security
    - Every tool declares permissions upfront
    - Agent runtime enforces constraints
    - Audit logging for all invocations
    - Rate limiting prevents abuse

What This Unlocks:
- Predictable agent behavior - No more token waste guessing tool interfaces
- Multi-agent orchestration - Agents can delegate to other agents using same TBC protocol
- Tool composability - Chain tools reliably (metadata guarantees compatibility)
- Security transparency - Know permissions before invocation, not after breach

v1.0 Release Timeline: Active design phase
- Reference implementation (Python SDK)
- Tool adapter SDK (wrap existing tools in TBC metadata)
- Multi-agent coordination protocols
- Integration with Pantheon IR (tool graphs as semantic IR)

Technical Deep Dive

Full Documentation:

Repository is currently private (in active development). Documentation will be published when the project reaches public beta.

Example Gallery:
- Filesystem Search Tool - Job execution mode
- REPL Session Tool - Interactive session mode
- API Call Tool - Async execution mode

Getting Started:

The Agent Ether repository is private while in design. The core artifact today is the Tool Behavior Contract specification — the metadata schema by which a tool declares its execution mode, channels, progress model, and required permissions, so an agent knows how to drive it without guessing.

Part of SIL's Semantic OS Vision

Agent Ether's Role in the 7-Layer Semantic OS:

Composes With:
- Pantheon (Layer 3/5): Tool graphs as Pantheon IR
- Workflow planning compiles to Pantheon semantic graphs
- Validation framework ensures tool composition is semantically valid
- Constraint solving optimizes tool execution order

Architectural Principle: Intelligence Scales with Coordination, Not Opacity

Agent Ether proves that multi-agent systems don't need black-box communication. When agents share a predictable protocol (TBC), coordination becomes natural instead of heroic.

The Key Insight:
Most agent frameworks treat tools as afterthoughts (wrap existing tools, hope for best). Agent Ether makes tool contracts the foundation:
- Discoverable: Agents list tools, read metadata
- Predictable: Execution model declared upfront
- Safe: Permissions checked before invocation
- Traceable: Every action logged and auditable

This transforms multi-agent systems from "pray it works" to "provably correct orchestration."

Impact: Real-World Use Cases

Before Agent Ether:
- Agent guesses tool is sync → Calls blocking tool → Hangs for hours
- Agent assumes JSON output → Tool returns YAML → Parse error
- Multi-agent system: Agent A doesn't know how to delegate to Agent B → Hardcoded per-agent logic
- Security: Agent uses tool → Later discovers it wrote to filesystem unexpectedly

With Agent Ether:
- Agent reads TBC metadata → Knows tool is job with progress → Monitors correctly
- Agent sees "output: structured" → Parses JSON confidently
- Multi-agent: Agent A reads Agent B's TBC → Delegates using same protocol as any tool
- Security: Agent checks permissions upfront → Filesystem write blocked before invocation

Use Cases Enabled:

  1. Multi-Agent Orchestration
    - Research agents delegate to specialist agents (code, writing, analysis)
    - Hierarchical task decomposition with agent-to-agent coordination
    - Transparent handoffs (full audit trail of delegations)

  2. Tool Marketplace
    - Third-party tools publish TBC metadata
    - Agents discover and integrate new tools dynamically
    - No code changes to agent, just metadata registration

  3. Safe Autonomous Systems
    - Agents declare required permissions upfront
    - Runtime enforces constraints (filesystem, network, rate limits)
    - Audit logs capture all tool invocations for compliance

  4. LLM-Optimized Workflows
    - Agents read TBC metadata once, cache knowledge
    - No token waste on "how does this tool work?"
    - Correct invocation patterns guaranteed by metadata

Adoption Path (v1.0 Goals):
- 20+ tools with TBC metadata (filesystem, network, browsers, REPLs)
- Reference implementation (Python SDK)
- Multi-agent coordination framework
- Integration with major agent frameworks (LangChain, AutoGPT, etc.)

Version: 0.1.0-alpha → 1.0 (Active Design Phase)
License: Apache 2.0
Status: Complete specification, architecture designed, implementation in progress

Patron Saint: Marvin Minsky (1927-2016)
"The Society of Mind" - Intelligence emerges from coordination of simple agents

Learn More:
- GitHub Repository: Semantic-Infrastructure-Lab/agent-ether (private — coming soon)