Quickstart

Build an identity-aware agent in 5 minutes.

What you'll do

1. Install the SDK
2. Create an agent instance
3. Send observations, get an ExecutionContract
4. Use the contract to control your agent's behavior

Time: ~5 minutes · Prerequisites: Python 3.8+ or Node.js 16+

---

Step 1: Install

Python SDKAPI only (no SDK)TypeScript

git clone https://github.com/Xiocasso/identity-os-api.git
cd identity-os-api && pip install -e ./sdk/python

# No install needed — use any HTTP client
curl https://api.identity-os.dev/health
# {"status":"ok"}

npm install @identity-os/sdk

Set your API key:

export IDENTITY_OS_API_KEY="idos_sk_your_key_here"

How do I get an API key?

Visit identity-os.dev → Sign up → Settings → API Keys → Create

---

Step 2: Create an Instance

An instance = one agent's identity. Create it once, send observations over time.

Pythoncurl

from identity_os_sdk import IdentityOS

client = IdentityOS(api_key="idos_sk_xxx")
instance = client.instances.create(name="MyAgent")
print(instance.id)  # inst_9f190826...

curl -X POST https://api.identity-os.dev/v1/instances \
  -H "Authorization: Bearer idos_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "MyAgent"}'

---

Step 3: Send an Observation

Tell the engine what your agent is doing. Pick a mode and signal strength:

Mode	When to use
perception	Agent is reading, analyzing, gathering info
exploration	Agent is trying new approaches, being creative
order	Agent is following procedures, being systematic
assertion	Agent is executing, making decisions
connection	Agent is collaborating, being empathetic
stress_response	Agent encountered an error, got stuck, or is under pressure

Pythoncurl

from identity_os_sdk import Mode

result = client.engine.process(
    instance_id=instance.id,
    mode_target=Mode.EXPLORATION,
    signal_strength=0.8,
)

curl -X POST https://api.identity-os.dev/v1/instances/inst_xxx/process \
  -H "Authorization: Bearer idos_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"mode_target": "exploration", "signal_strength": 0.8}'

---

Step 4: Use the ExecutionContract

The contract tells your agent what it can do right now:

contract = result.contract

# What tools are available?
print(contract.allowed_actions)
# ['explore', 'question', 'pivot', 'suggest']

# Should the agent stop?
print(contract.should_pause)     # False
print(contract.should_escalate)  # False

# How should it decide?
print(contract.decision_style)
# {'tempo': 'exploratory', 'risk': 'seeking'}

# What's its energy and stress?
print(contract.energy_level)     # 0.83
print(contract.stress_state)     # 'LOW'

Use it in your agent loop:

if contract.should_pause:
    agent.stop("Identity OS says: take a break")

elif "execute" in contract.allowed_actions:
    agent.execute_plan()

elif contract.stress_state in ("HIGH", "OVER"):
    agent.fallback_to_safe_mode()

else:
    agent.continue_normally()

---

Step 5: Multi-Turn Example

A realistic 4-turn agent session:

from identity_os_sdk import IdentityOS, Mode

client = IdentityOS(api_key="idos_sk_xxx")
agent = client.instances.create(name="Researcher")

# Turn 1: Agent reads the task
r = client.engine.process(agent.id, mode_target=Mode.PERCEPTION, signal_strength=0.7)
print(f"Energy: {r.contract.energy_level}, Actions: {len(r.contract.allowed_actions)}")

# Turn 2: Agent explores approaches
r = client.engine.process(agent.id, mode_target=Mode.EXPLORATION, signal_strength=0.85)
print(f"Tempo: {r.contract.decision_style['tempo']}")  # 'exploratory'

# Turn 3: Agent hits a problem — stress rises
r = client.engine.process(agent.id, mode_target=Mode.STRESS_RESPONSE, signal_strength=0.6)
print(f"Stress: {r.contract.stress_state}")  # 'MED' or 'HIGH'
print(f"Actions: {r.contract.allowed_actions}")  # fewer actions available

# Turn 4: Agent recovers
r = client.engine.process(agent.id, mode_target=Mode.ORDER, signal_strength=0.8)
print(f"Stress: {r.contract.stress_state}")  # back to 'LOW'

What happens: - Turn 1–2: Normal operation, full action space - Turn 3: Stress rises → risky actions removed → agent is safer - Turn 4: Recovery → actions expand back → agent continues

---

What's Next?

Understand the model

The 7 Modes → Stress Model → Drift Detection →

Integrate with your framework

Claude Agent SDK → LangGraph → CrewAI →

Go deeper

API Reference → Execution Contract → Generational Identity →