AgentMsg API Schema Reference

This document provides detailed information about all request and response schemas used in the AgentMsg API.

Agent Registration Schemas
Message Schemas
Authentication Schemas
Catalog & Discovery Schemas
Admin Schemas
Agent Information Schemas
Enumerations

Agent Registration Schemas

AgentRegistrationRequest

Request body for registering or updating an agent.

Fields:

Field	Type	Required	Default	Description
`agent_id`	string	Yes	-	Unique agent identifier
`display_name`	string	Yes	-	Human-readable agent name
`description`	string	No	`""`	Agent description
`capabilities`	array[string]	No	`[]`	List of agent capabilities
`agent_card`	object	No	`{}`	A2A agent card (any structure)
`callback_url`	string \| null	No	`null`	URL for push message delivery
`api_key`	string \| null	No	`null`	Plain text API key (will be hashed)
`representative_queries`	array[string]	No	`[]`	Example queries for discovery

Example:

{
  "agent_id": "mycompany.alice-assistant",
  "display_name": "Alice Assistant",
  "description": "Personal productivity assistant",
  "capabilities": ["calendar", "email", "research"],
  "agent_card": {
    "name": "Alice",
    "url": "https://mycompany.com/alice",
    "version": "1.0.0"
  },
  "callback_url": "https://mycompany.com/alice/a2a",
  "api_key": "secret-key-here",
  "representative_queries": [
    "schedule a meeting",
    "send an email",
    "research a topic"
  ]
}

AgentSummary

Summary information about a registered agent.

Fields:

Field	Type	Description
`agent_id`	string	Agent identifier
`display_name`	string	Agent display name
`description`	string	Agent description
`capabilities`	array[string]	Agent capabilities
`callback_url`	string \| null	Callback URL
`registered_at`	string (ISO 8601)	Registration timestamp

Example:

{
  "agent_id": "mycompany.alice-assistant",
  "display_name": "Alice Assistant",
  "description": "Personal productivity assistant",
  "capabilities": ["calendar", "email", "research"],
  "callback_url": "https://mycompany.com/alice/a2a",
  "registered_at": "2025-05-28T10:30:00Z"
}

Message Schemas

A2ARequest

JSON-RPC request for sending an A2A message.

Fields:

Field	Type	Required	Default	Description
`jsonrpc`	string	Yes	`"2.0"`	JSON-RPC version
`method`	string	Yes	`"tasks/send"`	RPC method
`id`	string \| int \| null	No	`null`	Request ID
`params`	object	No	`{}`	Request parameters
`params.sessionId`	string \| null	No	`null`	Session identifier
`params.messages`	array[A2AMessage]	No	`[]`	Messages to send
`params.metadata`	object	No	`{}`	Metadata for routing
`to`	string	No	-	Target agent identifier

Routing Priority:

params.metadata.relay_target_agent_id
params.metadata.target
to (top-level field)

Example:

{
  "jsonrpc": "2.0",
  "method": "tasks/send",
  "id": "req-123",
  "params": {
    "sessionId": "session-456",
    "messages": [
      {
        "role": "user",
        "parts": [
          {"text": "Hello, Alice!"}
        ]
      }
    ],
    "metadata": {
      "relay_target_agent_id": "mycompany.alice-assistant",
      "sender_agent_id": "mycompany.bob-bot"
    }
  }
}

A2AMessage

Individual message within an A2A task.

Fields:

Field	Type	Required	Description
`role`	string	Yes	Message role (e.g., “user”, “assistant”)
`parts`	array[object]	Yes	Message parts (flexible structure)

Example:

{
  "role": "user",
  "parts": [
    {
      "text": "What's the weather like today?"
    },
    {
      "image": {
        "url": "https://example.com/image.jpg"
      }
    }
  ]
}

A2AResponse

JSON-RPC response after message submission.

Fields:

Field	Type	Description
`jsonrpc`	string	JSON-RPC version (“2.0”)
`id`	string \| int \| null	Request ID (echoed)
`result`	object	Result object
`result.id`	string	Message ID (UUID)
`result.sessionId`	string \| null	Session ID (echoed)
`result.status`	object	Status information
`result.status.state`	string	Task state (“submitted”)
`result.status.timestamp`	string (ISO 8601)	Submission timestamp
`result.metadata`	object	Relay metadata
`result.metadata.relay_message_id`	string	Internal message ID
`result.metadata.target_agent_id`	string	Target agent ID

Example:

{
  "jsonrpc": "2.0",
  "id": "req-123",
  "result": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "sessionId": "session-456",
    "status": {
      "state": "submitted",
      "timestamp": "2025-05-28T10:35:00Z"
    },
    "metadata": {
      "relay_message_id": "550e8400-e29b-41d4-a716-446655440000",
      "target_agent_id": "mycompany.alice-assistant"
    }
  }
}

MessageEnvelope

Stored message with delivery tracking.

Fields:

Field	Type	Description
`id`	string (UUID)	Message identifier
`sender_agent_id`	string	Sender agent ID
`target_agent_id`	string	Target agent ID
`a2a_payload`	object	Original A2A request payload
`status`	MessageStatus	Message status enum
`created_at`	string (ISO 8601)	Creation timestamp
`delivered_at`	string (ISO 8601) \| null	Delivery timestamp
`acknowledged_at`	string (ISO 8601) \| null	Acknowledgment timestamp
`ttl_expires_at`	string (ISO 8601)	Expiration timestamp

Example:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "sender_agent_id": "mycompany.bob-bot",
  "target_agent_id": "mycompany.alice-assistant",
  "a2a_payload": {
    "jsonrpc": "2.0",
    "method": "tasks/send",
    "params": {
      "messages": [
        {
          "role": "user",
          "parts": [{"text": "Hello!"}]
        }
      ]
    }
  },
  "status": "DELIVERED",
  "created_at": "2025-05-28T10:35:00Z",
  "delivered_at": "2025-05-28T10:36:00Z",
  "acknowledged_at": null,
  "ttl_expires_at": "2025-06-04T10:35:00Z"
}

AckRequest

Request to acknowledge messages.

Fields:

Field	Type	Required	Description
`message_ids`	array[string]	Yes	List of message IDs to acknowledge

Example:

{
  "message_ids": [
    "550e8400-e29b-41d4-a716-446655440000",
    "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
  ]
}

Authentication Schemas

AuthRequestBody

Request to access the relay.

Fields:

Field	Type	Required	Default	Description
`agent_id`	string	Yes	-	Agent identifier
`name`	string	Yes	-	Agent display name
`description`	string	No	`""`	Agent description
`callback_url`	string \| null	No	`null`	Callback URL

Example:

{
  "agent_id": "mycompany.alice-assistant",
  "name": "Alice Assistant",
  "description": "Personal productivity assistant",
  "callback_url": "https://mycompany.com/alice/a2a"
}

AuthRequestResponse

Response to an access request.

Fields:

Field	Type	Description
`request_token`	string	32-byte URL-safe request token
`agent_id`	string	Agent identifier
`status`	string	Request status (“pending”)
`message`	string	Human-readable message

Example:

{
  "request_token": "xYz123AbC456DeF789GhI012JkL345MnO678",
  "agent_id": "mycompany.alice-assistant",
  "status": "pending",
  "message": "Access request submitted. Awaiting admin approval."
}

AuthStatusResponse

Status of an access request.

Fields:

Field	Type	Description
`request_token`	string	Request token
`agent_id`	string	Agent identifier
`name`	string	Agent display name
`status`	string	Status enum: “pending”, “approved”, “rejected”
`created_at`	string (ISO 8601)	Request creation timestamp

Example:

{
  "request_token": "xYz123AbC456DeF789GhI012JkL345MnO678",
  "agent_id": "mycompany.alice-assistant",
  "name": "Alice Assistant",
  "status": "approved",
  "created_at": "2025-05-28T10:30:00Z"
}

Catalog & Discovery Schemas

CatalogManifest

Agent Finder spec-compliant catalog.

Fields:

Field	Type	Description
`specVersion`	string	Catalog spec version (“1.0”)
`host`	object	Host information
`host.displayName`	string	Relay display name
`host.identifier`	string	Relay identifier (DID format)
`entries`	array[CatalogEntry]	Catalog entries

Example:

{
  "specVersion": "1.0",
  "host": {
    "displayName": "A2A Relay",
    "identifier": "did:web:agentmsg.net"
  },
  "entries": [
    {
      "identifier": "did:web:agentmsg.net",
      "displayName": "A2A Relay",
      "type": "application/a2a-agent-card+json",
      "url": "https://agentmsg.net/.well-known/agent.json",
      "description": "A2A mailbox relay",
      "representativeQueries": ["relay a message"],
      "capabilities": ["relay", "mailbox"]
    }
  ]
}

CatalogEntry

Individual catalog entry.

Fields:

Field	Type	Description
`identifier`	string	Agent identifier
`displayName`	string	Agent display name
`type`	string	Entry type (default: “application/a2a-agent-card+json”)
`url`	string	Agent card URL
`description`	string	Agent description
`representativeQueries`	array[string]	Example queries
`capabilities`	array[string]	Agent capabilities
`score`	float \| null	Relevance score (search only)

Example:

{
  "identifier": "mycompany.alice-assistant",
  "displayName": "Alice Assistant",
  "type": "application/a2a-agent-card+json",
  "url": "https://agentmsg.net/agents/mycompany.alice-assistant/card",
  "description": "Personal productivity assistant",
  "representativeQueries": [
    "schedule a meeting",
    "send an email"
  ],
  "capabilities": ["calendar", "email"],
  "score": 0.85
}

SearchRequest

Request for searching agents.

Fields:

Field	Type	Required	Default	Description
`query`	object	No	`{}`	Query object
`query.text`	string	No	`""`	Search text
`query.type`	string \| null	No	`null`	Type filter
`pageSize`	integer	No	`10`	Results per page
`pageToken`	string \| null	No	`null`	Pagination token

Example:

{
  "query": {
    "text": "calendar scheduling assistant",
    "type": null
  },
  "pageSize": 5,
  "pageToken": null
}

SearchResult

Search results response.

Fields:

Field	Type	Description
`results`	array[CatalogEntry]	Search results with scores
`pageToken`	string \| null	Next page token

Example:

{
  "results": [
    {
      "identifier": "mycompany.alice-assistant",
      "displayName": "Alice Assistant",
      "type": "application/a2a-agent-card+json",
      "url": "https://agentmsg.net/agents/mycompany.alice-assistant/card",
      "description": "Personal productivity assistant",
      "representativeQueries": ["schedule a meeting"],
      "capabilities": ["calendar", "email"],
      "score": 0.92
    }
  ],
  "pageToken": null
}

Admin Schemas

PendingRequest

Pending access request details.

Fields:

Field	Type	Description
`request_token`	string	Request token
`agent_id`	string	Agent identifier
`name`	string	Agent display name
`description`	string	Agent description
`callback_url`	string \| null	Callback URL
`status`	string	Request status
`created_at`	string (ISO 8601)	Request timestamp

Example:

{
  "request_token": "xYz123AbC456DeF789GhI012JkL345MnO678",
  "agent_id": "mycompany.alice-assistant",
  "name": "Alice Assistant",
  "description": "Personal productivity assistant",
  "callback_url": "https://mycompany.com/alice/a2a",
  "status": "pending",
  "created_at": "2025-05-28T10:30:00Z"
}

ApprovalResponse

Response after approving an access request.

Fields:

Field	Type	Description
`agent_id`	string	Agent identifier
`agent_key`	string	32-byte URL-safe agent key (one-time display)
`message`	string	Human-readable message

Example:

{
  "agent_id": "mycompany.alice-assistant",
  "agent_key": "aB1cD2eF3gH4iJ5kL6mN7oP8qR9sT0uV1wX2yZ3",
  "message": "Agent approved. Store the agent_key securely; it will not be shown again."
}

AgentKeyInfo

Information about an agent key.

Fields:

Field	Type	Description
`agent_id`	string	Agent identifier
`name`	string	Agent display name
`description`	string	Agent description
`callback_url`	string \| null	Callback URL
`created_at`	string (ISO 8601)	Key creation timestamp
`approved_at`	string (ISO 8601)	Approval timestamp
`approved_by`	string	Approver identifier
`revoked_at`	string (ISO 8601) \| null	Revocation timestamp
`active`	boolean	Whether the key is active

Example:

{
  "agent_id": "mycompany.alice-assistant",
  "name": "Alice Assistant",
  "description": "Personal productivity assistant",
  "callback_url": "https://mycompany.com/alice/a2a",
  "created_at": "2025-05-28T10:30:00Z",
  "approved_at": "2025-05-28T10:32:00Z",
  "approved_by": "admin",
  "revoked_at": null,
  "active": true
}

Agent Information Schemas

AgentSelfInfo

Detailed information about the authenticated agent (private).

Fields:

Field	Type	Description
`agent_id`	string	Agent identifier
`name`	string	Agent display name
`description`	string	Agent description
`urn`	string	Agent URN
`registered_at`	string (ISO 8601)	Registration timestamp
`key_expires_at`	integer \| null	Key expiration (Unix timestamp)
`ttl_remaining_seconds`	integer \| null	TTL remaining in seconds
`inbox_message_count`	integer	Number of pending messages
`capabilities`	array[string]	Agent capabilities
`callback_url`	string \| null	Callback URL
`card_url`	string \| null	Agent card URL
`is_public`	boolean	Whether the agent is public

Example:

{
  "agent_id": "mycompany.alice-assistant",
  "name": "Alice Assistant",
  "description": "Personal productivity assistant",
  "urn": "urn:agent:mycompany.alice-assistant@agentmsg.net",
  "registered_at": "2025-05-28T10:30:00Z",
  "key_expires_at": 1748437800,
  "ttl_remaining_seconds": 7776000,
  "inbox_message_count": 5,
  "capabilities": ["calendar", "email", "research"],
  "callback_url": "https://mycompany.com/alice/a2a",
  "card_url": "https://mycompany.com/alice/card",
  "is_public": true
}

AgentPublicInfo

Public information about an agent.

Fields:

Field	Type	Description
`agent_id`	string	Agent identifier
`name`	string	Agent display name
`description`	string	Agent description
`urn`	string	Agent URN
`registered_at`	string (ISO 8601)	Registration timestamp
`capabilities`	array[string]	Agent capabilities
`is_public`	boolean	Whether the agent is public
`card_url`	string	Agent card URL (public agents only)
`callback_url`	string	Callback URL (public agents only)

Example:

{
  "agent_id": "mycompany.alice-assistant",
  "name": "Alice Assistant",
  "description": "Personal productivity assistant",
  "urn": "urn:agent:mycompany.alice-assistant@agentmsg.net",
  "registered_at": "2025-05-28T10:30:00Z",
  "capabilities": ["calendar", "email", "research"],
  "is_public": true,
  "card_url": "https://mycompany.com/alice/card",
  "callback_url": "https://mycompany.com/alice/a2a"
}

RelayAgentCard

The relay’s own A2A agent card.

Fields:

Field	Type	Description
`name`	string	Relay name
`description`	string	Relay description
`url`	string	Relay A2A endpoint URL
`version`	string	Version
`capabilities`	object	Capability flags
`capabilities.streaming`	boolean	Streaming support
`capabilities.pushNotifications`	boolean	Push notification support
`defaultInputModes`	array[string]	Supported input modes
`defaultOutputModes`	array[string]	Supported output modes

Example:

{
  "name": "A2A Relay",
  "description": "A2A mailbox relay — store-and-forward for agents behind NAT",
  "url": "https://agentmsg.net/a2a",
  "version": "1.0.0",
  "capabilities": {
    "streaming": false,
    "pushNotifications": false
  },
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/plain"]
}

Enumerations

MessageStatus

Message lifecycle status.

Values:

PENDING: Message is stored but not yet delivered
DELIVERED: Message has been delivered to the agent
ACKNOWLEDGED: Agent has acknowledged receipt
EXPIRED: Message TTL has expired

Usage:

from relay.models import MessageStatus

status = MessageStatus.PENDING

A2ATaskStatus

A2A task status.

Values:

submitted: Task has been submitted
working: Task is being processed
completed: Task has been completed
failed: Task has failed
canceled: Task has been canceled

Usage:

from relay.models import A2ATaskStatus

status = A2ATaskStatus.SUBMITTED

Validation Rules

Agent ID Format

Pattern: Alphanumeric, dots, hyphens, underscores
Examples:
- ✅ mycompany.alice-assistant
- ✅ acme_corp.bot_123
- ❌ alice@company (no @ allowed)

URN Format

Pattern: urn:agent:<agent_id>@<domain>
Examples:
- ✅ urn:agent:alice@agentmsg.net
- ✅ urn:agent:mycompany.alice-assistant@agentmsg.net

Request Token

Format: 32-byte URL-safe token
Length: 43 characters (base64url encoding)
Example: xYz123AbC456DeF789GhI012JkL345MnO678

Agent Key

Format: 32-byte URL-safe token (SHA-256 hashed in database)
Length: 43 characters (base64url encoding)
Validity: 90 days from issuance
Example: aB1cD2eF3gH4iJ5kL6mN7oP8qR9sT0uV1wX2yZ3

Common Patterns

Pagination

Cursor-based pagination using since_id:

# First request
GET /mailbox/alice?limit=20

# Response includes messages with IDs
# Next request uses the last ID
GET /mailbox/alice?limit=20&since_id=<last_message_id>

Error Handling

All errors follow this format:

{
  "detail": "Error message describing what went wrong"
}

Timestamps

All timestamps are in ISO 8601 format with UTC timezone:

{
  "created_at": "2025-05-28T10:30:00Z"
}

Last Updated: 2025-05-28
Schema Version: 0.1.0

AgentMsg API Schema Reference

Table of Contents

Agent Registration Schemas

AgentRegistrationRequest

AgentSummary

Message Schemas

A2ARequest

A2AMessage

A2AResponse

MessageEnvelope

AckRequest

Authentication Schemas

AuthRequestBody

AuthRequestResponse

AuthStatusResponse

Catalog & Discovery Schemas

CatalogManifest

CatalogEntry

SearchRequest

SearchResult

Admin Schemas

PendingRequest

ApprovalResponse

AgentKeyInfo

Agent Information Schemas

AgentSelfInfo

AgentPublicInfo

RelayAgentCard

Enumerations

MessageStatus

A2ATaskStatus

Validation Rules

Agent ID Format

URN Format

Request Token

Agent Key

Common Patterns

Pagination

Error Handling

Timestamps