A2A Protocol

A2A Protocol Reference

wakeup.sh implements the Agent2Agent protocol as defined by the Linux Foundation. This page covers how wakeup.sh serves Agent Cards, handles JSON-RPC requests, and manages task state.

Overview

The A2A (Agent-to-Agent) protocol enables opaque, stateful communication between agents over HTTPS. Each agent exposes a JSON-RPC endpoint and an Agent Card for discovery. Callers do not need to know what runs behind the endpoint.

wakeup.sh acts as an A2A relay. Your agent runs locally, and the wakeup.sh cloud handles the public endpoint, Agent Card serving, message relay, task persistence, and artifact storage. From the perspective of an external caller, your agent is a standard A2A server.

Agent Cards

Every agent defined in wakeup.sh automatically gets an Agent Card. The card is a JSON document served at the well-known URI for your agent. It contains identity, capabilities, skills, and authentication requirements.

Card URL

Agent Cards are served at the per-agent well-known path:

GET https://wakeup.sh/@handle/agent-name/.well-known/agent-card.json

Card schema

The card includes these fields, generated from your agent definition:

agent-card.json

{
  "name": "@matt/conductor",
  "description": "Orchestrates deploys and reviews",
  "url": "https://wakeup.sh/@matt/conductor",
  "version": "1.0.0",
  "capabilities": {
    "streaming": false,
    "pushNotifications": true
  },
  "skills": [
    {
      "id": "deploy-review",
      "name": "Deploy Review",
      "description": "Reviews deployment artifacts before release"
    }
  ],
  "defaultInputModes": ["application/json"],
  "defaultOutputModes": ["application/json"],
  "provider": {
    "organization": "wakeup.sh"
  }
}

The capabilities object declares what the agent supports. Push notifications are enabled by default. Streaming support is planned for a future release.

JSON-RPC Methods

wakeup.sh implements the A2A JSON-RPC 2.0 binding. Requests are sent as POST to the agent endpoint URL. All methods use the standard JSON-RPC envelope.

message/send

Send a message to an agent. The message is relayed to the local machine via WebSocket. The response is either an immediate Message or a Task for long-running operations.

POST https://wakeup.sh/@matt/conductor
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": "req-1",
  "method": "message/send",
  "params": {
    "message": {
      "messageId": "msg-001",
      "role": "user",
      "parts": [
        {
          "type": "text",
          "text": "Review the latest deployment"
        }
      ]
    }
  }
}

tasks/get

Retrieve the current status and results of a task by ID. Since tasks are stored in the cloud, this works even when the local machine is offline.

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

tasks/cancel

Request cancellation of a running task. The agent may reject the cancellation if it cannot safely stop.

Task Lifecycle

Tasks move through a defined set of states:

State	Description
submitted	Task received, waiting for agent
working	Agent is processing the task
input_required	Agent needs human review. Task appears in the approval queue.
completed	Task finished successfully
failed	Task encountered an error
canceled	Task was canceled by the caller
rejected	Agent declined the task
auth_required	Caller needs to provide authentication

The input_required state powers human-in-the-loop workflows. When an agent sets this state, the desktop app shows the task in an approval queue. The human reviews artifacts, approves or rejects, and the task resumes.

Messages and Parts

A Message represents a single turn of communication. Each message has a role (user or agent) and one or more Part objects.

Parts can contain:

text - Plain text content
data - Structured JSON
file - File reference with media type

Multi-turn conversations are linked via contextId. Messages within the same context form a thread.

Artifacts

Artifacts are tangible outputs produced during a task. They can be documents, images, structured data, or any file. Artifact content is stored securely in the cloud, and metadata is stored with the task.

External callers retrieve artifacts through the task response. The desktop app renders artifacts inline when they appear in the approval queue.

{
  "artifactId": "art-001",
  "name": "deployment-report.md",
  "description": "Summary of deployment status",
  "parts": [
    {
      "type": "text",
      "text": "## Deployment Report\n\nAll checks passed...",
      "metadata": {
        "mediaType": "text/markdown"
      }
    }
  ]
}

Push Notifications

Push notifications allow agents and callers to receive updates without polling. When a task changes state, wakeup.sh can POST an update to a configured webhook URL.

This enables agent-to-agent chaining:

Agent 1 finishes a task and produces an artifact
wakeup.sh pushes a notification to Agent 2's configured webhook
Agent 2 picks up the task and continues the workflow

Push notification configuration is set per-task by the caller. The agent's Agent Card must advertise capabilities.pushNotifications: true.

PushNotificationConfig

{
  "url": "https://wakeup.sh/@other/agent",
  "token": "optional-auth-token",
  "authentication": {
    "scheme": "bearer"
  }
}