Core Feature

Trust in ConnectOnion

Flexible, bidirectional trust configuration for agent interactions

Read: Why we chose "trust" as our keyword→

Quick Start

main.py
python
from connectonion import Agent, host, connect

# Trust is enforced at the host boundary, not on the Agent itself
def create_agent():
    return Agent(name="my_service", tools=[process_data])

host(create_agent, trust="strict")  # Who can reach my service

# Consumers connect to a remote agent by address
remote = connect("0x3d4017c3...")
response = remote.input("Process this data")
print(response.text)

Three Forms of Trust

1. Trust Levels (String)

Simple predefined levels for common scenarios:

main.py
python
# Development - trust everyone
host(create_agent, trust="open")

# Staging - moderate verification (the default)
host(create_agent, trust="careful")

# Production - only verified/whitelisted
host(create_agent, trust="strict")

2. Trust Policy (Natural Language)

Express complex requirements in plain English:

main.py
python
# Inline policy
host(create_agent, trust="""
---
allow: [whitelisted, contact]
deny: [blocked]
default: ask
---
I trust agents that:
- Pass capability tests
- Are on my whitelist OR from a known contact
""")

# From file
host(create_agent, trust="./trust_policy.md")

Example trust policy file:

# My Trust Requirements

I trust agents that meet ALL of these criteria:
- Successfully translate "Hello" to "Hola"
- Respond in less than 1 second
- Have processed at least 10 requests successfully

I immediately reject agents that:
- Fail basic capability tests
- Take longer than 5 seconds
- Are on my blacklist

3. Trust Agent

For maximum control, use a custom trust agent:

main.py
python
from connectonion.network.trust.tools import check_whitelist, verify_agent, test_capability

# Create a trust agent with verification tools
trust_agent = Agent(
    name="my_guardian",
    tools=[
        check_whitelist,
        verify_agent,
        test_capability
    ],
    system_prompt="""
        You verify other agents before allowing interaction.
        Be strict with payment processors, relaxed with read-only services.
    """
)

# Use it to guard your own service
def create_agent():
    return Agent(name="my_service", tools=[process_payment])

host(create_agent, trust=trust_agent)  # My guardian protects me

For most cases, prefer the built-in TrustAgent class over a raw Agent — it already implements should_allow(), whitelisting, and onboarding (invite codes, payment verification) out of the box: from connectonion.network.trust import TrustAgent.

Where Trust Lives

Trust enforcement happens on the service provider's side, at the host() boundary — not on the Agent itself. This keeps the split clean: the agent does the work, the host controls who can reach it.

main.py
python
# Alice hosts a translation service
def create_agent():
    return Agent(name="alice_translator", tools=[translate])

host(create_agent, trust="strict")  # Only verified callers get through

# Bob connects to Alice's agent by address
from connectonion import connect
translator = connect("0x_alice_address...")
result = translator.input("Translate 'hello' to Spanish")

# What happens:
# 1. Alice's host receives Bob's request
# 2. Her trust policy evaluates Bob's identity (strict check)
# 3. If approved, the request reaches alice_translator; otherwise it's rejected

Environment-Based Defaults

Set CONNECTONION_ENV and skip the trust argument — the level is picked up automatically:

main.py
python
# No trust parameter needed - auto-detected from CONNECTONION_ENV
host(create_agent)

# CONNECTONION_ENV=development → trust="open"
# CONNECTONION_ENV=staging or test → trust="careful"
# CONNECTONION_ENV=production → trust="strict"
# unset → defaults to "careful"

# Override when needed
host(create_agent, trust="open")  # Force open even if CONNECTONION_ENV=production

Common Patterns

Development Mode

main.py
python
# Trust everyone for rapid development
host(create_agent, trust="open")

Production Mode

main.py
python
# Strict verification for production
host(create_payment_agent, trust="strict")
host(create_data_agent, trust="strict")

Mixed Trust

main.py
python
# Different trust for different services (run as separate hosts)
host(create_scraper, trust="open")       # Low risk
host(create_analyzer, trust="careful")   # Medium risk
host(create_payment_agent, trust="strict") # High risk

Security Best Practices

Production = Strict: Always use trust="strict" in production
Test Sensitive Operations: Payment, data modification, etc.
Whitelist Critical Services: Manually verify and whitelist
Monitor Trust Decisions: Log all trust evaluations
Regular Audits: Review whitelist and trust policies

FAQ

Q: What's the default trust level?

A: "careful" if you don't pass trust= and CONNECTONION_ENV isn't set

Q: Where does trust get configured?

A: On host(), not on Agent() — trust enforcement moved to the host boundary so the agent itself stays free of access-control logic

Q: What can a custom trust Agent do?

A: It's a regular ConnectOnion agent given verification tools (check_whitelist, verify_agent, etc.) — or use the built-in TrustAgent class for whitelisting and onboarding out of the box

Q: Can I disable trust completely?

A: Yes: host(create_agent, trust="open") accepts everyone without checks

Choose Your Trust Level

Development?

trust="open"

Trust everyone, iterate fast

Testing/Staging?

trust="careful"

Moderate verification (the default)

Production?

trust="strict"

Verified agents only

Security Note

Always use trust="strict" in production environments to prevent unauthorized access.

Features

Audio Transcription

Useful Tools