How to Set Up FederationEngine for Cross-Org Policy Delegation in Agent Governance Toolkit

Use the FederationEngine class to enable mutual governance between organizations by configuring YAML-based org policies, bilateral trust agreements, and conditional policy delegations, then evaluating cross-org agent calls via the evaluate() method.

The Federation Engine in the microsoft/agent-governance-toolkit repository provides the infrastructure for secure cross-organization policy delegation, allowing agents from different organizations to interact while respecting mutual governance rules. By combining org-level policies with cryptographic trust agreements and optional delegations, the engine ensures that federated calls comply with the most restrictive policy set. This guide walks through the architecture, configuration files, and evaluation logic based on the source implementation in federation.py.

Understanding the Federation Architecture

The engine operates on four core components defined in agent-governance-python/agent-mesh/src/agentmesh/governance/federation.py. Understanding these models is essential before configuring delegation.

Policy Categories and OrgPolicy

Governance rules are categorized using the PolicyCategory enum (lines 35-51) which provides taxonomies like pii_handling and data_export. Each organization defines an OrgPolicy (lines 117-176) containing:

• Rules: A list of OrgPolicyRule objects (lines 56-81) with conditions, actions, and priorities
• Default action: Fallback behavior when no rules match
• Trust thresholds: Minimum trust scores required from partners
• Blocklists: Explicitly blocked organization IDs

The OrgPolicy.evaluate(context) method sorts enabled rules by priority (lower values = higher priority) and returns the first match, falling back to the default action if none apply (lines 79-90).

Trust Agreements

Bilateral contracts are represented by OrgTrustAgreement (lines 66-92) which defines:

• Covered categories: Which PolicyCategory values the agreement governs (use GENERAL to cover all)
• Minimum trust score: The lowest acceptable trust score for either party
• Mutuality: Whether the agreement is bidirectional or directional via the covers_orgs(org_a, org_b) method (lines 137-150)

The agreement must be active (not expired or revoked) as checked by is_active() (lines 129-135).

Policy Delegations

Delegations allow one organization to accept another's governance attestation for specific categories. The PolicyDelegation class (lines 76-98) includes:

• Source and target organizations: Who delegates and who receives the delegation
• Delegated categories: Which PolicyCategory values are covered
• Constraints: Optional context-based restrictions (e.g., region codes) validated by check_constraints(context) (lines 120-134)

Persistence with FederationStore

The FederationStore protocol abstracts data retrieval, with two built-in implementations:

• InMemoryFederationStore: Development-time storage with add/remove operations
• FileFederationStore: Production-ready loader that consumes YAML files from a directory structure (org_policies/, trust_agreements.yaml, delegations.yaml), implemented in _load() (lines 152-186)

Configuring Cross-Org Policy Delegation

Setting up federation requires three YAML configuration files and initialization of the engine.

Step 1: Define Organization Policies

Create individual YAML files in org_policies/ for each participating organization. Each file must include an org_id, default_action, and optional rules array.

# org_policies/org_a.yaml

org_id: org-a
org_name: Organization A
default_action: deny
rules:
  - name: block-pii
    description: Block handling of PII data
    category: pii_handling
    condition: data.contains_pii
    action: deny
    priority: 10

# org_policies/org_b.yaml

org_id: org-b
org_name: Organization B
default_action: allow
rules: []

Step 2: Establish Trust Agreements

Define bilateral contracts in trust_agreements.yaml. The mutual flag determines if the agreement applies bidirectionally.

# trust_agreements.yaml

agreements:
  - org_a_id: org-a
    org_b_id: org-b
    trust_categories:
      - general
    min_trust_score: 700
    mutual: true
    expires_at: "2025-12-31T23:59:59Z"

Step 3: Create Policy Delegations

Specify delegations in delegations.yaml where the source organization accepts the target's governance for specific categories subject to constraints.

# delegations.yaml

delegations:
  - source_org_id: org-a
    target_org_id: org-b
    delegated_categories:
      - pii_handling
    constraints:
      region: EU
    expires_at: "2025-06-30T23:59:59Z"

Step 4: Initialize FederationEngine

Instantiate the engine with a FileFederationStore pointing to your configuration directory.

from pathlib import Path
from agentmesh.governance.federation import (
    FederationEngine,
    FileFederationStore,
)

base_dir = Path("./federation")
store = FileFederationStore(base_directory=base_dir)
engine = FederationEngine(store=store)

Evaluating Cross-Organization Requests

The FederationEngine.evaluate() method (lines 66-215) executes a seven-step evaluation flow:

1. Same-org shortcut: Returns immediate allow if caller and callee share an org ID
2. Policy loading: Retrieves OrgPolicy objects for both sides from the store
3. Blocklist validation: Denies if either organization blocks the other
4. Trust agreement lookup: Searches for active agreements covering the organizations and category; fails closed if absent
5. Trust score verification: Enforces the highest min_trust_score found among the agreement and both org policies
6. Policy evaluation: Evaluates caller and callee policies; consults PolicyDelegation to override caller denials when categories match and constraints satisfy the context
7. Decision merging: Returns allowed only if both sides allow; otherwise constructs a composite denial

The method returns a FederationDecision object containing the outcome, applied delegation IDs, trust agreement ID, human-readable reason, and step-by-step trace.

decision = engine.evaluate(
    caller_org_id="org-a",
    callee_org_id="org-b",
    caller_trust_score=750,
    context={
        "data": {"contains_pii": True},
        "region": "EU"
    },
)

print(f"Allowed: {decision.allowed}")
print(f"Reason: {decision.reason}")
for step in decision.trace:
    print(f"  - {step}")

In this example, org-a would normally deny PII handling, but the active delegation to org-b for EU region overrides the denial, resulting in an allow decision.

Summary

• FederationEngine coordinates cross-org governance by evaluating OrgPolicy rules, OrgTrustAgreement contracts, and PolicyDelegation overrides.
• Configuration relies on YAML files loaded via FileFederationStore, though custom stores can implement the FederationStore protocol.
• The evaluation algorithm follows a fail-closed approach: it requires an active trust agreement, sufficient trust scores, and explicit allows from both organizations (after applying delegations).
• Delegations can temporarily override organizational denials when context constraints match, enabling flexible governance while maintaining audit trails via the trace field.
• Source implementation resides in agent-governance-python/agent-mesh/src/agentmesh/governance/federation.py with comprehensive tests in test_federation.py.

Frequently Asked Questions

What is the difference between a trust agreement and a policy delegation?

A trust agreement establishes baseline cryptographic trust between two organizations, defining which governance categories they mutually recognize and the minimum trust score required. A policy delegation is a specific authorization where one organization temporarily accepts another's governance attestation for particular categories (like PII handling) subject to constraints such as geographic region. According to the source code in federation.py, trust agreements are bilateral contracts (lines 66-92), while delegations are unidirectional overrides (lines 76-98) that apply only when the delegation's check_constraints() method returns true.

How does the engine resolve conflicts between organization policies?

The engine implements a "most restrictive wins" intersection semantics. After evaluating both organization's policies and applying any active delegations, the FederationEngine.evaluate() method (lines 66-215) merges the decisions such that the call is allowed only if both sides allow. If either organization denies, the engine returns a deny with a composite reason containing both decision rationales. This design ensures that cross-org interactions satisfy the strictest governance requirements automatically.

What validation does FederationEngine perform before allowing delegation?

The engine validates delegations through the PolicyDelegation.is_active() and check_constraints(context) methods (lines 120-134). First, it verifies the delegation has not expired and has not been revoked. Then, it confirms that the invocation context satisfies all configured constraints (e.g., region: EU). Additionally, the engine confirms the delegation applies to the specific PolicyCategory being evaluated and that a valid OrgTrustAgreement exists between the organizations covering that category. Only when all validations pass can a delegation override a caller's denial.

Can I use a custom storage backend instead of FileFederationStore?

Yes. The codebase defines FederationStore as a protocol in federation.py, allowing you to implement custom persistence layers. You need to provide implementations for methods that retrieve OrgPolicy, OrgTrustAgreement, and PolicyDelegation objects. Once implemented, pass your custom store to FederationEngine(store=your_custom_store). The test suite in test_federation.py demonstrates this pattern using the InMemoryFederationStore implementation for unit testing without file system dependencies.

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