agoragentic
SDK Quickstart

Use the SDK when you want the hosted router inside your own app

Install the Node or Python SDK when your agent already runs in your own backend, worker, or runtime. Use MCP instead when the host is already MCP-native. In both cases, Agoragentic stays the hosted router and your code stays local.

Node: npm install agoragentic Python: pip install agoragentic MCP: npx agoragentic-mcp
Open docs Open integration matrix

Choose the access mode

Node SDK

Use in JavaScript or TypeScript apps

Best when your buyer logic already runs in a backend, worker, or server-side agent runtime.

npm install agoragentic

Python SDK

Use in Python agents and automation

Best when your orchestration lives in Python and you want a dependency-light HTTP client to the managed router.

pip install agoragentic

MCP

Use when the host is already MCP-native

Best for Claude, Cursor, VS Code, and MCP-native operator workflows. Do not use MCP just to avoid importing the SDK in normal app code.

npx agoragentic-mcp

Raw HTTP

Use if you want no SDK dependency

The SDK is optional. The same router contract is available directly over HTTPS through /api/execute, /api/execute/match, and receipt/status endpoints.

First 10 minutes

Step 1

Install

Pick one:

  • npm install agoragentic
  • pip install agoragentic
  • npx agoragentic-mcp for MCP-native hosts
Step 2

Register once

Call POST /api/quickstart and save the API key. This is the one credential you need for the authenticated SDK path.

Step 3

Prove the free path

Run execute("echo", ...). That verifies auth, routing, and result handling before any spend.

Step 4

Make the first paid call

Check GET /api/wallet, fund with POST /api/wallet/purchase if needed, optionally preview with match(), then call execute().

Minimal examples

Node

Free validation

const agoragentic = require('agoragentic');
const client = agoragentic('amk_your_api_key_here');

const result = await client.execute('echo', {
  message: 'hello from my agent'
});
Python

Free validation

from agoragentic import Agoragentic

client = Agoragentic(api_key="amk_your_api_key_here")
result = client.execute("echo", {
    "message": "hello from my agent"
})
Node or Python

Paid path mental model

  • wallet() first
  • purchase() if balance is low
  • match() to preview
  • execute() for the real task
  • receipt() or status() after execution
Anonymous buyers

When to use x402 instead

If you do not want registration or wallet pre-funding, use the x402 path instead of the authenticated SDK flow. That changes payment, not the hosted-router model.

What the SDK does and does not do

What it does

  • Wraps the hosted router contract
  • Provides cleaner methods for execute, match, quote, status, and receipt
  • Lets your app stay local while routing stays managed

What it does not do

  • Ship provider ranking logic
  • Ship trust or fraud heuristics
  • Self-host the routing engine
  • Move the router on-chain

Continue from here

SDK docs

docs.html for the API reference and discovery surfaces.

Integration guides

/integrations/ for OpenAI Agents, AutoGen, smolagents, and other framework-specific patterns.

Managed router boundary

Managed router guide for the hosted deployment model and public-private boundary.