Enabling Multi-Agent Support in UAIX (.uai)

Full report

On this page

Executive Summary: UAIX’s UAI-1 standard already provides a rich JSON-based envelope for agent communication, including fields for sender/receiver identity, conversation state, delivery metadata, trust, provenance, and extensions. To support multi-agent scenarios (group messages, discovery, negotiation, etc.), we propose small optional extensions to this envelope and message body. For example, adding an optional list of recipient agents (or a “broadcast” mode) and explicit discovery/query messages enables agents to find and negotiate tasks with each other, while leaving existing parsers and workflows intact. We discuss how these extensions leverage UAIX’s current profiles (e.g. uai.agent.message.v1, uai.agent.handoff.v1) and “extensions” fields, and we outline security, compatibility, and implementation considerations. In the end, we recommend a phased approach: first reusing UAI-1’s conversation and delivery fields for chained tasks and acknowledgments, then gradually introducing multi-recipient envelopes and discovery profiles. This maximizes backward compatibility and minimizes new complexity.

1. Current .uai Features and Extension Points

UAIX’s UAI-1 messages use a canonical JSON envelope with structured fields. Key envelope sections include:

• Identity & addressing: uai_version, profile, message_id, and nested source/target objects identify sender and intended recipient. Each agent has an id, type (e.g. “agent” or “runtime”), label, and optional DID/URI.
• Workflow continuity: A conversation object (with conversation_id, turn_id, parent_message_id, etc.) sequences multi-turn dialogues.
• Delivery metadata: A delivery object specifies mode (sync/async/event), priority, expiry, reply/ack expectations, an idempotency_key, retry counters, and lifecycle status. These enable reliable, idempotent exchanges even over failures (e.g. via an acknowledgement packet).
• Trust context: A trust object declares the channel (e.g. “public-web”), authentication scheme, principal identity (often a DID or URL), and references to credentials or signatures. This makes sender identity verifiable without hard-coding a single stack.
• Business payload: The body is profile-specific. For uai.agent.message.v1, required body fields include message_type (directive/query/etc.), content, context_refs (URIs to related docs or schemas), requires_acknowledgement, and intent/action qualifiers. Other profiles carry task status, handoff commands, errors, etc.
• Audit fields: provenance and integrity record a trace ID, timestamps, model/agent info and hashes so the exchange is auditable. An extensions array provides a safe-harbor for future fields or custom metadata.

UAIX provides extension points via these optional or flexibly-defined areas. Notably, the extensions field (with namespace-qualified entries) can carry extra metadata, and context_refs can point to external documents. New profiles and body fields can also be defined via the UAIX Schema Registry. Official UAIX documentation (specs, schemas, examples) cover agent-focused profiles (e.g. uai.agent.handoff.v1, uai.agent.ack.v1, uai.agent.task-status.v1, uai.capability.negotiation.v1, etc.). Implementations exist in WordPress and .NET tools, but these generally follow UAI-1 without multi-recipient extensions. In sum, the .uai format is very extensible: it already supports agent IDs, correlation IDs, acknowledgements, delegated task packets, and even agent capability profiles. Any multi-agent extension should reuse these where possible to preserve compatibility.

2. Multi-Agent Architectures and Protocol Patterns

Multi-agent systems typically use structured messaging patterns, often inspired by older Agent Communication Languages (ACL). For example, FIPA-ACL defines performatives (e.g. inform, request, proposal, subscribe) and standard fields like sender, receiver, content, conversation-id, ontology, etc.. Such protocols support one-to-one or multicast messaging: “Participants (Sender/Receiver)” can be a list for broadcast scenarios. Similarly, KQML introduced broker agents (facilitators) for registration and lookup, enabling agents to discover and forward messages via registry services.

Modern LLM-driven agent protocols (e.g. Model Context Protocol, A2A, ACP, ANP) build on these ideas. A recent survey describes A2A (Agent-to-Agent Protocol) as using JSON “Agent Cards” at a well-known URL for discovery: each agent advertises its capabilities (skills, input/output schema, auth) in a JSON document. A Client Agent retrieves these Agent Cards to find a suitable Remote Agent before delegation. A2A also specifies structured task messages and acknowledgments to coordinate delegation. Likewise, MCP/ACP define JSON-RPC or REST-based exchanges for tool invocation, and ANP uses DIDs and JSON-LD graphs for open discovery.

Common multi-agent patterns include:

• Discovery: Agents query a registry or browse published metadata (“agent cards”) to find peers with needed capabilities.
• Negotiation: Agents exchange proposals (e.g. via CFP/propose/accept workflow) to agree on task delegation or resource use.
• Request-Reply vs. Pub-Sub: Protocols support direct request-response or publish-subscribe channels. For example, an agent may broadcast a query to many agents or subscribe to updates on a shared topic (like an event stream).
• Conversation tracking: Unique conversation IDs and parent-message links allow correlating multi-turn dialogs and nested tasks.
• Acknowledgement and Idempotency: Reliable delivery uses explicit acks and unique message IDs/keys to prevent duplicates.
• Concurrency/Shared State: Agents may work concurrently on parts of a task; protocols often include locks or commit semantics or use a central mediator to serialize updates. If multiple agents update shared memory, conflicts are managed by approval or merging.
• Security/Trust: Decentralized identity (DID) and signed credentials ensure agent authenticity. Agents may encrypt messages or restrict fields to authorized peers.

In summary, multi-agent systems rely on explicit sender/receiver IDs, conversation threading, optional broadcast semantics, discovery mechanisms, and transaction-like acks. These capabilities parallel UAIX’s design (which already has IDs, threading, acks), but multi-agent adds group addressing, discovery queries, etc.

3. Proposed .uai Extensions for Multi-Agent Interaction

To enable multi-agent use cases without breaking existing parsers, we propose optional extensions to the .uai envelope and body:

• Multi-Recipient Messaging: Allow the target field to optionally carry multiple recipients. For backward compatibility, we could define either an alternate field (e.g. "additional_targets": [...]) or allow "target" to be a list of agent objects in keyless mode. For example:

  // Single target (existing)
  "target": {"type":"agent","id":"agt_alpha","label":"Agent Alpha", ...},
  // Optional multi-target (new)
  "additional_targets": [
    {"type":"agent","id":"agt_beta","label":"Agent Beta", ...},
    {"type":"agent","id":"agt_gamma","label":"Agent Gamma", ...}
  ],

When present, the sender’s message is intended for all listed agents (broadcast/Multicast). Existing parsers will simply ignore the new field if unrecognized; updated validators can require that keyless lists or additional_targets follow the same schema as target. This covers group notifications or one-to-many directives.

• Discovery and Query Profiles: Introduce a new intent profile such as uai.agent.discovery.v1 (or reuse uai.intent.request.v1) to perform agent discovery. For example, an agent could send:

  // Pseudocode for an agent discovery query
  {
    "profile":"uai.intent.request.v1",
    "body": {
      "intent":"find_agents",
      "subject":"capability.query",
      "parameters": {"skill":"weatherforecast", "location":"NYC"}
    }
  }

Other agents or a directory service could respond with a list of matching agent IDs or Agent Cards. This adds no new envelope fields and could use UAIX’s existing context_refs or extensions to point to an index of agent metadata.

• Capability Negotiation: UAIX already has a uai.capability.negotiation.v1 schema for clients. We recommend repurposing it (or defining a similar one) for agent-to-agent negotiation. For instance, two agents could exchange uai.capability.profile.v1 and uai.capability.negotiation.v1 packets to agree on a common protocol version or data format before starting. This requires no new fields, just use the existing profiles for agents instead of browsers.

• Enhanced Delivery Modes: Define new delivery.mode values for group communication. For example, "mode":"pubsub" or "mode":"broadcast" (in addition to “sync”/“async”/“event” permitted now). A pub/sub mode could use a delivery.topic field (a string or list) to identify a channel. Since mode and any new fields would be optional extensions in the envelope, legacy systems simply ignore unknown modes.

• Group Conversation ID: Allow the existing conversation_id to optionally represent a multicast group context. No syntax change is needed, but agents should agree on a convention that certain conversation IDs correspond to multi-party dialogs. The turn_id and parent_message_id fields can still track threads within that conversation, as usual.

These extensions are additive and optional. For example, a simple one-to-one agent message still looks like the standard uai.agent.message.v1 envelope; multi-agent cases just populate the new fields when needed. Existing tools can remain unchanged; they will still see valid UAI-1 envelopes (perhaps with extra keys they ignore). Validation rules can be updated to allow these extras under the UAIX “extensions” regime.

Example: A delegating agent might send a handoff to two workers with a group directive:

{
  "profile":"uai.agent.handoff.v1",
  "source":{"id":"agt_manager",...},
  "target":{"id":"agt_worker1",...},
  "additional_targets":[{"id":"agt_worker2",...}],
  "delivery":{"mode":"async", "ack_required":true, ...},
  "body":{
    "task_id":"task_42",
    "context_summary":"Process dataset X",
    "handoff_reason":"parallelization",
    "exact_next_action":"Process partition Y",
    "target_agent_id":"agt_worker2",
    ...
  }
}

This would tell both worker1 and worker2 about a shared task (breaking it into parts). Each worker could then individually acknowledge and process its portion.

sequenceDiagram
    participant Manager as Agent Manager
    participant Worker1 as Agent Worker1
    participant Worker2 as Agent Worker2
    Manager->>Worker1: uai.agent.handoff.v1 (task 42, context)
    Manager->>Worker2: uai.agent.handoff.v1 (task 42, context)
    Worker1->>Manager: uai.agent.ack.v1 (handoff received)
    Worker2->>Manager: uai.agent.ack.v1 (handoff received)
    Worker1->>Manager: uai.agent.final-report.v1 (completed subtask)
    Worker2->>Manager: uai.agent.final-report.v1 (completed subtask)

In this flow, each message is a standard UAI packet with extra recipients. The manager uses uai.agent.handoff.v1 to assign subtasks, and workers reply with uai.agent.ack.v1 and later uai.agent.final-report.v1. All messages use UTC timestamps and the canonical JSON envelope.

4. Impact on Tools, Parsers, and Workflows

Our proposals use optional fields and known profiles, so existing parsers stay valid UAI-1 readers. Key compatibility considerations:

• Parsers/Validators: Any new fields (e.g. additional_targets, new mode values) must be added to the schema registry or validator rules. Until then, implementations should accept unknown fields in the envelope (as UAIX’s JSON Schema validation can allow additionalProperties or an “extensions” entry). The UAIX field registry and transport bindings already anticipate future extensions.
• Backward Compatibility: Agents not updated will simply ignore unknown fields or targets, effectively receiving only the primary target’s data. For example, a legacy agent might see only target and handle it normally, while ignoring additional_targets. To ease migration, handlers should default to treating a message with unknown extra fields as a normal message. Over time, tools can adopt the full semantics.
• Conversation Linking: No changes needed beyond common use of conversation IDs. Agents should use the standard conversation object to correlate related messages across multiple parties. Existing turn_id and correlation_id fields cover branching dialogues.
• Message Routing: Multi-recipient messaging may require underlying transport support (e.g. a broker or pub/sub system). At minimum, a UAIX runtime should propagate the same envelope to each intended agent. This could be done by the sender sending multiple identical UAI packets (one per recipient) if native broadcast isn’t available. Either way, the UAIX record remains plain JSON and backward compatible.
• Migration Strategy: We recommend a phased rollout. First, use only one-to-one UAI flows and feature flags (e.g. designating some conversation IDs as group conversations). Next, introduce multi-target fields in a supported client and allow them to fall back gracefully. Update the UAIX JSON Schema and validator by bumping version (still 1.0 for UAI-1) to recognize the new fields. Provide test messages (examples) and update tooling (CLI/SDK) to handle them. Since all changes are additive, older UAI-1 implementation claims remain valid until updated.

Overall, by building on UAI-1’s existing schema machinery, these extensions incur low compatibility risk. UAIX’s design even encourages adding fields as needed: its field registry and JSON Schema mode support keyless (array) and keyed formats in parallel. Migration is mainly a matter of updating validators and documenting the new fields, not rewriting the protocol.

5. Security, Privacy, and Concurrency

Adding multi-agent features raises these concerns:

• Security: UAI-1 already includes a robust trust model. Agents should authenticate using DIDs or signed credentials in the trust object. Multi-recipient messages amplify the risk of misdelivery: if broadcast, ensure only intended agents can read content. Possible mitigation: encrypt content with each target’s public key (outside UAI or via extensions), or use ACLs. The use of signed message envelopes (e.g. JWS) can ensure agents cannot be spoofed. UAIX’s replay_window_id and optional credential references help prevent replay attacks.
• Privacy: Broadcasting exposes content to multiple agents. Ensure content does not leak sensitive info to parties without clearance. Privacy-focused protocols might omit personal data and rely on agent IDs (DIDs) instead of human info. UAIX’s extensions could mark fields as sensitive, but encryption is the ultimate guard.
• Concurrency: When multiple agents work on a shared task or memory, conflicts can occur. UAIX addresses shared memory by separating hot and cold context (Project Handoff) and using proposals/final-reports to sequence updates. Agents should use uai.agent.memory-proposal.v1 and final-report packets to coordinate writes (e.g. one agent proposes facts, another confirms). The use of idempotency_key and unique message IDs prevents duplicate actions. If two agents try to update the same goal, the receiving agent can issue a uai.agent.blocker.v1 to signal a conflict or require human approval.
• Reliability: Ack loops ensure messages aren’t lost in async flow. Each uai.agent.message.v1 can set "ack_required": true and include an idempotency_key. The recipient must then send a uai.agent.ack.v1, closing the loop. If an ack is not received in time, the sender may retry with the same idempotency key, and the receiver must dedupe duplicates (the schema even has a duplicate_of_message_id option). This guards multi-agent sequences against race conditions.
• Integrity: Use UAI-1’s integrity section to checksum and canonicalize JSON (JCS) so any tampering is detectable. Agents should log all received and sent messages with their provenances for audit.

By reusing UAIX’s existing trust/delivery features, multi-agent interactions inherit the same security posture. For example, agent A publishing a task to B and C can sign the envelope; B and C verify the signature. If B or C fail to deliver, they can be investigated via UAI audit logs.

6. Implementation Roadmap

A pragmatic rollout could proceed in stages:

1. Define Extensions in Schema: Update UAIX JSON Schema (and registry) to allow the new fields. For example, add optional "additional_targets" (array of agent objects) and permit new delivery.mode values. Use the UAIX field registry to assign URNs to any new fields or define them under “extensions”. Release this as a minor revision of UAI-1 conformance rules.
2. Update Validator and Examples: Incorporate new example packets and update the online validator to accept them. Publish sample .uai files demonstrating multi-agent flows (handoff, broadcast query, etc.).
3. Iterative Testing: Create unit tests and integration tests where, e.g., an orchestrator sends a multi-target UAI packet and verifies all recipients handle it correctly. Use keyless (positional) mode to test backward-compatibility via arrays.
4. Backward-Compatible Fallbacks: In cases where multi-target isn’t recognized, define a fallback such as “first target wins” or send separate 1:1 messages. Document this in implementation guides.
5. Agent Discovery Service: If adopting an A2A-like model, pilot a registry service (e.g. a simple HTTP endpoint hosting agent cards or capability indexes) and have agents query it using a discovery UAI message. Initially this can be out-of-band (e.g. bots querying a DB), later standardized as a UAI profile.
6. Human Approval and Trust: For tasks requiring consensus, integrate UAI’s uai.agent.blocker.v1 for escalation. Testing should cover concurrency: have two agents attempt conflicting updates and verify the protocol correctly blocks or merges them.
7. Documentation & Tooling: Update the Adoption Kit and API Reference to describe multi-agent features. Provide .NET or WP plugins (as existing tracks) to handle multi-target envelopes.
8. Incremental Rollout: Start with closed beta for known agent systems, gather feedback, and only then publish as an official UAIX recommendation (with changelog entry). Keep “Basic Envelope” mode (single target) as the stable default for most agents.

Throughout, all dates and timestamps use UTC (Z) format as UAIX already does. No performance targets are assumed, but payloads should be kept small (for efficiency), with large data passed by reference (e.g. using context_refs to share URIs) as recommended by best practices.

7. Alternative Approaches

We considered several strategies for multi-agent exchange. The table below compares them:

• Baseline UAI-1 simply uses existing 1-to-1 messages and chains conversations. It has zero risk but cannot natively multicast or discover agents. Multi-agent behavior must be orchestrated out-of-band.
• Multi-Target Envelope (our recommended approach) adds optional targets and minor mode flags. This moderately increases parser complexity (allowing a list), but old tools simply ignore new fields. It directly supports parallel delegation and broadcasts with little new logic.
• External Coordination (A2A-style) offloads discovery and routing to a separate protocol (agents use a common registry or adapter). UAI-1 stays unchanged for message payloads. This has low risk to existing systems (since .uai files stay as-is) but requires building or depending on a separate discovery/orchestration layer. Use cases like open agent marketplaces and automated delegation are fully supported via the external system.
• Pub/Sub Channels would define new profiles and semantics for subscribing/publishing to topics. This is powerful for event-driven systems but is a significant extension of UAI-1 (new fields like topic, subscriptions management, brokers). It supports multicast streaming use cases but is complex to retrofit.
• Conversation Chaining Only means using UAI-1’s parent_message_id and turn counters to link multi-party tasks (e.g. A→B→C sequences). It requires no new syntax, but works only if messages go through a chain (A→B, then B→C) and does not allow true broadcast or discovery. It’s simple but limited.

8. Recommendation

We recommend Approach B (Multi-Target Envelope) as a first step. It keeps the UAIX contract largely intact, only adding optional recipient lists and minor mode indicators. This minimizes disruption: existing tools remain functional, and validators merely need to accept the new fields. With this approach, common multi-agent use cases (delegation, notifications to several agents, parallel tasking) work natively. For discovery and rich coordination, agents can initially use out-of-band conventions or basic UAI messages (e.g. POSTing a JSON list of known agents) while UAIX formalizes a discovery profile.

In practice, agents would use UAI-1 as the public audit trail, while a separate layer (or UAIX itself via the new fields) handles addressing. This matches the UAIX vision: “UAI-1 is strongest as the public exchange and release-record layer, not as a replacement for the surrounding runtime ecosystem”. Under our proposal, agents still rely on UAIX for trust, logging, and message content; multi-agent routing and negotiation use lightweight, backward-compatible enhancements. This balances interoperability with simplicity.

Rationale: By extending UAIX minimally, we align with standards evolution patterns. As a precedent, many agent protocols (like FIPA) already allowed a list of receivers for broadcast, and UAIX’s design explicitly anticipates extensions via extensions and a flexible schema. The phased path ensures multi-agent features can be adopted gradually, with fallbacks for older systems. Security is handled by UAIX’s existing trust fields and by requiring explicit acknowledgments. Overall, this approach offers broad multi-agent support (group addressing, delegation, ack, negotiation) without abandoning backwards compatibility or re-inventing the wheel.

Sources: The above proposals draw on UAIX’s official spec and schemas and on known multi-agent communication patterns (FIPA/KQML conventions, A2A’s agent card discovery, etc.). Our design aligns with UAIX’s guidance on concurrent tasks and flexible trust and leverages its existing agent profiles. By carefully extending the plain-text .uai format, we enable robust multi-agent workflows with minimal added complexity.