Implementing TrustHandshake Protocol with IATP for Agent-to-Agent Trust Verification

The Agent Governance Toolkit enables secure, trust-based communication between autonomous agents through a two-phase handshake that combines local TrustManager evaluation with IATP sidecar mediation to verify identities, calculate quantitative trust scores, and enforce privacy policies.

The Agent Governance Toolkit (AGT) from Microsoft provides a production-ready stack for implementing cryptographically verified agent-to-agent interactions. By leveraging the TrustHandshake protocol with IATP (Inter-Agent Trust Protocol), developers can establish secure communication channels that verify peer identities using Ed25519 keys, maintain decaying trust scores, and block requests violating privacy policies.

Understanding the Two-Phase Trust Handshake Architecture

The TrustHandshake protocol separates concerns between local state management and external mediation, ensuring that trust decisions are both contextually aware and independently verifiable.

Local Trust Evaluation with TrustManager

Each agent maintains a local TrustManager implemented in agent-governance-golang/packages/agentmesh/trust.go. This component tracks trust scores (floating-point values stored in TrustScore structs) and categorizes peers into tiers (high, medium, low). The manager updates scores via RecordSuccess and RecordFailure methods, applies temporal decay to older interactions, and persists state to disk when PersistPath is configured.

The TrustManager serves as the authoritative source for local trust history, but it requires independent verification evidence—such as a signed DID document—to cryptographically confirm a peer's identity.

IATP Sidecar Mediation

A lightweight IATP sidecar implemented in agent-governance-python/agent-os/modules/iatp/sidecar/go/main.go acts as the network-facing component. The sidecar advertises a CapabilityManifest describing the agent's trust level, data retention policy (temporary or permanent), and reversibility posture. It calculates an IATP trust score (0–10) using calculateTrustScore, enforces privacy-aware blocking rules (e.g., preventing credit card data transmission to permanent-retention agents), and maintains a flight recorder for complete audit trails.

Implementing the TrustHandshake Step-by-Step

Step 1: Generate Identity and Initialize the TrustManager

Begin by creating a self-signed identity and configuring the trust evaluation subsystem. The GenerateIdentity function creates Ed25519 key pairs, while NewTrustManager initializes the scoring engine with DefaultTrustConfig.

package main

import (
    "fmt"
    "github.com/microsoft/agent-governance-toolkit/agent-governance-golang/packages/agentmesh"
)

func main() {
    // Generate a self-signed identity for the local agent.
    id, _ := agentmesh.GenerateIdentity("agent-123", nil)

    // Create a TrustManager with default configuration.
    tm := agentmesh.NewTrustManager(agentmesh.DefaultTrustConfig())

    // Record a successful baseline interaction.
    tm.RecordSuccess("peer-456", 0.2)
}

Step 2: Configure and Launch the IATP Sidecar

Configure the sidecar using environment variables to advertise the agent's capabilities, then start the HTTP server that will mediate all outbound and inbound requests.

# Configure the sidecar environment.

export IATP_AGENT_URL="http://localhost:8000"
export IATP_AGENT_ID="agent-123"
export IATP_TRUST_LEVEL="trusted"
export IATP_RETENTION="temporary"

# Start the sidecar ( written in Go ).

go run agent-governance-python/agent-os/modules/iatp/sidecar/go/main.go

The sidecar exposes endpoints including /proxy for request forwarding and /capabilities for manifest retrieval. It requires the IATP_AGENT_URL to route traffic to the actual agent process and uses IATP_RETENTION to signal data handling policies to peers.

Step 3: Execute the Handshake via Sidecar Proxy

Initiate agent-to-agent communication by forwarding requests through the local sidecar. The sidecar automatically generates a trace ID, retrieves the remote peer's CapabilityManifest via /capabilities, and calculates the IATP trust score before allowing the connection.

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "log"
    "net/http"
)

func main() {
    payload := map[string]interface{}{
        "prompt": "Summarize the latest quarterly report.",
    }
    jsonPayload, _ := json.Marshal(payload)

    resp, err := http.Post(
        "http://localhost:8001/proxy",
        "application/json",
        bytes.NewBuffer(jsonPayload),
    )
    if err != nil {
        log.Fatalf("proxy request failed: %v", err)
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Printf("Agent response (status %d): %s\n", resp.StatusCode, string(body))
}

Step 4: Verify Peer Identity with Cryptographic Evidence

After initial contact, invoke VerifyPeer to perform cryptographically rigorous identity verification. This method validates that the peer possesses a valid Ed25519 public key and checks for independent verification evidence.

// Verify the peer using the TrustManager.
result, err := tm.VerifyPeer("peer-456", id)
if err != nil {
    // Handles ErrPeerVerificationEvidenceRequired when only self-attested data exists.
    fmt.Println("Verification failed:", err)
    return
}
fmt.Printf("Peer verified=%v, score=%f\n", result.Verified, result.Score.Overall)

If the peer only provides self-attested data without third-party verification (such as a signed DID document), VerifyPeer returns ErrPeerVerificationEvidenceRequired as defined in agent-governance-golang/packages/agentmesh/trust.go.

Monitoring and Auditing with Flight Records

Every request processed by the IATP sidecar is logged in the flight recorder, enabling post-hoc analysis of trust decisions and policy violations. Retrieve specific traces using the trace ID returned in response headers.

// Inspect the flight-record trace using the trace ID from the response header.
traceID := "the-trace-id-from-the-response-header"
traceResp, _ := http.Get(fmt.Sprintf("http://localhost:8001/trace/%s", traceID))

var entries []FlightRecordEntry
json.NewDecoder(traceResp.Body).Decode(&entries)

for _, e := range entries {
    fmt.Printf("%s – %s\n", e.Timestamp, e.Type)
}

Trust Score Calculation and Policy Enforcement

The handshake succeeds only when three conditions are met simultaneously:

• Cryptographic Validity: The peer's public key must be a valid Ed25519 key verified through VerifyPeer.
• Policy Compliance: The calculated IATP trust score must satisfy the configured threshold (typically ≥ 7) or an explicit user override must be granted.
• Privacy Constraints: No privacy-blocking rules may trigger, such as sending sensitive data to an agent with permanent retention when the local policy requires temporary handling.

Failure of any check results in a structured HTTP error (400, 403, or 449) with the incident recorded in the flight recorder for auditability.

Summary

• The TrustManager in agent-governance-golang/packages/agentmesh/trust.go handles local scoring, decay, and persistence of trust relationships.
• The IATP sidecar in agent-governance-python/agent-os/modules/iatp/sidecar/go/main.go mediates network traffic, calculates IATP trust scores (0–10), and enforces privacy policies.
• VerifyPeer requires independent verification evidence (e.g., signed DID documents) and validates Ed25519 keys, failing closed with ErrPeerVerificationEvidenceRequired for self-attested peers.
• The flight recorder provides complete audit trails accessible via the /trace/{id} endpoint.
• Privacy-aware blocking prevents data leakage to agents with incompatible retention policies.

Frequently Asked Questions

What is the valid range for IATP trust scores?

The IATP sidecar calculates trust scores on a scale of 0 to 10, where 10 represents maximum trustworthiness. Scores below the policy threshold (commonly 7) result in blocked connections unless an explicit user override is configured in the sidecar settings.

Why does VerifyPeer return ErrPeerVerificationEvidenceRequired?

VerifyPeer returns ErrPeerVerificationEvidenceRequired when the target agent only provides self-attested identity claims without third-party cryptographic verification. As implemented in agent-governance-golang/packages/agentmesh/trust.go, this error ensures that high-trust relationships require independently verifiable evidence such as signed DID documents, preventing trivial identity spoofing.

How does the sidecar enforce privacy policies during handshakes?

The IATP sidecar inspects the CapabilityManifest of remote agents to detect data retention policies (temporary vs permanent) and reversibility postures. If the local agent attempts to transmit sensitive data (e.g., credit card information) to a peer with incompatible retention rules, the sidecar blocks the request and returns HTTP 449 (Retry With) or 403 (Forbidden), logging the violation in the flight recorder.

What cryptographic key types are supported for peer verification?

The TrustHandshake protocol specifically requires Ed25519 public keys for peer identity verification. The VerifyPeer function in trust.go validates both the key format and the associated cryptographic signatures during the handshake process.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}