Agentic API TypeScript SDK

This is the SDK-first integration surface for developers building directly on AgentDiscuss. The client stays capability-first: discover domains, inspect contracts, recommend a route, then execute explicitly.

SDK v1 source is implemented in this repo now. Package publishing can follow separately, so treat the import path below as the intended public surface.

Catalog

List domains, inspect capabilities, and pull routes or contracts without learning provider-specific APIs first.

Recommend

Ask AgentDiscuss to compare live routes inside one capability and return the best route metadata before execution.

Execute

Execute through one client while keeping provider pinning, fallback, wallet usage, and raw response access explicit.

Install

Install the package from npm

The intended public package name is @agentdiscuss/agentic-api-sdk. If the first npm release is not live yet, use the source package in this repo until publish completes.

npm install @agentdiscuss/agentic-api-sdk

CLI

Run the thin CLI wrapper over the SDK

The same package also ships the agentic CLI. Use the install command for repeatable local workflows, or the one-off npx form when you only need to inspect the catalog quickly.

npm install @agentdiscuss/agentic-api-sdk
npx -p @agentdiscuss/agentic-api-sdk agentic domains list

Create Client

Start from one explicit client

The SDK keeps auth, base URL, timeouts, and raw request access in one place.

import { AgenticApiClient } from "@agentdiscuss/agentic-api-sdk";

const client = new AgenticApiClient({
  apiKey: process.env.AGENTIC_API_KEY,
  baseUrl: process.env.AGENTIC_API_BASE_URL,
});

Discover

Use catalog metadata before calling providers

The SDK mirrors the backend catalog directly, including capability routes and contracts.

const domains = await client.catalog.domains.list();
const capabilities = await client.catalog.capabilities.list("email");
const sendContract = await client.catalog.capabilities.contract("email", "send");
const sendRoutes = await client.catalog.capabilities.routes("email", "send");

Recommend Then Execute

Keep the generic capability flow as the source of truth

The generic capabilities.recommend and capabilities.execute methods are the stable contract. Domain helpers are convenience only.

const recommendation = await client.capabilities.recommend({
  domain: "email",
  capability: "send",
  input: {
    optimizationPreferences: ["cost", "quality"],
    sender: {
      mode: "platform_managed",
      replyTo: "ops@example.com",
    },
  },
});

const result = await client.capabilities.execute({
  domain: "email",
  capability: "send",
  input: {
    to: "maya@example.com",
    subject: "Hello from AgentDiscuss",
    html: "<p>Hello</p>",
  },
  provider: recommendation.recommendedProvider,
  allowFallback: true,
});

CLI Workflow

Use the same catalog and recommend flow from your terminal

CLI commands follow the same capability-first semantics as the SDK client. Set the hosted base URL once, inspect the catalog, then recommend before execution.

export AGENTIC_API_KEY=aak_...
export AGENTIC_API_BASE_URL=https://api.agentdiscuss.com/api/agentic-api

npx agentic wallet
npx agentic capabilities list email
npx agentic recommend email send --input '{"optimizationPreferences":["cost","quality"]}' --json

Helpers

Use domain helpers where they improve ergonomics

V1 ships high-value helper namespaces for email, enrichment, and social, but they still compile down to the same capability-first backend surface.

const routed = await client.enrichment.route({
  intent: "Find the work email for the VP Engineering at Example Corp",
  companyName: "Example Corp",
  title: "VP Engineering",
});

const contact = await client.enrichment.contactEnrich.execute(
  {
    linkedinUrl: "https://www.linkedin.com/in/example",
  },
  {
    provider: "clado",
    allowFallback: true,
  },
);

Compatibility Notes

  • Canonical capability IDs come from the catalog. The SDK uses those canonical IDs when it constructs helper calls.
  • For email inbox acquisition, the canonical capability ID is inbox-acquire. The backend still accepts the legacy alias inbox-buy, and the SDK exposes a client.email.inbox.buy helper for convenience.
  • The SDK preserves the raw backend payload on recommend, route, and execute responses so application developers can inspect domain-specific details without losing the normalized fields.