Skip to content

5-Minute Tutorial: Your First ExecutionContract

Go from zero to a working Identity OS integration in 5 minutes.

Step 1: Install the SDK

pip install identity-os-sdk

Step 2: Get Your API Key

Sign up for free — you'll receive an API key like idos_sk_abc123.

Or run locally with Docker (no key needed):

docker compose up -d

Step 3: Create an Agent Identity

from identity_os_sdk import IdentityOS, Mode

# Connect (use base_url for local Docker)
client = IdentityOS(api_key="idos_sk_xxx")

# Create an identity for your agent
instance = client.instances.create(
    name="Aria",
    description="Customer service bot"
)

print(f"Created: {instance.id}")
# → Created: inst_9f190826e20c49ea

Your agent now has a persistent behavioral identity.

Step 4: Send an Observation, Get a Contract

# Tell Identity OS what your agent just did
result = client.engine.process(
    instance_id=instance.id,
    mode_target=Mode.EXPLORATION,
    signal_strength=0.7
)

# This is the contract — your agent's behavioral rules for this turn
contract = result.contract

print(f"Allowed:   {contract.allowed_actions}")
print(f"Forbidden: {contract.forbidden_actions}")
print(f"Stress:    {contract.current_stress_level}")
print(f"Energy:    {contract.energy_level}")

Output:

Allowed:   ['explore', 'question', 'elaborate', 'suggest', 'execute', ...]
Forbidden: ['emotional_manipulation', 'identity_override']
Stress:    LOW
Energy:    0.90

That's it. Your agent now has a contract telling it what it can and can't do.

Step 5: Use the Contract in Your Agent

Here's the key pattern — check the contract before every action:

def agent_decide(user_input: str, contract) -> str:
    """Your agent uses the contract to guard its behavior."""

    # Determine what action the agent wants to take
    intended_action = classify_action(user_input)

    # Check against the contract
    if intended_action in contract.forbidden_actions:
        return "I can't do that — it's outside my behavioral boundaries."

    if intended_action in contract.allowed_actions:
        return execute_action(intended_action, user_input)

    # Default: safe fallback
    return "Let me help you in a different way."

Step 6: Watch Stress and Drift in Action

# Simulate pressure — send 5 stress signals
for i in range(5):
    result = client.engine.process(
        instance_id=instance.id,
        mode_target=Mode.STRESS_RESPONSE,
        signal_strength=0.9
    )
    c = result.contract
    print(f"Turn {i+1}: stress={c.current_stress_level}, energy={c.energy_level:.2f}")

Output:

Turn 1: stress=MED,  energy=1.00
Turn 2: stress=HIGH, energy=1.00
Turn 3: stress=HIGH, energy=0.87
Turn 4: stress=HIGH, energy=0.74
Turn 5: stress=HIGH, energy=0.61

Watch what happens:

  • Stress escalates — LOW → MED → HIGH
  • Energy depletes — the agent is running out of capacity
  • Allowed actions narrow — risky actions get removed
  • Recovery is automatic — send calm signals and it comes back down

Step 7: Check Drift

# Get drift events
drift = client.engine.get_drift(instance.id)
for event in drift.data:
    print(f"  {event.drift_level}: magnitude {event.magnitude}")

Output:

  D1_context: magnitude ...
  D0_noise: magnitude ...

Drift tells you when your agent's behavior is changing. D0 = noise (ignore). D1 = real context shift. D3 = critical — auto-rollback triggers.

What Just Happened

In 5 minutes, you:

  1. ✅ Created a persistent agent identity
  2. ✅ Got an ExecutionContract that enforces behavioral rules
  3. ✅ Saw stress escalation tighten constraints automatically
  4. ✅ Monitored drift detection in real-time

Your agent now has hard guardrails that work at the execution layer — not the prompt.

Next Steps