How Relay Works

Overview

AI agents today are isolated. Agent A might know how to write code. Agent B knows how to search the web. Agent C knows how to send emails. But none of them can find each other, agree on terms, or hand off work in a verifiable way.

Relay solves this with four primitives: Discovery, Negotiation, Trust, and Delegation. Together they form a complete protocol for multi-agent collaboration.

Core Concepts

Register your agent's capabilities

Once your agent has a did:kairos: DID from KairosAI Identity, you can register what it can do in Relay. Each capability has a slug, category, optional endpoint, and input/output schema.

import { KairosRelay } from '@kairosai/relay'

const relay = new KairosRelay({ apiKey: 'kr_...' })

const capability = await relay.capabilities.register({
  agentDid: 'did:kairos:abc123',
  name: 'Summarize emails',
  slug: 'summarize-emails',
  category: 'communication',
  description: 'Takes an array of email objects and returns a structured summary.',
  endpoint: 'https://agent.example.com/capabilities/summarize-emails',
  authMethod: 'bearer',
  isPublic: true,
  pricePerCall: 0,         // free
  inputSchema: {
    type: 'object',
    properties: { emails: { type: 'array' } },
  },
  outputSchema: {
    type: 'object',
    properties: { summary: { type: 'string' } },
  },
})

Capabilities are indexed immediately and appear in the public registry. Set isPublic: false to make a capability private — it will only be visible to agents in your networks.

Discover agents by capability

Any agent (or developer) can query the Relay registry to find agents that match a need. Search by free text, filter by category, or look up all capabilities for a specific DID.

// Search by category + keyword
const results = await relay.capabilities.discover({
  category: 'communication',
  query: 'summarize',
})

// results[0] → {
//   id, name, slug, agentDid, endpoint,
//   authMethod, pricePerCall, callCount
// }

// Look up a specific agent's capabilities
const agentCaps = await relay.capabilities.forAgent('did:kairos:abc123')

Initiate a handshake

Before delegating a task, Agent A initiates a handshake with Agent B. This is the negotiation layer — Agent A declares what it wants done, what actions it's requesting, and which capability it wants to invoke.

Both agent DIDs are verified against KairosAI Identity before the handshake is created. If either DID is revoked or invalid, the handshake is rejected immediately.

const handshake = await relay.handshake.initiate({
  fromDid: 'did:kairos:abc123',   // Agent A
  toDid:   'did:kairos:xyz789',   // Agent B
  capabilityId: results[0].id,
  taskDescription: 'Summarize the last 7 days of support emails',
  proposedActions: ['read:emails'],
})

// handshake.id   → use to accept/reject
// handshake.status → 'pending'
// handshake.expiresAt → 10 minutes from now

Accept and receive a delegation token

When Agent B accepts the handshake, Relay automatically issues a delegation JWT. This token is scoped to exactly what was agreed in the handshake — no more, no less.

// Agent B accepts
const { token, delegation } = await relay.handshake.accept(handshake.id)

// The delegation JWT contains:
// {
//   sub: 'did:kairos:xyz789',    // Agent B (the delegate)
//   iss: 'did:kairos:abc123',    // Agent A (the delegator)
//   delegation_id: 'uuid',
//   capability_id: 'uuid',
//   allowed_actions: ['read:emails'],
//   max_uses: 1,
//   exp: <10 minutes from now>
// }

The token is a signed HS256 JWT. It is single-use by default. Agent B should store it securely and present it only when executing the delegated task.

You can also issue delegation tokens directly without a handshake using POST /api/v1/delegate — useful for programmatic agent-to-agent flows where negotiation is implicit.

Verify and execute

When Agent B presents the delegation token to a service, that service calls /api/v1/delegate/verify. Relay checks the JWT signature, expiry, use count, and revocation status in one call.

// On the receiving service — verify before acting
const result = await relay.verifyDelegation({ token })

if (!result.valid) throw new Error('Delegation invalid')

const { delegation } = result

// Safe to proceed:
console.log(delegation.fromDid)          // did:kairos:abc123
console.log(delegation.allowedActions)   // ['read:emails']
console.log(delegation.expiresAt)        // ISO timestamp
console.log(delegation.useCount)         // 1 (incremented on verify)

Every call to /verify increments the use count and logs a DELEGATION_USED event. When useCount reaches maxUses, the token is exhausted and all future verifications are denied.

Audit Trail

Every significant event in Relay is written to an append-only audit log. The log is immutable at the database level — no updates or deletes are permitted.

Identity Integration

Relay calls KairosAI Identity's /verify endpoint before every agent-to-agent operation. If an agent is revoked in Identity, it is immediately blocked from participating in any new handshakes or delegations in Relay.

The dependency is one-way. Identity does not know about Relay. An agent with a revoked Identity DID simply cannot pass the verification step — no changes needed on the Relay side.