Your First Agent
This tutorial walks through the core setup flow: creating a tenant, registering an agent, subscribing to it, and sending your first message.
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 |
Coming soon.
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" }'
Coming soon.
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"
}'
{
"accessToken": "eyJhbG...",
"tokenType": "Bearer",
"expiresIn": 300,
"refreshToken": "eyJhbG..."
}
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..." }'
Coming soon.
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 |
agentId — save it for the next steps.If you provide a healthCheckUrl, Swarmd will monitor your agent’s health and display its status as Healthy, Degraded, or Unhealthy in the dashboard.
Coming soon.
Step 5: Subscribe to Your Agent
Subscriptions define who can talk to whom. There are two types:
- Agent-to-agent — one of your agents calls another agent
- User-to-agent — you (as a human) talk to an agent via the dashboard or API
Subscribe Yourself (User-to-Agent)
This lets you 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"
}
}
}'
Coming soon.
Subscribe Agent-to-Agent
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"
}
}
}'
Coming soon.
Authentication Options
The authConfig tells the relay how to authenticate with the target agent when forwarding messages.
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
With a subscription in place, you can send a message through the relay. The relay handles authentication, policy evaluation, and audit logging automatically.
curl -X POST https://api.swarmd.ai/relay/v1/agents/YOUR_AGENT_ID/a2a/0.3.0/message:send \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $SWARMD_TOKEN" \
-d '{
"message": {
"role": "user",
"parts": [
{
"kind": "text",
"text": "Hello, agent! What can you do?"
}
]
}
}'
| Status | Meaning |
|---|
COMPLETED | Agent processed the message and returned a result |
WORKING | Agent is still processing — poll the task endpoint |
INPUT_REQUIRED | Agent needs more information from you |
FAILED | Something went wrong |
WORKING, poll for the result:curl https://api.swarmd.ai/relay/v1/agents/YOUR_AGENT_ID/a2a/0.3.0/tasks/TASK_ID \
-H "Authorization: Bearer $SWARMD_TOKEN"
Coming soon.
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"
curl https://api.swarmd.ai/audit/v1/traces/CORRELATION_ID \
-H "Authorization: Bearer $SWARMD_TOKEN"
Coming soon.
Next Steps
