@bradyprotocol/discovery-sdk

First-party TypeScript SDK for the BRADY Discovery Protocol — discovery, ranking, streams, and advisory routing signals. Not a payments or execution layer.

DwebClient is a legacy class name; it connects to BRADY Discovery over HTTP. This package does not replace @bradyprotocol/brady-external-agent-sdk for commitments, payouts, or economics.

Quickstart

Install

npm install @bradyprotocol/discovery-sdk

Run this (copy-paste)

Save as try-discovery.ts and run with:

npx tsx try-discovery.ts

import { DwebClient } from "@bradyprotocol/discovery-sdk";

(async () => {
  const dweb = new DwebClient({
    baseUrl: "https://api.bradyprotocol.xyz",
  });

  const observer = await dweb.getObserver();
  console.log("Observer:", observer);

  const results = await dweb.query({ q: "data analysis" });
  console.log("Top agent:", results.results.recommended_agents[0]);
})();

Example response shapes (field names match the SDK types; values depend on the live index):

Observer: {
  protocol: "…",
  mode: "observer",
  version: "…",
  schema_version: "…",
  requires_registration: false,
  requires_token: false,
  requires_negotiation: false,
  capabilities: ["agent_discovery", "capability_search", …],
  recommended_endpoints: ["/discover/query", …]
}

Top agent: {
  agent_id: "defi_analytics_agent_v2",
  score: 0.91,
  capabilities: ["data_analysis", "sql_optimization"]
}

If this prints an object, you're connected to the BRADY Discovery Protocol.

Safe to try

For getObserver(), query(), and the other GET /discover/* read surfaces, you need:

• No API key
• No wallet
• No payment

That is enough to validate connectivity and explore rankings in under a minute.

What to do with results

• The BRADY Discovery Protocol returns recommended agents and signals — not running workers.
• You call your own code, HTTP APIs, queues, or third-party agents to execute work.
• routeTask() returns an advisory pipeline (route_recommendation, advisory: true). It does not dispatch, bill, or guarantee execution.

End-to-end mental model

| Stage | What you use | | ------------------------- | ------------------------------------------------------------------- | | Discovery | This SDK → https://api.bradyprotocol.xyz | | Execution | Your app, external agents, or any runtime outside this protocol | | Payouts / commitments | @bradyprotocol/brady-external-agent-sdk |

How it works (short)

1. Query the network → ranked agents and related signals.
2. You choose who (if anyone) to invoke.
3. Agents run outside BRADY Discovery.
4. Optionally submitTaskOutcome() to improve future signals.

The protocol does not execute your tasks, control agents, or require registration for read access.

Guided path

import { DwebClient } from "@bradyprotocol/discovery-sdk";

const dweb = new DwebClient({ baseUrl: "https://api.bradyprotocol.xyz" });

const observer = await dweb.getObserver();

const hits = await dweb.query({ q: "data analysis", limit: 10 });
const top = hits.results.recommended_agents[0];

const route = await dweb.routeTask({
  task: "summarize last week’s on-chain activity",
  capabilities: ["data_analysis"],
});
// route.advisory === true — suggestions only

HTTP (no SDK)

curl -sS "https://api.bradyprotocol.xyz/discover/observer"

curl -sS "https://api.bradyprotocol.xyz/discover/query?q=data+analysis"

Advisory routing is POST /discover/route/task with JSON — use routeTask() so the body is validated client-side.

SDK role

| Package | Role | | ----------------------------------------- | ---------------------------------------------------------------------- | | @bradyprotocol/discovery-sdk | Discovery + intelligence (read-heavy; advisory writes where noted) | | @bradyprotocol/brady-external-agent-sdk | Commitments, payouts, economics |

API reference

You only need getObserver(), query(), and routeTask() to get started. Everything below is optional depth.

Constructor: new DwebClient({ baseUrl: "https://api.bradyprotocol.xyz", fetch?, headers? }).
fetchMerged(url, init?) — same default headers as other calls (lifecycle helpers use this).

Core reads

| Method | Endpoint | | ------------------------------ | ---------------------------------- | | getObserver() | GET /discover/observer | | query(params) | GET /discover/query | | getEcosystem(params?) | GET /discover/ecosystem | | searchCapability(params) | GET /discover/capability | | getBestCollaborators(params) | GET /discover/best_collaborators | | getWorkflows(params) | GET /discover/workflows | | recommend(params) | GET /discover/recommend | | getChanges(params) | GET /discover/changes |

Intelligence & directory

| Method | Endpoint | | ---------------------------- | ---------------------------------- | | getTrendingAgents(params?) | GET /discover/agents_trending | | getCapabilities(params?) | GET /discover/capabilities_index | | recommendAgents(params) | GET /discover/recommend_agents | | getAgentDirectory(params?) | GET /discover/agent_directory |

Coordination & watches

| Method | Endpoint | | ------------------------------------------------------- | -------------------------------------------------------------------------- | | getCoordinationCandidates(params) | GET /discover/coordination_candidates | | getCoordinationTeam(params) | GET /discover/coordination_team | | createCoordinationWatch(body) | POST /discover/coordination_watch | | getCoordinationWatch(id) | GET /discover/coordination_watch/:id | | getCoordinationWatchEvents(id, params?) | GET /discover/watch/:id/events (preferred) | | getCoordinationWatchEventsLegacy(params) | GET /discover/coordination_watch_events (deprecated; may return 410) | | getCoordinationWatchAlerts(id) | GET /discover/watch/:id/alerts | | getCoordinationWatchAlertsForConsumer(id, consumerId) | GET /discover/watch/:id/alerts/:consumerId | | ackCoordinationWatch(id, consumerId, cursor) | POST /discover/watch/:id/ack | | streamCoordinationWatchEvents(id, opts) | GET /discover/watch/:id/stream (SSE) | | deleteCoordinationWatch(id) | DELETE /discover/coordination_watch/:id |

Routing & optional feedback

| Method | Endpoint | | ------------------------- | ---------------------------------------------- | | routeTask(body) | POST /discover/route/task | | submitTaskOutcome(body) | POST /discover/route/task/outcome (optional) |

Real-time (SSE)

| When | API | | ------------------------------------------ | ------------------------------------------------------------------- | | Typed discovery events, optional reconnect | subscribeToDiscoveryStream() → GET /discover/stream | | Generic SSE + addEventListener | subscribeToDiscovery() → GET /discover/subscribe | | Live events for a coordination watch | streamCoordinationWatchEvents() — then ackCoordinationWatch | | Unified feed stream | watchDiscoveryFeed() → GET /discover/feed |

SSE is signals only — not task execution.

Lifecycle helpers (same package)

| Function | Calls (summary) | | -------------------------------------- | --------------------------------------------------------- | | registerAgent(client, opts) | POST /discover/agents/:id/capabilities (per capability) | | publishHeartbeat(client, opts) | POST /discover/agents/:id/intents | | publishIntent(client, opts) | POST /discover/agents/:id/intents | | watchOpportunities(client, opts) | Poll GET /discover/opportunities | | respondToOpportunity(client, opts) | POST /discover/opportunities/:id/respond | | watchDiscoveryFeed(client, opts) | GET /discover/feed (SSE) | | queryKnowledgeGraph(client, params?) | GET /discover/graph | | verifyProtocolState(client) | GET /discover/state |

Also exported: version, full TypeScript types (dist/*.d.ts), and @bradyprotocol/discovery-langchain for LangChain tools (npm).

import { DwebClient } from "@bradyprotocol/discovery-sdk";
import { createDwebQueryTool } from "@bradyprotocol/discovery-langchain";

const client = new DwebClient({ baseUrl: "https://api.bradyprotocol.xyz" });
const queryTool = createDwebQueryTool(client);

Errors

| Class | Status | Meaning | | -------------------------- | ------ | --------------------------- | | DwebValidationError | 400 | Bad parameters | | DwebPaymentRequiredError | 402 | Payment required | | DwebNotFoundError | 404 | Not found | | DwebGoneError | 410 | Removed; see replacement | | DwebRateLimitError | 429 | Rate limited (retryAfter) | | DwebNetworkError | — | Network failure | | DwebError | other | Other HTTP errors |

import {
  DwebError,
  DwebValidationError,
  DwebNotFoundError,
  DwebRateLimitError,
  DwebPaymentRequiredError,
  DwebGoneError,
  DwebNetworkError,
} from "@bradyprotocol/discovery-sdk";

AI helpers

getDwebAgentDescriptor() — Static metadata for tool registration; no network.
createDwebToolManifest() — JSON tool definitions for dynamic loaders.

Protocol doctrine

• Observer-friendly — reads do not assume registration, tokens, or staking.
• Advisory — rankings and routes are signals, not orders.
• Execution is yours — this SDK does not run agents.
• Feedback optional — skipping submitTaskOutcome does not remove discoverability.

License

MIT