What can developers build on Agent Studio?#
Anything that speaks HTTP can run your agents. Build a flow on the canvas, in guided mode or in TypeScript, launch it, and it gets a stable run URL, a public page and machine-readable discovery documents that stay put across every relaunch.
| Surface | What it gives you | Where it lives |
|---|---|---|
| Run API | One POST runs a published agent and returns its outputs | POST /api/agents/{id-or-slug}/run |
| MCP server | Listed agents appear as priced, described tools | POST /api/mcp, see MCP |
| SDK and CLI | Write agent.ts, test locally, push it live | npm install @suedeai/agents |
| Webhooks | Signed HTTP trigger that starts a run from any backend | POST /api/agents/{id-or-slug}/webhook |
| Catalog | Crawlable JSON feed of published agents and their call state | /api/catalog |
| OpenAPI | Machine-readable contract for the public agent routes | /openapi.json |
| A2A AgentCard | Agent-to-agent discovery and message:send over A2A 1.0 | /.well-known/agent-card.json |
How do I call a published agent over HTTP?#
Send one POST to the agent's run URL with an optional input object. Every body field is optional, so {} is a valid request for a flow that needs no input. Add dryRun: true, ?dryRun=1 or an x-suede-dry-run: 1 header to run a preview-ready agent free with every paid step stubbed.
# 1. list published agents and their call state
curl https://agents.suedeai.ai/api/catalog
# 2. run one (dryRun keeps it free for a preview-ready agent)
curl -X POST https://agents.suedeai.ai/api/agents/<id-or-slug>/run \
-H 'content-type: application/json' \
-d '{ "input": { "prompt": "Score this lead: 40 seats, renewal in 45 days" }, "dryRun": true }'The response carries a runId, a status of done or error, and outputs keyed by Output node id. The run endpoint allows a burst of 10 requests per IP and refills at one request every two seconds; a 429 comes with a Retry-After header. Every status code is in the API guide.
How do I connect Claude or an IDE to my agents over MCP?#
Add one server entry pointing at /api/mcp and send your workspace key as a bearer token. The server answers tools/list and tools/call over plain HTTP POST and derives each tool's input schema from the agent's own input fields, so the schema never drifts from what the agent reads.
{
"mcpServers": {
"suede": {
"url": "https://agents.suedeai.ai/api/mcp",
"headers": { "Authorization": "Bearer <your workspace key>" }
}
}
}Where do I get my workspace key?#
Your key lives on the Workspace page under This key is your workspace. Click Reveal, then Copy. Treat it like a password: whoever holds it controls your agents.
Set up your developer access
Step 1: Copy your workspace key
Open Workspace, find This key is your workspace., click Reveal and Copy. Store it in your password manager or secrets store.Open WorkspaceStep 2: Publish one agent
Start from a template such as the lead qualifier, dry-run it free, then click Launch to get its run URL.Open the lead qualifierStep 3: Call it from your terminal
Paste theRead the API guidecurlabove with your agent's slug and confirm astatusofdone.Step 4: Plug it into your AI client
Add the MCP config with your key and ask Claude to list your tools.Read the MCP guideStep 5: Read the machine contract
Load the OpenAPI document into Postman, Insomnia or a code generator.Open /openapi.json
How do other agents and crawlers discover mine?#
Every published agent ships with an A2A 1.0 AgentCard at /api/agents/{slug}/.well-known/agent-card.json, and the site root publishes /.well-known/agent-card.json plus an aggregate A2A interface at /api/a2a. An A2A client calls message:send with one structured data part and gets back a direct agent message.
- Catalog: /api/catalog lists published agents with their preview, payment-enabled or unavailable state.
- OpenAPI: /openapi.json documents the run, A2A and discovery routes for code generators.
- Directory: agents you choose to list appear in the public agent directory; a first launch stays unlisted until you list it.
Do I need crypto or a wallet to build or call agents?#
No. Building, testing, running and calling agents runs on your card-funded plan and usage credit. Per-call selling over x402 and USDC is an optional add-on for builders who want machine buyers, covered in Sell your agent per call.
Ship your first endpoint today
Pick a template, dry-run it free, launch it and call it with one request.