> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Fundamental Communication Elements
> Defines core elements and flow for agent-to-agent communication including agent cards, messages and parts, tasks with streaming, artifacts as deliverables, discovery, transport, and authentication
Below is a clearer, more structured explanation of the core elements used in A2A (agent-to-agent) communication. The sequence follows discovery → messaging → long-running work → deliverables so you can map each technical diagram to the corresponding definitions and examples.
Agent Card
An Agent Card is essentially a "business card" for an AI agent. It tells other agents:
* Who the agent is (name, description, provider)
* Where to reach it (URL / endpoint)
* What it can do (capabilities and skills)
* How to authenticate (security requirements)
Capabilities can include features like streaming, push notifications, or state transition history. Skills are detailed entries that list name, id, description, tags, examples, and supported input/output modes — effectively the agent's advertised abilities.
Example Agent Card (Kubernetes-focused agent):
```json theme={null}
{
"name": "k8s_a2a_agent",
"description": "An example A2A agent that knows how to use Kubernetes tools.",
"url": "http://127.0.0.1:8083/api/a2a/kagent/k8s-a2a-agent/",
"capabilities": {
"streaming": true,
"pushNotifications": false,
"stateTransitionHistory": true
},
"skills": [
{
"id": "get-resources-skill",
"name": "Get Resources",
"description": "Get resources in the Kubernetes cluster",
"tags": ["k8s", "resources"],
"examples": [
"Get all resources in the Kubernetes cluster",
"Get the pods in the default namespace"
],
"inputModes": ["text"],
"outputModes": ["text"]
}
]
}
```
Agent discovery returns the Agent Card so other agents know how to connect, which capabilities are available, and what authentication is required. Exposing accurate capabilities and skill metadata improves automated routing and orchestration in multi-agent systems.
Messages and Parts
Messages are the basic units that agents exchange. Each message typically includes metadata (sender, unique ID) and a list of parts. A part contains the actual content and can be one of:
* text (plain user or system text)
* file (binary content encoded as Base64 with a MIME type)
* structured data (JSON payloads)
Example message parts:
```json theme={null}
{
"type": "text",
"text": "Get the pods in default namespace"
}
```
```json theme={null}
{
"type": "file",
"mimeType": "application/json",
"data": "base64-encoded-content"
}
```
```json theme={null}
{
"type": "data",
"data": {
"namespace": "default",
"resourceType": "pods"
}
}
```
Artifacts
Artifacts are the tangible outputs produced by agents. Unlike messages (which are transient communication), artifacts are deliverables: reports, structured results, files, images, or any persistent output. Artifacts have unique IDs, names, and parts (using the same parts schema as messages).
Example artifact (pod listing):
```json theme={null}
{
"taskId": "task-001",
"status": { "state": "completed" },
"artifacts": [
{
"artifactId": "artifact-001",
"name": "Pod List",
"parts": [
{
"type": "text",
"text": "Found 3 pods:\n- pod-1\n- pod-2\n- pod-3"
}
]
}
]
}
```
Common artifact types and examples:
| Artifact Type | Typical Use Case | Example |
| ----------------- | -------------------------------------------- | ------------------------------------------------- |
| Text artifact | Human-readable reports | `Finished analysis: 12 issues found` |
| Data artifact | Structured output for machine consumption | `{"reservationId":"abc123","status":"confirmed"}` |
| File artifact | Images, documents, or binary outputs | Base64-encoded image bytes |
| Mixed (Text/Data) | Aggregated outputs (e.g., list of resources) | `["pod-1","pod-2","pod-3"]` |
Artifacts can also be streamed incrementally as they are produced (useful for large or long-running tasks).
Tasks
Tasks model long-running or multi-step work that originates from a message. Tasks have well-defined lifecycles (submitted → working → completed/failed/canceled). While a task executes, it may stream status updates and partial artifacts before delivering final artifacts.
Example task lifecycle with streaming partial results then final results:
```json theme={null}
// Initial task submission
{
"taskId": "task-789",
"status": { "state": "submitted" }
}
// Update while working (streaming partial artifact)
{
"taskId": "task-789",
"status": { "state": "working", "message": "Processing your request..." },
"artifacts": [
{
"artifactId": "artifact-1",
"name": "Partial Results",
"parts": [{"type": "text", "text": "Found 2 pods so far..."}]
}
]
}
// Final result
{
"taskId": "task-789",
"status": { "state": "completed" },
"artifacts": [
{
"artifactId": "artifact-2",
"name": "Final Results",
"parts": [{"type": "text", "text": "Found 3 pods total"}]
}
]
}
```
End-to-end Example
This short flow demonstrates discovery → message → task updates → artifact results.
```http theme={null}
# Step 1: Discover Agent Card (Agent discovery endpoint)
GET http://127.0.0.1:8083/api/a2a/kagent/k8s-a2a-agent/.well-known/agent-card
# Server → Returns the Agent Card JSON shown earlier
```
```json theme={null}
# Step 2: Send Message
{
"messageId": "msg-001",
"role": "user",
"parts": [
{
"type": "text",
"text": "Get all pods in the default namespace"
}
]
}
```
```json theme={null}
# Step 3: Agent responds with a Task update (working)
{
"taskId": "task-001",
"status": {
"state": "working",
"message": "Querying Kubernetes cluster..."
}
}
```
```json theme={null}
# Step 4: Agent sends final Artifact (result)
{
"taskId": "task-001",
"status": { "state": "completed" },
"artifacts": [
{
"artifactId": "artifact-001",
"name": "Pod List",
"parts": [
{
"type": "text",
"text": "Found 3 pods:\n- pod-1\n- pod-2\n- pod-3"
}
]
}
]
}
```
Summary
* Agent discovery returns an Agent Card.
* Clients send Messages composed of Parts (text, files, structured data).
* Agents create Tasks for long-running work, stream status and partial Artifacts while working, and return final Artifacts when done.
Other important concepts
* Context: Groups related messages and tasks into sessions or conversations for consistent state.
* Transport: Use secure channels such as HTTPS. See: [HTTPS](https://developer.mozilla.org/en-US/docs/Glossary/HTTPS)
* Format: Standardize on formats like JSON and JSON-RPC 2.0. See: [JSON](https://www.json.org/json-en.html) and [JSON-RPC 2.0](https://www.jsonrpc.org/specification)
* Authentication: Prefer robust schemes such as OAuth 2.0 or API keys. See: [OAuth 2.0](https://oauth.net/2/)
* Agent discovery & extensions: Protocol-level mechanisms for how agents locate each other and how optional extensions are negotiated
Security reminder: always authenticate and encrypt agent endpoints. Exposing discovery endpoints without proper authentication or TLS can leak capabilities and create attack surfaces.
References
* Kubernetes Basics: [https://kubernetes.io/docs/concepts/overview/what-is-kubernetes/](https://kubernetes.io/docs/concepts/overview/what-is-kubernetes/)
* JSON: [https://www.json.org/json-en.html](https://www.json.org/json-en.html)
* JSON-RPC 2.0: [https://www.jsonrpc.org/specification](https://www.jsonrpc.org/specification)
* OAuth 2.0: [https://oauth.net/2/](https://oauth.net/2/)