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

> Implement TrustHandshake protocol with IATP for secure agent communication. Verify identities, calculate trust scores, and enforce policies using the Agent Governance Toolkit.

- Repository: [Microsoft/agent-governance-toolkit](https://github.com/microsoft/agent-governance-toolkit)
- Tags: how-to-guide
- Published: 2026-05-29

---

**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`](https://github.com/microsoft/agent-governance-toolkit/blob/main/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`](https://github.com/microsoft/agent-governance-toolkit/blob/main/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`.

```go
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.

```bash

# 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.

```go
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.

```go
// 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`](https://github.com/microsoft/agent-governance-toolkit/blob/main/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.

```go
// 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`](https://github.com/microsoft/agent-governance-toolkit/blob/main/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`](https://github.com/microsoft/agent-governance-toolkit/blob/main/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`](https://github.com/microsoft/agent-governance-toolkit/blob/main/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`](https://github.com/microsoft/agent-governance-toolkit/blob/main/trust.go) validates both the key format and the associated cryptographic signatures during the handshake process.