DiscoveryKit

DiscoveryKit is the nearby device discovery service in AgentOS.
It allows third-party apps to discover other AgentOS devices and app instances on the same local network.

What it solves

DiscoveryKit handles:

• Registering the current app as a discoverable node
• Discovering nearby AgentOS devices and registered apps
• Retrieving device info (device ID, name, type, online status)
• Real-time SSE monitoring of device join/leave events
• Getting self device info and registration status

Best fit

• You want to implement cross-device pairing
• You need to select a target device before sending files
• You are building multi-device collaboration features
• You want to show users a "nearby available devices" list

Core capabilities

Register as discoverable

After obtaining identity through AuthKit, an app can register itself with DiscoveryKit:

• SDK (TypeScript): sdk.discoverykit.register(bearerToken, { receivePolicy: 'autoAccept' })
• SDK (Python): await sdk.discoverykit.register(bearer_token, {"receivePolicy": "autoAccept"})
• HTTP: POST /discoverykit/register

Available receivePolicy options:

Policy	Description
autoAccept	Automatically accept incoming files
requireConfirm	Require manual confirmation before each receive

Discover nearby devices

• SDK: sdk.discoverykit.getPeers(bearerToken)
• HTTP: GET /discoverykit/peers

Returned PeerDevice includes:

• deviceId: unique device identifier
• name: display name
• deviceName: system device name
• deviceType: device type
• host / port: device address
• online: whether the device is online
• apps: registered apps with the same bundleId on that device

Real-time device events

Continuously receive device join/leave events via SSE:

• SDK: sdk.discoverykit.streamPeers(bearerToken)
• HTTP: GET /discoverykit/peers/stream

Event types: joined, updated, left

Get self info

• SDK: sdk.discoverykit.getSelf(bearerToken)
• HTTP: GET /discoverykit/self

Returns current device info and registration status.

Unregister

• SDK: sdk.discoverykit.unregister(bearerToken)
• HTTP: POST /discoverykit/unregister

Scan levels

DiscoveryKit distinguishes two scan levels:

• Device-level (callerBundleId is empty): returns device info only, no app list
• App-level (callerBundleId is set): returns only apps with the same bundleId, for app-to-app pairing

Relationship with AuthKit

DiscoveryKit depends on AuthKit for user identity:

• username and avatarUrl come from the AuthKit user profile
• userId comes from the AuthKit grant
• Apps are automatically unregistered when they go offline

When you may not need DiscoveryKit

• You only make cloud API calls without local network device communication
• You do not need cross-device features
• Your app runs in environments without a local network

Next steps

• After discovering devices, for file transfer: see TransferKit
• To obtain user identity first: see AuthKit
• To register your app: see AppKit