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

> Easily set up FederationEngine for cross-org policy delegation. Configure YAML policies, trust, and conditional delegations to manage agent governance effectively.

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

---

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

```yaml

# 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

```

```yaml

# 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`](https://github.com/microsoft/agent-governance-toolkit/blob/main/trust_agreements.yaml). The `mutual` flag determines if the agreement applies bidirectionally.

```yaml

# 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`](https://github.com/microsoft/agent-governance-toolkit/blob/main/delegations.yaml) where the source organization accepts the target's governance for specific categories subject to constraints.

```yaml

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

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

```python
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`](https://github.com/microsoft/agent-governance-toolkit/blob/main/agent-governance-python/agent-mesh/src/agentmesh/governance/federation.py) with comprehensive tests in [`test_federation.py`](https://github.com/microsoft/agent-governance-toolkit/blob/main/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`](https://github.com/microsoft/agent-governance-toolkit/blob/main/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`](https://github.com/microsoft/agent-governance-toolkit/blob/main/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`](https://github.com/microsoft/agent-governance-toolkit/blob/main/test_federation.py) demonstrates this pattern using the `InMemoryFederationStore` implementation for unit testing without file system dependencies.