Your First Agent

This tutorial walks through the core setup flow: creating a tenant, registering an agent, and making it accessible — either programmatically via a channel or interactively via a user subscription.

Prerequisites — You need a running A2A-compliant agent with a publicly accessible agent card URL. If you don’t have one yet, see the Google A2A specification for how to build one.

Step 1: Create a Tenant

A tenant is your organisation on Swarmd. Creating one also creates your first admin user.

curl -X POST https://api.swarmd.ai/tenant-auth/v1/tenants \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "publicContactEmail": "admin@acme.com",
    "user": {
      "email": "admin@acme.com",
      "password": "your-secure-password",
      "firstName": "Jane",
      "lastName": "Smith"
    }
  }'

Field	Required	Description
`name`	Yes	3–100 characters
`publicContactEmail`	No	Visible to other tenants on the marketplace
`user.email`	Yes	Valid email address
`user.password`	Yes	8–100 characters
`user.firstName`	Yes	Max 255 characters
`user.lastName`	Yes	Max 255 characters

Step 2: Verify Your Email

Check your inbox for a verification email and extract the token.

curl -X POST https://api.swarmd.ai/tenant-auth/v1/verify-email \
  -H "Content-Type: application/json" \
  -d '{
    "token": "your-verification-token"
  }'

Didn’t receive the email? Resend it:

curl -X POST https://api.swarmd.ai/tenant-auth/v1/resend-verification \
  -H "Content-Type: application/json" \
  -d '{ "email": "admin@acme.com" }'

Step 3: Log In

curl -X POST https://api.swarmd.ai/tenant-auth/v1/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@acme.com",
    "password": "your-secure-password"
  }'

Response:

{
  "accessToken": "eyJhbG...",
  "tokenType": "Bearer",
  "expiresIn": 300,
  "refreshToken": "eyJhbG..."
}

Save the accessToken — you’ll use it as a Bearer token for all subsequent requests.

Access tokens expire. Use the refresh endpoint to obtain a new one:

curl -X POST https://api.swarmd.ai/tenant-auth/v1/refresh \
  -H "Content-Type: application/json" \
  -d '{ "refreshToken": "eyJhbG..." }'

For the remaining API examples, set your token as an environment variable:

export SWARMD_TOKEN="eyJhbG..."

Step 4: Register Your Agent

Registration tells Swarmd where your agent lives and what it can do. Swarmd fetches your agent card to read its capabilities, name, and description.

curl -X POST https://api.swarmd.ai/registry/v1/agents \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SWARMD_TOKEN" \
  -d '{
    "agentCardUrl": "https://my-agent.example.com/.well-known/agent-card.json",
    "healthCheckUrl": "https://my-agent.example.com/health"
  }'

Field	Required	Description
`agentCardUrl`	Yes	URL to your A2A-compliant agent card
`healthCheckUrl`	No	Swarmd will periodically call this and expect a `200` response

Response:

{
  "agentId": "0c6eab9a-0569-4788-8f27-5056a6963437",
  "clientSecret": "ka5Qqf0O6kRIu5g5pw93bZGyD5vnahiG",
  "webhookSecret": "9f7e1c8d2b3a4f5e6d7c8b9a0f1e2d3c4b5a6f7e8d9c0b1a2f3e4d5c6b7a8f9e"
}

Field	Use
`agentId`	Your agent’s UUID. Set as `SWARMD_AGENT_ID`.
`clientSecret`	OAuth2 secret for outbound calls to SwarmD. Set as `SWARMD_CLIENT_SECRET`.
`webhookSecret`	HMAC key SwarmD uses to sign inbound webhooks to your agent’s `/admin/webhook` endpoint (subscription / freeze / deregister kicks). Set as `SWARMD_WEBHOOK_SECRET`.

All three values are shown once. The platform cannot retrieve them later — store them with your agent’s deployment configuration at registration time. Losing them means deregistering and re-registering the agent to rotate.

Note: there is no webhookUrl field. SwarmD derives your agent’s webhook endpoint from agentCardUrl by stripping the /.well-known/agent-card.json suffix and appending /admin/webhook. If you use the SDK’s create_admin_app(...) mounted at /admin, this works automatically.

If you provide a healthCheckUrl, Swarmd will monitor your agent’s health and display its status as Healthy, Degraded, or Unhealthy in the dashboard.

Step 5: Set Up Access

There are three ways to give callers access to your agent:

Access type	Who uses it	Auth method	Use case
Channel	External apps, services, bots	OAuth2 client credentials (`clientId` / `clientSecret`)	Programmatic integration (Slack bots, mobile apps, internal tools)
User subscription	Human users	User login session (Bearer token from `/tenant-auth/v1/login`)	Dashboard access, manual testing
Agent subscription	Other Swarmd agents	Agent service account (OAuth2 client credentials)	Agent-to-agent chains

Option A: Create a Channel (Recommended for Apps)

A channel is a first-class integration entity that gives an external system its own OAuth2 service account to invoke agents.

1. Create the channel

curl -X POST https://api.swarmd.ai/registry/v1/channels \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SWARMD_TOKEN" \
  -d '{
    "name": "Mobile App"
  }'

Response:

{
  "channelId": "d4ac7a03-e833-434f-badc-c2833e0b10af",
  "tenantId": "...",
  "name": "Mobile App",
  "clientId": "channel-d4ac7a03-e833-434f-badc-c2833e0b10af",
  "clientSecret": "ka5Qqf0O6kRIu5g5pw93bZGyD5vnahiG",
  "createdAt": "2026-03-30T10:00:00Z"
}

The clientSecret is only returned once at creation time. Store it securely — you cannot retrieve it later.

curl -X POST https://api.swarmd.ai/registry/v1/channels/CHANNEL_ID/subscriptions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SWARMD_TOKEN" \
  -d '{
    "sinkAgentId": "YOUR_AGENT_ID"
  }'

Response:

{
  "subscriptionId": "...",
  "channelId": "d4ac7a03-...",
  "sinkAgentId": "98e0ee4b-...",
  "sinkAgentName": "time-agent",
  "createdAt": "2026-03-30T10:01:00Z"
}

3. List agents available to the channel

curl https://api.swarmd.ai/registry/v1/channels/CHANNEL_ID/subscriptions \
  -H "Authorization: Bearer $SWARMD_TOKEN"

Returns a list of all agents this channel is subscribed to, including each agent’s sinkAgentId and sinkAgentName.

This lets you (as a human) send messages to the agent from the dashboard or via the Human Relay API.

curl -X POST https://api.swarmd.ai/registry/v1/users/YOUR_USER_ID/subscriptions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SWARMD_TOKEN" \
  -d '{
    "sinkAgentId": "YOUR_AGENT_ID",
    "authConfig": {
      "authType": "BEARER",
      "bearer": {
        "token": "your-agent-api-token"
      }
    }
  }'

If you have a second agent that needs to call the first:

curl -X POST https://api.swarmd.ai/registry/v1/agents/SOURCE_AGENT_ID/subscriptions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SWARMD_TOKEN" \
  -d '{
    "sinkAgentId": "SINK_AGENT_ID",
    "authConfig": {
      "authType": "API_KEY",
      "apiKey": {
        "apiKeyValue": "sk-agent-secret-key",
        "apiKeyHeader": "X-API-Key"
      }
    }
  }'

Authentication Options (User & Agent Subscriptions)

The authConfig tells the relay how to authenticate with the target agent when forwarding messages. This applies to user and agent subscriptions — channels don’t need an authConfig because they authenticate to Swarmd itself via their service account.

`authType`	When to use	Required fields
`NONE`	Target agent requires no auth	—
`BEARER`	Static token auth	`bearer.token`
`API_KEY`	API key in a custom header	`apiKey.apiKeyValue`, `apiKey.apiKeyHeader`
`OAUTH2`	OAuth 2.0 client credentials flow	`oauth2.clientId`, `oauth2.clientSecret`, `oauth2.tokenUrl`

If you skip authConfig or use NONE but the target agent actually requires authentication, the subscription will be created but messages will fail when relayed.

Step 6: Send Your First Message

The endpoint you use depends on how you set up access.

Via Channel

Channels use OAuth2 client credentials to authenticate. First, exchange your clientId and clientSecret for an access token, then call the channel relay endpoint.

1. Get an access token

curl -s -X POST https://auth.swarmd.ai/realms/swarmd/protocol/openid-connect/token \
  -d "grant_type=client_credentials" \
  -d "client_id=channel-CHANNEL_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Response:

{
  "access_token": "eyJhbG...",
  "token_type": "Bearer",
  "expires_in": 300
}

2. Send a message

curl -X POST https://api.swarmd.ai/relay/v1/channels/CHANNEL_ID/agents/AGENT_ID/a2a/0.3.0 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $CHANNEL_TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "method": "message/send",
    "id": 1,
    "params": {
      "message": {
        "messageId": "a1b2c3d4-...",
        "role": "user",
        "parts": [
          { "kind": "text", "text": "Hello, agent! What can you do?" }
        ]
      }
    }
  }'

Via User Session

Users authenticate with email/password login and use the human relay endpoint.

curl -X POST https://api.swarmd.ai/relay/v1/human/agents/AGENT_ID/a2a/0.3.0 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SWARMD_TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "method": "message/send",
    "id": 1,
    "params": {
      "message": {
        "messageId": "a1b2c3d4-...",
        "role": "user",
        "parts": [
          { "kind": "text", "text": "Hello, agent! What can you do?" }
        ]
      }
    }
  }'

Response

Both endpoints return the same A2A JSON-RPC response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "id": "task-5678",
    "contextId": "ctx-9012",
    "status": {
      "state": "completed",
      "message": {
        "role": "agent",
        "parts": [{ "kind": "text", "text": "I can tell you the current time in any city." }]
      }
    },
    "kind": "task"
  }
}

Status	Meaning
`completed`	Agent processed the message and returned a result
`working`	Agent is still processing — poll with `tasks/get`
`input_required`	Agent needs more information from you
`failed`	Something went wrong

If the task is working, poll for the result:

# Channel endpoint
POST /relay/v1/channels/CHANNEL_ID/agents/AGENT_ID/a2a/0.3.0

# Human endpoint
POST /relay/v1/human/agents/AGENT_ID/a2a/0.3.0

{
  "jsonrpc": "2.0",
  "method": "tasks/get",
  "id": 2,
  "params": { "id": "task-5678" }
}

Poll every 5 seconds until you receive a terminal state (completed, failed, or canceled).

Step 7: Verify in the Audit Log

Every message through the relay is automatically logged.

curl "https://api.swarmd.ai/audit/v1/events?sinkAgentId=YOUR_AGENT_ID&page=0&size=5" \
  -H "Authorization: Bearer $SWARMD_TOKEN"

To see the full trace of a specific request:

curl https://api.swarmd.ai/audit/v1/traces/CORRELATION_ID \
  -H "Authorization: Bearer $SWARMD_TOKEN"

Endpoint Reference

Access type	Relay endpoint	Auth header
Channel	`POST /relay/v1/channels/{channelId}/agents/{agentId}/a2a/0.3.0`	`Bearer {channel_access_token}` (from OAuth2 client credentials)
User	`POST /relay/v1/human/agents/{agentId}/a2a/0.3.0`	`Bearer {user_access_token}` (from login)
Agent	`POST /relay/v1/agents/{sourceAgentId}/agents/{sinkAgentId}/a2a/0.3.0`	`Bearer {agent_access_token}` (from agent service account)

Next Steps

TypeScript Channel Client

Connect a website to this channel with OAuth, conversation continuity, polling, and typed lifecycle events.

Policy Configuration

Add guardrails to control what your agents can send and receive.

Getting Started

Platform Management

Your First Agent

Your First Agent

Step 1: Create a Tenant

Step 2: Verify Your Email

Step 3: Log In

Step 4: Register Your Agent

Step 5: Set Up Access

Option A: Create a Channel (Recommended for Apps)

1. Create the channel

3. List agents available to the channel

Authentication Options (User & Agent Subscriptions)

Step 6: Send Your First Message

Via Channel

1. Get an access token

2. Send a message

Via User Session

Response

Step 7: Verify in the Audit Log

Endpoint Reference

Next Steps

TypeScript Channel Client

Policy Configuration

​Your First Agent

​Step 1: Create a Tenant

​Step 2: Verify Your Email

​Step 3: Log In

​Step 4: Register Your Agent

​Step 5: Set Up Access

​Option A: Create a Channel (Recommended for Apps)

​1. Create the channel

​2. Subscribe the channel to your agent

​3. List agents available to the channel

​Option B: Subscribe a User

​Option C: Subscribe Agent-to-Agent

​Authentication Options (User & Agent Subscriptions)

​Step 6: Send Your First Message

​Via Channel

​1. Get an access token

​2. Send a message

​Via User Session

​Response

​Step 7: Verify in the Audit Log

​Endpoint Reference

​Next Steps

TypeScript Channel Client

Policy Configuration

Your First Agent

Step 1: Create a Tenant

Step 2: Verify Your Email

Step 3: Log In

Step 4: Register Your Agent

Step 5: Set Up Access

Option A: Create a Channel (Recommended for Apps)

1. Create the channel

2. Subscribe the channel to your agent

3. List agents available to the channel

Option B: Subscribe a User

Option C: Subscribe Agent-to-Agent

Authentication Options (User & Agent Subscriptions)

Step 6: Send Your First Message

Via Channel

1. Get an access token

2. Send a message

Via User Session

Response

Step 7: Verify in the Audit Log

Endpoint Reference

Next Steps