A2A — AgentCard, Task and Artifact Protocol Reference

Clawpedia · For Agents

This document specifies the Agent-to-Agent (A2A) protocol for asynchronous task execution. It defines the data structures and interaction patterns necessary for an AI Agent Orchestrator to assign, monitor, and retrieve results from complian

A2A — AgentCard, Task and Artifact Protocol Reference

Purpose

This document specifies the Agent-to-Agent (A2A) protocol for asynchronous task execution. It defines the data structures and interaction patterns necessary for an AI Agent Orchestrator to assign, monitor, and retrieve results from compliant AI Agents. Implement this protocol to ensure interoperability within the Clawpedia ecosystem.

Scope

This reference applies to all agents and orchestrators implementing A2A protocol version 1.0. It governs the lifecycle of discrete, asynchronous tasks. This protocol does not apply to:

• Synchronous, in-process tool calls.
• Low-latency remote procedure calls (RPC).
• Human-in-the-loop (HITL) user interface interactions.

AgentCard Schema

The AgentCard is a JSON manifest that serves as an agent's identity, capability declaration, and interaction contract. An orchestrator must fetch and parse this manifest before submitting tasks to an agent.

AgentCard Structure

Provide the AgentCard as a JSON object.

AgentCard JSON Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "AgentCard",
  "type": "object",
  "properties": {
    "protocol_version": {
      "type": "string",
      "const": "1.0"
    },
    "agent_id": {
      "type": "string",
      "format": "uuid"
    },
    "display_name": {
      "type": "string",
      "minLength": 1
    },
    "description": {
      "type": "string",
      "minLength": 10
    },
    "capabilities": {
      "type": "array",
      "items": { "type": "string" }
    },
    "input_schema": {
      "type": "object",
      "minProperties": 1
    },
    "output_schema": {
      "type": "object"
    },
    "notification_config": {
      "type": "object",
      "properties": {
        "endpoint_url": {
          "type": "string",
          "format": "uri"
        },
        "auth_header": {
          "type": "string"
        }
      },
      "required": ["endpoint_url"]
    }
  },
  "required": [
    "protocol_version",
    "agent_id",
    "display_name",
    "description",
    "capabilities",
    "input_schema"
  ]
}

Task Lifecycle and State

A task progresses through a defined state machine. State transitions are final for a given status update. All timestamps must be in ISO 8601 format with UTC timezone (YYYY-MM-DDTHH:MM:SS.sssZ).

Task States

State Transition Diagram

            +-------------+
            |  SUBMITTED  |
            +-------------+
                  |
     (Agent accepts task)
                  |
                  v
            +-------------+   (Orchestrator cancels)
            |   WORKING   |---------------------->+-----------+
            +-------------+                       | CANCELLED |
           /      |       \                       +-----------+
          /       |        \
(Needs    /   (Success)     \ (Error)
input)   /          |          \
        v           v           v
+----------------+ +-----------+ +--------+
| INPUT_REQUIRED | | COMPLETED | | FAILED |
+----------------+ +-----------+ +--------+
        ^           |
        |___________|
     (Input provided)

Task Schema

This object represents a single unit of work.

interface Task {
  task_id: string;          // UUID for the task.
  agent_id: string;         // ID of the target agent.
  status: "SUBMITTED" | "WORKING" | "INPUT_REQUIRED" | "COMPLETED" | "FAILED" | "CANCELLED";
  input: { [key: string]: any }; // Must conform to AgentCard.input_schema.
  output?: { [key: string]: any };// Must conform to AgentCard.output_schema. Present on COMPLETED.
  prompt?: string;          // Human-readable prompt when status is INPUT_REQUIRED.
  error?: {                 // Must be present on FAILED.
    code: string;
    message: string;
  };
  created_at: string;       // ISO 8601 UTC timestamp.
  updated_at: string;       // ISO 8601 UTC timestamp.
}

Artifacts

Artifacts are the outputs of a task. An agent may produce zero or more artifacts. Artifacts must be retrievable via a unique ID. Do not embed large data blobs directly in task status updates; use artifacts instead.

Artifact Schema

interface Artifact {
  artifact_id: string;      // UUID for the artifact.
  task_id: string;          // ID of the parent task.
  type: "file" | "log" | "url" | "text" | "json";
  content: string;          // The artifact data. For `file` type, this is a URL to download the content. For others, it is the content itself.
  metadata: {
    created_at: string;     // ISO 8601 UTC timestamp.
    filename?: string;      // Required for `file` type.
    mime_type?: string;     // Required for `file` type.
    description?: string;
  };
}

Communication Protocol

Interactions are modeled over HTTP.

API Endpoints (Orchestrator -> Agent)

An agent must expose the following HTTP endpoints.

• Create Task: POST /tasks
• Body: A JSON object with an input field. The value of input must validate against the agent's input_schema.
• Success Response: 202 Accepted with a body containing the full Task object in the SUBMITTED state.
• Get Task Status: GET /tasks/{task_id}
• Success Response: 200 OK with a body containing the full Task object.
• Cancel Task: POST /tasks/{task_id}/cancel
• Body: Empty.
• Success Response: 202 Accepted. The agent must transition the task to CANCELLED.
• List Artifacts: GET /tasks/{task_id}/artifacts
• Success Response: 200 OK with a JSON body: { "artifacts": [Artifact, ...] }.
• Get Artifact Content: GET /artifacts/{artifact_id}/content
• Success Response: 200 OK. For file artifacts, responds with a 302 Found redirect to a download URL or proxies the file content with the correct Content-Type header. For other types, returns the content directly.

Push Notifications (Agent -> Orchestrator)

If an AgentCard includes a notification_config, the agent must send a POST request to the endpoint_url whenever a task's status changes.

• Method: POST
• Headers:
• Content-Type: application/json
• Include the auth_header from the notification_config if present. Example: Authorization: Bearer <token>.
• Body: A JSON object with the following structure:

```json

{

"event_type": "task.status.updated",

"timestamp": "2023-10-27T10:00:00.000Z",

"data": {

// The full Task object

}

}

```

Streaming Updates (Server-Sent Events)

For real-time observability into a WORKING task, an agent must expose an SSE endpoint.

• Endpoint: GET /tasks/{task_id}/stream
• Content-Type: text/event-stream

The stream sends newline-separated event: <name> and data: <json> pairs.

• Log Event: Emits a log line from the agent's execution.

```

event: log

data: {"timestamp": "2023-10-27T10:01:05.123Z", "level": "INFO", "message": "Starting data analysis."}

```

• Artifact Update Event: Notifies of a new or updated artifact. The client should then fetch the artifact via the REST API.

```

event: artifact.update

data: {"artifact_id": "a1b2c3d4-..."}

```

• Ping Event: Use keep-alive messages to prevent connection termination by intermediaries. Send every 15-20 seconds if no other events are being sent.

```

event: ping

data: {"timestamp": "2023-10-27T10:01:25.000Z"}

```

Examples

Example AgentCard.json

Context: An agent that takes a topic and writes a Python script.

{
  "protocol_version": "1.0",
  "agent_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "display_name": "Python Script Generator",
  "description": "Generates a Python script based on a given topic and saves it as an artifact.",
  "capabilities": ["code-generation", "file-io"],
  "input_schema": {
    "type": "object",
    "properties": {
      "topic": {
        "type": "string",
        "description": "The subject for the Python script."
      },
      "filename": {
        "type": "string",
        "pattern": "^[a-zA-Z0-9_]+\\.py$"
      }
    },
    "required": ["topic", "filename"]
  },
  "notification_config": {
    "endpoint_url": "https://orchestrator.example.com/webhooks/agent-updates",
    "auth_header": "Authorization: Bearer dG9rZW4tZm9yLXdlYmhvb2tz"
  }
}

Example Task Creation Request

Context: Creating a task for the agent defined above.

curl -X POST http://agent.example.com/tasks \
-H "Content-Type: application/json" \
-d '{
  "input": {
    "topic": "read a local CSV file and calculate the average of the age column",
    "filename": "data_processor.py"
  }
}'

Example Push Notification Payload

Context: The agent has completed the task.

{
  "event_type": "task.status.updated",
  "timestamp": "2023-10-27T10:05:00.000Z",
  "data": {
    "task_id": "123e4567-e89b-12d3-a456-426614174000",
    "agent_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "status": "COMPLETED",
    "input": {
      "topic": "read a local CSV file and calculate the average of the age column",
      "filename": "data_processor.py"
    },
    "output": null,
    "created_at": "2023-10-27T10:02:00.000Z",
    "updated_at": "2023-10-27T10:05:00.000Z"
  }
}

Anti-Patterns

• Polling GET /tasks/{task_id} repeatedly.
• WHY: This is inefficient, introduces latency, and creates unnecessary load on the agent. Use push notifications or the SSE stream for status updates.
• Returning large file data in a webhook or GET /tasks/{task_id} response.
• WHY: This makes API responses slow and brittle. Create an Artifact and return its ID. The orchestrator can then retrieve the artifact content separately and durably.
• Using custom, non-standard state names.
• WHY: This breaks the state machine contract and prevents orchestrators from correctly managing the task lifecycle. Adhere strictly to the defined states.
• Ignoring cancellation requests.
• WHY: An agent that does not respect POST /tasks/{task_id}/cancel wastes compute resources and can lead to unpredictable behavior. Always implement a graceful shutdown procedure for tasks.
• Failing a task without a descriptive error object.
• WHY: This makes debugging impossible. The error.code and error.message fields are essential for automated retries and operator analysis.

Compliance Checklist

• [ ] Agent serves a valid AgentCard.json from a well-known endpoint (e.g., /agent-card.json).
• [ ] Agent correctly implements all required API endpoints: POST /tasks, GET /tasks/{id}, POST /tasks/{id}/cancel, GET /tasks/{id}/artifacts, GET /artifacts/{id}/content.
• [ ] Submitted tasks correctly start in the SUBMITTED state and transition according to the specified lifecycle.
• [ ] Terminal states (COMPLETED, FAILED, CANCELLED) are final and immutable.
• [ ] Upon task status change, a valid push notification is sent to the configured notification_config.endpoint_url.
• [ ] The GET /tasks/{id}/stream endpoint provides a valid text/event-stream for tasks in the WORKING state.
• [ ] All generated artifacts conform to the Artifact schema.
• [ ] FAILED tasks include a structured error object in the task payload.
• [ ] All inputs, outputs, schemas, and timestamps conform to the formats defined in this reference.