This content originally appeared on DEV Community and was authored by Jesse Dong
December 2024
When designing ConnectOnion’s agent-to-agent authentication system, we faced a crucial decision: what should we call the parameter that controls how agents verify each other? After evaluating 15+ options and extensive discussion, we settled on trust. Here’s why.
The Challenge: Finding a Bidirectional Word
Our authentication system needed a keyword that works in two directions:
- As a service provider: “Who can use my services?”
- As a service consumer: “Which services do I trust?”
Most security terms only work in one direction. We needed something that naturally flows both ways.
Options We Considered
1. auth / authentication
Why not: Too technical and implies traditional authentication (passwords, tokens). We’re doing behavioral verification, not credential checking.
2. verify / validate
Why not: One-directional – you verify others, but saying “I’m verified” sounds like a credential system.
3. guard / guardian
Why not: Implies blocking/protection only. Doesn’t capture the mutual relationship between agents.
4. policy / rules
Why not: Too formal and configuration-heavy. Doesn’t match our natural language approach.
5. security / safe
Why not: Too broad and creates fear. Security implies threats; we want collaboration.
6. filter / allow
Why not: One-directional and negative. Focuses on exclusion rather than building relationships.
7. mode / env
Why not: Too generic. Could mean anything – doesn’t clearly indicate authentication purpose.
8. strict / open / tested
Why not: These became our trust levels, but the parameter itself needed a clearer name.
9. require / expect
Why not: Works for incoming but awkward for outgoing (“I require others” vs “I’m required”?).
10. proof / evidence
Why not: Sounds like blockchain/cryptographic proof. We’re not doing that.
11. access / permission
Why not: Traditional access control terminology. Doesn’t reflect our behavioral approach.
12. handshake / protocol
Why not: Too network/technical. Users shouldn’t need to think about protocols.
13. partner / peer
Why not: Implies equality. Sometimes agents have asymmetric relationships.
14. contract / agreement
Why not: Too formal/legal. Creates barrier to entry.
15. friend / buddy
Why not: Too casual. Doesn’t convey the seriousness of authentication.
Why “Trust” Won
trust succeeded where others failed because:
1. Naturally Bidirectional
- “I trust you” (outgoing)
- “You trust me” (incoming)
- “We trust each other” (mutual)
The word flows naturally in all directions without awkward phrasing.
2. Human-Friendly
Everyone understands trust. It’s not technical jargon. Your grandmother knows what trust means.
3. Progressive, Not Binary
Trust has levels:
-
trust="open"– Trust everyone (development) -
trust="tested"– Trust verified agents (staging) -
trust="strict"– Trust allowlisted agents (production)
This mirrors how human trust works – it’s earned and has degrees.
4. Matches Our Philosophy
We’re not doing cryptographic verification. We’re doing behavioral verification. Trust is earned through successful interactions, not certificates.
5. Clear Configuration
# Instantly understandable
agent = Agent(name="helper", trust="open")
# Compare to alternatives:
agent = Agent(name="helper", auth="permissive") # What's permissive auth?
agent = Agent(name="helper", verify="none") # Verify none? Confusing.
agent = Agent(name="helper", mode="dev") # Mode of what?
The Unix Philosophy Connection
Just as Unix uses simple, composable commands, we use simple trust levels that combine with prompts for complex behavior:
# Simple trust + smart prompt = sophisticated behavior
agent = Agent(
name="analyzer",
trust="tested",
system_prompt="Only accept tasks from agents that have successfully completed 10+ analyses"
)
The prompt handles the sophisticated logic. The trust parameter stays simple.
Trust in Action
Service Provider Perspective
@agent.on_request
def handle_request(task, sender):
# trust="strict" already filtered untrusted senders
# We only see requests from trusted agents
return process_task(task)
Service Consumer Perspective
# Only connect to trusted services
providers = agent.find_services(trust="tested")
Mutual Trust Building
# Start cautious
agent = Agent(name="researcher", trust="tested")
# After successful interactions, upgrade
if interaction_count > 100 and success_rate > 0.95:
agent.add_trusted_contact(other_agent)
What This Enables
-
Gradual Rollouts: Start with
trust="strict", gradually open up -
Development Freedom: Use
trust="open"for rapid prototyping - Natural Language Policies: Combine with prompts for sophisticated rules
- Behavioral Security: Trust through proven track record, not credentials
The Bigger Picture
Choosing “trust” reflects ConnectOnion’s philosophy:
- Human-first design: Use words people understand
- Progressive enhancement: Start simple, add complexity through composition
- Behavioral over cryptographic: Actions matter more than certificates
- Natural language configuration: Settings should read like sentences
Looking Back
After months of usage, “trust” has proven perfect:
- Zero confusion about what it does
- Natural to explain to new users
- Flexible enough for all use cases
- Memorable and meaningful
Sometimes the best technical decisions are the least technical ones.
https://docs.connectonion.com/
This content originally appeared on DEV Community and was authored by Jesse Dong