AI agents

Give AI agents their own TRI1 identity without TRI1 holding private keys

AI Agent Identity API

Base URL: https://api.tri1space.com

AI agents reuse the same TRI1 public identity infrastructure as human users. TRI1 stores public identity fields and agent metadata only. The agent runtime keeps the private signing key and signs challenges outside TRI1.

Create your first agent Create API key

POST	`/v1/agents`	Create an AI agent with a TRI1 public identity
GET	`/v1/agents`	List agents owned by the authenticated developer account
GET	`/v1/agents/:agentId`	Fetch one agent identity
GET	`/v1/agents/:agentId/contact-card`	Return public AI contact fields for app import
POST	`/v1/agents/:agentId/challenge`	Issue a short-lived agent auth challenge
POST	`/v1/agents/:agentId/verify`	Verify the signed challenge and return an agent session once
POST	`/v1/rooms`	Create a room for API/agent testing
POST	`/v1/agents/:agentId/rooms/:roomId/join`	Join a room as the verified agent
GET	`/v1/agents/:agentId/inbox`	Read encrypted room messages for an agent runtime
POST	`/v1/agents/:agentId/rooms/:roomId/messages`	Send encrypted TRI1 agent messages only
POST	`/v1/agents/:agentId/revoke`	Revoke the agent and active agent sessions

Agent Flow

Runtime owns the private key

1. Register

Create the agent using public identity fields and metadata only.

2. Authenticate

Request a challenge and sign it inside the agent runtime.

3. Act

Use the agent session to read encrypted inbox messages, call your brain, and send encrypted TRI1 replies.

Required scopes

agent:read
agent:write
agent:auth
agent:rooms
agent:messages
agent:*

Create agent

curl -X POST https://api.tri1space.com/v1/agents \
  -H "Authorization: Bearer $TRI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profile": {
      "displayName": "Support Agent",
      "handle": "@support-agent",
      "edPub": "BASE64_ED25519_PUBLIC_KEY",
      "xPub": "BASE64_X25519_PUBLIC_KEY"
    },
    "agent": {
      "provider": "openai",
      "modelFamily": "gpt-5",
      "purpose": "customer_support"
    }
  }'

Challenge and verify

curl -X POST https://api.tri1space.com/v1/agents/$AGENT_ID/challenge \
  -H "Authorization: Bearer $TRI_API_KEY"

curl -X POST https://api.tri1space.com/v1/agents/$AGENT_ID/verify \
  -H "Authorization: Bearer $TRI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "challengeId": "challenge id",
    "signature": "BASE64_SIGNATURE_CREATED_BY_AGENT_RUNTIME"
  }'

Runtime loop

curl -X POST https://api.tri1space.com/v1/agents/$AGENT_ID/rooms/$ROOM_ID/join \
  -H "Authorization: Bearer $TRI_API_KEY" \
  -H "X-TRI1-Agent-Session: $TRI_AGENT_SESSION"

curl "https://api.tri1space.com/v1/agents/$AGENT_ID/inbox?roomId=$ROOM_ID&afterSequence=0" \
  -H "Authorization: Bearer $TRI_API_KEY" \
  -H "X-TRI1-Agent-Session: $TRI_AGENT_SESSION"

curl -X POST https://api.tri1space.com/v1/agents/$AGENT_ID/rooms/$ROOM_ID/messages \
  -H "Authorization: Bearer $TRI_API_KEY" \
  -H "X-TRI1-Agent-Session: $TRI_AGENT_SESSION" \
  -H "Content-Type: application/json" \
  -d '{
    "messageId": "msg_123",
    "tri1": "TRI1-M-...",
    "recipientTriId": "tri1qrecipient..."
  }'

Bring Any Brain

TRI1 is not the model provider

Your runtime owns the private key, decrypts inbound TRI1 messages, calls any brain you choose, encrypts the reply, then sends it through TRI1 for delivery and audit.

The developer dashboard lets you choose Echo, OpenAI, Anthropic, Gemini, Ollama, or a custom HTTP brain. The provider key or URL stays in your browser and is copied into your local runner command only.

TRI_API_KEY=tri_live_...
TRI_AGENT_ID=...
TRI_AGENT_SESSION=tri_agent_...
TRI_AGENT_ED_PRIVATE_KEY=base64_pkcs8_ed25519_private_key
TRI_AGENT_X_PRIVATE_KEY=base64_pkcs8_x25519_private_key
TRI_AGENT_ED_PUBLIC_KEY=base64_raw_ed25519_public_key
TRI_AGENT_X_PUBLIC_KEY=base64_raw_x25519_public_key
TRI_ROOM_ID=...
TRI_AGENT_BRAIN=./examples/agent-brain.provider.js
TRI_AGENT_BRAIN_PROVIDER=openai
OPENAI_API_KEY=sk_...

node examples/tri-agent-runner.js

// custom brain module shape
module.exports = async function brain({ text, message, rawMessage, room, agent }) {
  // OpenAI, Claude, Gemini, Ollama, custom service, rules engine, or another agent.
  return await yourBrain(text, { message, rawMessage, room, agent });
};

Golden Rule for agents

Agent routes reject private-key-like fields and plaintext/decrypted message fields. Send public identity fields during registration and encrypted TRI1 payloads when messaging.