Compare commits

..

2 Commits

Author SHA1 Message Date
Holt Skinner
0710b78dee ci(lint): Add API Linting Configuration 2026-02-10 13:04:58 -06:00
Darrel Miller
3628e974ef feat(linter): Add API Linter job to workflow for proto file validation against 2026-02-10 12:58:38 -06:00
62 changed files with 1630 additions and 6454 deletions

16
.github/CODEOWNERS vendored
View File

@ -5,14 +5,14 @@
# https://help.github.com/en/github/creating-cloning-and-archiving-repositories/about-code-owners#codeowners-syntax
* @a2aproject/a2a-tsc
docs/ @a2aproject/a2a-tsc
scripts/ @a2aproject/a2a-tsc
docs/ @a2aproject/tech-writing
scripts/ @a2aproject/tech-writing @a2aproject/google-a2a-eng
specification/ @a2aproject/a2a-tsc
docs/specification.md @a2aproject/a2a-tsc
GOVERNANCE.md @a2aproject/a2a-tsc
.mkdocs/ @a2aproject/a2a-tsc
.mkdocs.yml @a2aproject/a2a-tsc
README.md @a2aproject/a2a-tsc
.gemini/ @a2aproject/a2a-tsc
.mkdocs/ @a2aproject/a2a-tsc
.github/ @a2aproject/a2a-tsc
.mkdocs/ @a2aproject/tech-writing
.mkdocs.yml @a2aproject/tech-writing
README.md @a2aproject/tech-writing
.gemini/ @a2aproject/tech-writing @a2aproject/google-a2a-eng
.mkdocs/ @a2aproject/tech-writing
.github/ @a2aproject/tech-writing

View File

@ -19,12 +19,10 @@ AService
ASq
AStarlette
AUTOCOMMIT
Abhimanyu
Agentspace
Agno
Autogen
Bahasa
Besen
Blogs
CAs
CLIs
@ -77,12 +75,10 @@ Jhb
Jra
KGgo
KRW
LFX
LHR
LJcvt
LLM
LLMs
Lindfors
Lix
MSIs
MWpm
@ -91,13 +87,11 @@ Mvosg
Nszl
OIDC
OOa
OTP
Ollama
PLE
PLW
PMEEi
PTH
Petschulat
Polski
Portugu
QFdk
@ -105,11 +99,9 @@ Qvandrcy
RFCs
RPCs
RUF
SFDC
SLAs
SLF
SSLv
Siwach
Solax
TJS
TMDB
@ -118,7 +110,6 @@ URLTo
Upserting
Urke
VBORw
VHc
Vsb
WHB
WQi
@ -143,7 +134,6 @@ aacacac
aboutasha
achat
aconnect
actioncard
adk
adr
adrs
@ -191,7 +181,6 @@ codegen
codeowner
codespace
codewiki
cpb
crewai
datamodel
datapart
@ -201,7 +190,6 @@ dcfa
dde
deepwiki
direnv
dlai
docstrings
documentai
dotnet
@ -248,13 +236,11 @@ gstatic
gweb
hackathon
hackathons
hexpm
hqdefault
hughesthe
iana
iat
ietf
inardini
inbox
inmemory
ipynb
@ -270,7 +256,6 @@ konami
kty
langgraph
lerhaupt
lfx
linenums
linkedin
linting
@ -330,9 +315,7 @@ reportgen
reposted
rst
rvelicheti
sandijean
scm
siwachabhi
sllm
sourced
sourcing
@ -345,7 +328,6 @@ stephenh
styleguide
svn
systemctl
tablefmt
tagwords
tasksget
taskslist
@ -354,11 +336,8 @@ taskstate
taskstatus
textpart
threadsafe
tiangolo
toctree
tok
tolgaki
tomtom
toolkits
tracestate
ugc
@ -369,7 +348,6 @@ versioned
vnd
voa
vscode
vvvvvvvv
weavehacks
webform
webpage

View File

@ -1,6 +0,0 @@
Abhimanyu
lfx
Petschulat
SFDC
Siwach
siwachabhi

View File

@ -5,8 +5,7 @@
"**/images/**",
"**/samples/**",
"**/tests/**",
"**/.git/**",
"**/a2a_logo/**"
"**/.git/**"
],
"threshold": 3,
"reporters": ["html", "markdown"]

View File

@ -23,11 +23,6 @@ on:
types:
- published
workflow_dispatch:
inputs:
version:
description: 'Version to deploy to (e.g., v1.0.0)'
required: true
default: 'dev'
jobs:
build_and_deploy:
@ -55,9 +50,6 @@ jobs:
with:
python-version: 3.13
- name: Setup uv
uses: astral-sh/setup-uv@v7
- name: Restore pip cache
uses: actions/cache@v5
with:
@ -72,7 +64,7 @@ jobs:
- name: Setup Go
uses: actions/setup-go@v6
with:
go-version: '1.25'
go-version: '1.24'
- name: Install build tools
run: |
@ -100,6 +92,18 @@ jobs:
- name: Generate protocol specification files
run: ./scripts/build_docs.sh
- name: Generate and Build Python SDK Docs
run: |
# Find the path to the installed package
PACKAGE_PATH=$(python -c "import a2a, os; print(os.path.dirname(a2a.__file__))")
echo "Found 'a2a' package at: ${PACKAGE_PATH}"
# Generate RST source files from the installed package
sphinx-apidoc -f -o docs/sdk/python "${PACKAGE_PATH}"
# Build the HTML from the generated RST files
sphinx-build -b html docs/sdk/python docs/sdk/python/api
- name: Generate consolidated llms-full.txt file
run: bash scripts/build_llms_full.sh
@ -133,14 +137,3 @@ jobs:
bash scripts/deploy_root_files.sh ${{ github.repository }} ${{ secrets.GITHUB_TOKEN }}
env:
GITHUB_EVENT_RELEASE_TAG_NAME: ${{ github.event.release.tag_name }}
- name: Manually deploy specific version from main
if: github.event_name == 'workflow_dispatch'
run: |
mike deploy --push --update-aliases ${{ github.event.inputs.version }} latest
echo "Setting 'latest' as the default version for the site..."
mike set-default --push latest
# Re-deploy 404 page
bash scripts/deploy_root_files.sh ${{ github.repository }} ${{ secrets.GITHUB_TOKEN }}

View File

@ -29,7 +29,7 @@ jobs:
echo "last_month=$first_day..$last_day" >> "$GITHUB_ENV"
- name: Run issue-metrics tool
uses: github-community-projects/issue-metrics@v4
uses: github/issue-metrics@v3
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
SEARCH_QUERY: 'repo:a2aproject/A2A is:issue created:${{ env.last_month }} -reason:"not planned"'

View File

@ -38,26 +38,12 @@ jobs:
- name: Checkout Code
uses: actions/checkout@v6
- name: Install buf
run: |
curl -sSL "https://github.com/bufbuild/buf/releases/latest/download/buf-Linux-x86_64" -o buf
sudo mv buf /usr/local/bin/buf
sudo chmod +x /usr/local/bin/buf
- name: Download proto dependencies
working-directory: specification
run: |
buf dep update
buf export buf.build/googleapis/googleapis --output=.googleapis
- name: Install api-linter
run: |
curl -L https://github.com/googleapis/api-linter/releases/download/v1.67.6/api-linter-1.67.6-linux-amd64.tar.gz -o api-linter.tar.gz
tar -xzf api-linter.tar.gz
sudo mv api-linter /usr/local/bin/
sudo chmod +x /usr/local/bin/api-linter
- name: Run API Linter
run: |
# Run api-linter with exported googleapis protos
api-linter --config specification/.api-linter.yaml --output-format github --set-exit-status --proto-path specification --proto-path specification/.googleapis specification/a2a.proto
uses: googleapis/api-linter@v2.2.0
with:
# Lint all proto files in the specification directory
proto-path: specification
# Use the api-linter configuration file
config-path: specification/.api-linter.yaml
# Lint all proto files
args: specification/*.proto

View File

@ -27,7 +27,7 @@ jobs:
steps:
- name: check-spelling
id: spelling
uses: check-spelling/check-spelling@v0.0.26
uses: check-spelling/check-spelling@main
with:
suppress_push_for_open_pull_request: ${{ github.actor != 'dependabot[bot]' && 1 }}
checkout: true

2
.gitignore vendored
View File

@ -210,5 +210,3 @@ Thumbs.db
docs/sdk/python/_build/
docs/sdk/python/api/
docs/sdk/python/generated/
specification/.googleapis/

View File

@ -1,325 +1,514 @@
"""Custom MkDocs macros for A2A documentation.
"""
Custom MkDocs macros for A2A documentation.
This module provides macros for rendering Protocol Buffer definitions
as markdown tables.
"""
import re
from pathlib import Path
from typing import Any
from proto_schema_parser.ast import (
Comment,
Enum,
EnumValue,
Field,
MapField,
Message,
Method,
OneOf,
Service,
)
from proto_schema_parser.parser import Parser
from tabulate import tabulate
from typing import Dict, List, Optional, Tuple
# -----------------------------------------------------------------------------
# Configuration & Helpers
# -----------------------------------------------------------------------------
TYPE_MAP = {
'string': 'string',
'int32': 'integer',
'int64': 'integer',
'bool': 'boolean',
'bytes': 'bytes',
'double': 'float',
'float': 'float',
'google.protobuf.Struct': 'object',
'google.protobuf.Timestamp': 'timestamp',
'google.protobuf.Value': 'any',
'google.protobuf.Empty': 'empty',
}
# -----------------------------------------------------------------------------
# Main Macros
# -----------------------------------------------------------------------------
def _is_primitive_type(proto_type: str) -> bool:
"""Check if a proto type is a primitive type that shouldn't be linked."""
primitive_types = {
'string', 'int32', 'int64', 'bool', 'bytes',
'google.protobuf.Struct', 'google.protobuf.Timestamp'
}
return proto_type in primitive_types
def define_env(env):
"""Define custom macros for MkDocs."""
"""
Define custom macros for MkDocs.
def _parse_proto(file_path: str):
"""Parses a .proto file and returns the AST with comments attached."""
full_path = Path(env.conf['docs_dir']).parent / file_path
if not full_path.exists():
raise FileNotFoundError(f'Proto not found: {file_path}')
ast = Parser().parse(full_path.read_text(encoding='utf-8'))
_attach_comments(ast.file_elements)
return ast.file_elements
This function is called by the mkdocs-macros plugin.
"""
@env.macro
def proto_to_table(
message_name: str, proto_file: str = 'specification/a2a.proto'
) -> str:
"""Parses a .proto file and renders a message table."""
try:
elements = _parse_proto(proto_file)
except FileNotFoundError as e:
return f'**Error:** {e}'
def proto_to_table(proto_file: str, message_name: str) -> str:
"""
Parse a Protocol Buffer message definition and render it with description and table.
# Find the specific message object
target_message = _find_type(elements, message_name, Message)
if not target_message:
return f'**Error:** Message `{message_name}` not found.'
Args:
proto_file: Relative path to the .proto file (e.g., "specification/a2a.proto")
message_name: Name of the message to extract (e.g., "Message")
# Extract data
rows = []
oneof_groups = {} # Map[oneof_name] -> List[field_names]
Returns:
Markdown representation with description before table and notes after
"""
# Resolve the proto file path relative to the project root
project_root = Path(env.conf['docs_dir']).parent
proto_path = project_root / proto_file
# Iterate over elements inside the message
# elements can be Field, MapField, OneOf, Enum, Message, etc.
for el in target_message.elements:
# Handle Standard/Map Fields
if isinstance(el, Field | MapField):
rows.append(_process_field(el))
elif isinstance(el, OneOf):
for oneof_el in el.elements:
if isinstance(oneof_el, Field):
# Process field normally
row = _process_field(oneof_el, is_oneof=True)
rows.append(row)
# Add display name to group tracker
oneof_groups.setdefault(el.name, []).append(
row[0].strip('`') # Remove code ticks for the note
)
if not proto_path.exists():
return f"**Error:** Proto file not found: {proto_file}"
if not rows:
return 'None'
# Read the proto file content
content = proto_path.read_text(encoding='utf-8')
# Generate Output
# Extract the message definition between the region markers
pattern = rf'// --8<-- \[start:{re.escape(message_name)}\](.*?)// --8<-- \[end:{re.escape(message_name)}\]'
match = re.search(pattern, content, re.DOTALL)
if not match:
return f"**Error:** Message '{message_name}' not found in {proto_file}"
message_content = match.group(1)
# Extract description (before message), fields, and notes (after message)
description, fields, notes, oneof_groups = _parse_proto_message_full(message_content)
# Handle the case of empty proto message
if not fields:
return "None"
# Build the output
output = []
# Message Description
msg_desc = _extract_comments(target_message)
if msg_desc:
output.append(msg_desc)
output.append('')
if description:
output.append(description)
output.append('') # Empty line
# Render Table
headers = ['Field', 'Type', 'Required', 'Description']
output.append(tabulate(rows, headers, tablefmt='github'))
output.append(_generate_markdown_table(fields))
# Add OneOf Notes
# Add oneof notes after the table
if oneof_groups:
output.append('')
for _, fields in oneof_groups.items():
if len(fields) > 1:
field_list = ', '.join(f'`{f}`' for f in fields)
output.append(
f'**Note:** A `{message_name}` MUST contain exactly one of the following: {field_list}'
)
output.append('') # Empty line
for oneof_name, oneof_fields in oneof_groups.items():
if len(oneof_fields) > 1:
field_list = ', '.join(f'`{field}`' for field in oneof_fields)
output.append(f'**Note:** A {message_name} MUST contain exactly one of the following: {field_list}')
if notes:
output.append('') # Empty line
output.append(notes)
return '\n'.join(output)
@env.macro
def proto_enum_to_table(
enum_name: str, proto_file: str = 'specification/a2a.proto'
):
"""Parses a .proto file and renders an Enum table."""
try:
elements = _parse_proto(proto_file)
el = _find_type(elements, enum_name, Enum)
if not el:
return f'**Error:** Enum `{enum_name}` not found.'
def proto_enum_to_table(proto_file: str, enum_name: str) -> str:
"""
Parse a Protocol Buffer enum definition and render it with description and table.
rows = [
[f'`{e.name}`', _extract_comments(e)]
for e in el.elements
if isinstance(e, EnumValue)
]
return f'{_extract_comments(el)}\n\n' + tabulate(
rows, ['Value', 'Description'], tablefmt='github'
)
except Exception as e:
return f'**Error:** {e}'
Args:
proto_file: Relative path to the .proto file
enum_name: Name of the enum to extract
@env.macro
def proto_service_to_table(
service_name: str, proto_file: str = 'specification/a2a.proto'
) -> str:
"""Parses a .proto file and renders a Service table."""
try:
elements = _parse_proto(proto_file)
service = _find_type(elements, service_name, Service)
if not service:
return f'**Error:** Service `{service_name}` not found.'
Returns:
Markdown representation with description before table and notes after
"""
# Resolve the proto file path relative to the project root
project_root = Path(env.conf['docs_dir']).parent
proto_path = project_root / proto_file
rows = []
for el in service.elements:
if isinstance(el, Method):
# Request Type
# input_type is a MessageType(type='...', stream=True/False)
req_str = _format_type_for_docs(el.input_type.type)
if el.input_type.stream:
req_str = f'stream {req_str}'
if not proto_path.exists():
return f"**Error:** Proto file not found: {proto_file}"
# Response Type
res_str = _format_type_for_docs(el.output_type.type)
if el.output_type.stream:
res_str = f'stream {res_str}'
# Read the proto file content
content = proto_path.read_text(encoding='utf-8')
rows.append(
[
f'`{el.name}`',
req_str,
res_str,
_extract_comments(el),
]
)
# Extract the enum definition between the region markers
pattern = rf'// --8<-- \[start:{re.escape(enum_name)}\](.*?)// --8<-- \[end:{re.escape(enum_name)}\]'
match = re.search(pattern, content, re.DOTALL)
if not rows:
return 'None'
if not match:
return f"**Error:** Enum '{enum_name}' not found in {proto_file}"
headers = ['Method', 'Request', 'Response', 'Description']
return tabulate(rows, headers, tablefmt='github')
enum_content = match.group(1)
except Exception as e:
return f'**Error:** {e}'
# Extract description (before enum), values, and notes (after enum)
description, values, notes = _parse_proto_enum_full(enum_content)
if not values:
return f"**Error:** No values found in enum '{enum_name}'"
# Build the output
output = []
if description:
output.append(description)
output.append('') # Empty line
output.append(_generate_enum_table(values))
if notes:
output.append('') # Empty line
output.append(notes)
return '\n'.join(output)
# -----------------------------------------------------------------------------
# Helper Functions
# -----------------------------------------------------------------------------
def _should_skip_comment(comment_text: str) -> bool:
"""Check if a comment line should be skipped (protolint directives, region markers, etc.)."""
return (comment_text.startswith('protolint:') or
comment_text.startswith('--8<--') or
comment_text.startswith('Next ID:'))
def _extract_comments(element: Any) -> str:
"""Clean and combine comments from an AST element."""
cleaned_parts = []
raw_comments = getattr(element, 'comments', [])
def _parse_field_definition(field_def: str) -> Optional[Dict[str, any]]:
"""
Parse a single field definition and extract its components.
for comment in raw_comments:
text = (
comment.strip()
.removeprefix('//')
.removeprefix('/*')
.removesuffix('*/')
)
lines = (
line.strip().removeprefix('*').strip() for line in text.splitlines()
)
combined = ' '.join(filter(None, lines))
if combined and not combined.startswith(
(
'protolint:',
'--8<--',
'Next ID:',
'(-- api-linter',
'api-linter',
'aip.dev/not-precedent',
)
):
cleaned_parts.append(combined)
return ' '.join(cleaned_parts)
def _attach_comments(elements: list[Any]) -> None:
"""Recursively attach preceding comments to each non-comment element."""
buffer = []
for el in elements:
if isinstance(el, Comment):
buffer.append(el.text)
else:
# Attach collected comments to this element
el.comments = buffer
buffer = []
# Recursively handle nested elements (e.g. inside Message or OneOf)
if hasattr(el, 'elements'):
_attach_comments(el.elements)
def _format_type_for_docs(
proto_type: str, is_repeated: bool = False, map_key: str | None = None
) -> str:
"""Formats the type name with Markdown links for non-primitive types."""
# Handle fully qualified names by taking only the last part for the link label,
# but keep it if it's a known google.protobuf type we mapped.
display_name = TYPE_MAP.get(proto_type, proto_type.split('.')[-1])
is_primitive = proto_type in TYPE_MAP or proto_type.startswith(
'google.protobuf'
Returns:
Dict with keys: field_type, field_name, annotations, is_repeated, is_optional, is_required
or None if the field definition doesn't match any known pattern
"""
# Check for map type first
map_match = re.match(
r'map<[\w.]+,\s*([\w.]+)>\s+([\w_]+)\s*=\s*\d+(\s*\[(.*?)\])?;',
field_def
)
if map_match:
return {
'field_type': f'map<{map_match.group(1)}>',
'field_name': map_match.group(2),
'annotations': map_match.group(4) or '',
'is_repeated': False,
'is_optional': False,
'is_required': 'REQUIRED' in (map_match.group(4) or '')
}
# Create a slug for the link. Messages are usually CamelCase, so lowercase it.
label = f'`{display_name}`'
if not is_primitive:
label = f'[{label}](#{display_name.lower()})'
# Check for optional keyword
optional_match = re.match(
r'optional\s+([\w.]+)\s+([\w_]+)\s*=\s*\d+(\s*\[(.*?)])?;',
field_def
)
if optional_match:
return {
'field_type': optional_match.group(1),
'field_name': optional_match.group(2),
'annotations': optional_match.group(4) or '',
'is_repeated': False,
'is_optional': True,
'is_required': False
}
if map_key:
key_label = TYPE_MAP.get(map_key, map_key)
return f'map of {key_label} to {label}'
# Try regular field pattern
field_match = re.match(
r'(repeated\s+)?([\w.]+)\s+([\w_]+)\s*=\s*\d+(\s*\[(.*?)\])?;',
field_def
)
if field_match:
annotations = field_match.group(5) or ''
return {
'field_type': field_match.group(2),
'field_name': field_match.group(3),
'annotations': annotations,
'is_repeated': field_match.group(1) is not None,
'is_optional': False,
'is_required': 'REQUIRED' in annotations
}
if is_repeated:
return f'array of {label}'
return label
def _find_type(elements: list[Any], name: str, target_cls: type) -> Any | None:
"""Recursively searches for a Message or Enum by name."""
for el in elements:
if getattr(el, 'name', None) == name and isinstance(el, target_cls):
return el
if isinstance(el, Message):
found = _find_type(el.elements, name, target_cls)
if found:
return found
return None
def _process_field(field: Field, is_oneof: bool = False) -> list[str]:
"""Converts a Field or MapField object into a table row."""
options = getattr(field, 'options', [])
cardinality_obj = getattr(field, 'cardinality', None)
cardinality = (
getattr(cardinality_obj, 'value', None) if cardinality_obj else None
)
def _get_display_name(field_name: str, annotations: str) -> str:
"""Extract display name from json_name annotation or convert from snake_case."""
json_name_match = re.search(r'json_name\s*=\s*"([^"]+)"', annotations)
if json_name_match:
return json_name_match.group(1)
return _snake_to_camel_case(field_name)
# Determine Display Name (json_name vs snake_case)
json_name = next(
(o.value.strip('"') for o in options if o.name == 'json_name'), None
)
display_name = json_name or _snake_to_camel_case(field.name)
# Determine Type
is_map = isinstance(field, MapField)
is_repeated = cardinality == 'REPEATED'
def _determine_required_value(is_required: bool, is_optional: bool) -> str:
"""Determine the required column value for a field."""
if is_required:
return 'Yes'
elif is_optional:
return 'Optional'
return 'No'
type_to_format = field.value_type if is_map else field.type
map_key = getattr(field, 'key_type', None)
type_str = _format_type_for_docs(type_to_format, is_repeated, map_key)
def _parse_proto_message_full(content: str) -> Tuple[str, List[Dict[str, str]], str, Dict[str, List[str]]]:
"""
Parse proto message content and extract description, fields, and notes.
# Determine Required/Optional
has_required_behavior = any(
'REQUIRED' in str(opt.value)
for opt in options
if 'field_behavior' in opt.name
)
Returns:
Tuple of (description_before, fields, notes_after, oneof_groups)
where oneof_groups is a dict mapping oneof names to lists of field names
"""
fields = []
oneof_groups = {}
lines = content.split('\n')
current_comment = []
description_lines = []
notes_lines = []
inside_message = False
message_ended = False
inside_oneof = False
current_oneof_name = None
accumulated_line = ''
if is_oneof:
req_val = 'Optional (OneOf)'
elif cardinality == 'REQUIRED' or has_required_behavior:
req_val = 'Yes'
for line in lines:
stripped = line.strip()
# Collect description before the message declaration
if not inside_message and not message_ended:
if stripped.startswith('//'):
comment_text = stripped[2:].strip()
if not _should_skip_comment(comment_text):
description_lines.append(comment_text)
elif stripped.startswith('message '):
inside_message = True
continue
elif stripped: # Non-comment, non-message line
continue
# Collect notes after the message ends
elif message_ended:
if stripped.startswith('//'):
comment_text = stripped[2:].strip()
if not _should_skip_comment(comment_text):
notes_lines.append(comment_text)
continue
# Process content inside the message
elif inside_message:
# Check if message has ended
if stripped == '}' and not inside_oneof:
message_ended = True
continue
# Check for end of oneof block
if stripped == '}' and inside_oneof:
inside_oneof = False
current_oneof_name = None
continue
# Check for start of oneof block
oneof_match = re.match(r'oneof\s+([\w_]+)\s*{', stripped)
if oneof_match:
inside_oneof = True
current_oneof_name = oneof_match.group(1)
oneof_groups[current_oneof_name] = []
continue
# Collect comment lines for fields
if stripped.startswith('//'):
comment_text = stripped[2:].strip()
if not _should_skip_comment(comment_text):
current_comment.append(comment_text)
# Parse field definition - handle multi-line definitions
elif stripped and not stripped.startswith('message') and not stripped.startswith('enum'):
# Accumulate line if it doesn't end with semicolon
if accumulated_line:
accumulated_line += ' ' + stripped
else:
accumulated_line = stripped
# Process only when we have a complete field definition (ends with semicolon)
if not accumulated_line.endswith(';'):
continue
# Parse the complete field definition
field_info = _parse_field_definition(accumulated_line)
accumulated_line = '' # Reset for next field
if field_info:
# Convert proto type to readable format
readable_type = _format_proto_type(
field_info['field_type'],
field_info['is_repeated']
)
# Join comment lines
description = ' '.join(current_comment) if current_comment else ''
# Get display name and required value
display_name = _get_display_name(
field_info['field_name'],
field_info['annotations']
)
required_value = _determine_required_value(
field_info['is_required'],
field_info['is_optional']
)
fields.append({
'name': display_name,
'type': readable_type,
'required': required_value,
'description': description
})
# Track oneof fields
if inside_oneof and current_oneof_name:
oneof_groups[current_oneof_name].append(display_name)
# Reset comment buffer
current_comment = []
else:
# Reset comment buffer if not a field
if not inside_oneof:
current_comment = []
description = ' '.join(description_lines).strip()
notes = ' '.join(notes_lines).strip()
return description, fields, notes, oneof_groups
def _parse_proto_enum_full(content: str) -> Tuple[str, List[Dict[str, str]], str]:
"""
Parse proto enum content and extract description, values, and notes.
Returns:
Tuple of (description_before, values, notes_after)
"""
values = []
lines = content.split('\n')
current_comment = []
description_lines = []
notes_lines = []
inside_enum = False
enum_ended = False
for line in lines:
stripped = line.strip()
# Collect description before the enum declaration
if not inside_enum and not enum_ended:
if stripped.startswith('//'):
comment_text = stripped[2:].strip()
if not _should_skip_comment(comment_text):
description_lines.append(comment_text)
elif stripped.startswith('enum '):
inside_enum = True
continue
elif stripped: # Non-comment, non-enum line
continue
# Collect notes after the enum ends
elif enum_ended:
if stripped.startswith('//'):
comment_text = stripped[2:].strip()
if not comment_text.startswith('protolint:') and not comment_text.startswith('--8<--'):
notes_lines.append(comment_text)
continue
# Process content inside the enum
elif inside_enum:
# Check if enum has ended
if stripped == '}':
enum_ended = True
continue
# Collect comment lines
if stripped.startswith('//'):
comment_text = stripped[2:].strip()
# Skip protolint directives and region markers
if not comment_text.startswith('protolint:') and not comment_text.startswith('--8<--'):
current_comment.append(comment_text)
# Parse enum value definition
elif stripped and not stripped.startswith('enum'):
value_match = re.match(r'([\w_]+)\s*=\s*(\d+);', stripped)
if value_match:
value_name = value_match.group(1)
# Join comment lines
description = ' '.join(current_comment) if current_comment else ''
values.append({
'name': value_name,
'description': description
})
# Reset comment buffer
current_comment = []
description = ' '.join(description_lines).strip()
notes = ' '.join(notes_lines).strip()
return description, values, notes
def _format_proto_type(proto_type: str, is_repeated: bool) -> str:
"""
Format proto type to a more readable format with links to specification.
Non-primitive types are automatically linked to their anchor in specification.md.
"""
# Map proto types to readable types
type_map = {
'string': 'string',
'int32': 'integer',
'int64': 'integer',
'bool': 'boolean',
'bytes': 'bytes',
'google.protobuf.Struct': 'object',
'google.protobuf.Timestamp': 'timestamp',
}
# Check for map type first
map_match = re.match(r'map<(.+)>', proto_type)
if map_match:
value_type = map_match.group(1)
readable_value_type = type_map.get(value_type, value_type)
# Create link for non-primitive types
if not _is_primitive_type(value_type):
readable_value_type = f'[`{readable_value_type}`](#{value_type.lower()})'
else:
readable_value_type = f'`{readable_value_type}`'
return f'map of {readable_value_type}'
readable_type = type_map.get(proto_type, proto_type)
# Create link for non-primitive types
if not _is_primitive_type(proto_type):
formatted_type = f'[`{readable_type}`](#{proto_type.lower()})'
else:
req_val = 'No'
formatted_type = f'`{readable_type}`'
desc = _extract_comments(field)
if is_repeated:
return f'array of {formatted_type}'
return [f'`{display_name}`', type_str, req_val, desc]
return formatted_type
def _snake_to_camel_case(snake_str: str) -> str:
"""Convert snake_case to camelCase."""
"""
Convert snake_case to camelCase for field names.
"""
components = snake_str.split('_')
# Keep the first component lowercase, capitalize the rest
return components[0] + ''.join(x.title() for x in components[1:])
def _generate_markdown_table(fields: List[Dict[str, str]]) -> str:
"""
Generate a markdown table from field definitions.
"""
# Table header
table = "| Field | Type | Required | Description |\n"
table += "|-------|------|----------|-------------|\n"
# Table rows
for field in fields:
name = field['name']
field_type = field['type']
required = field['required']
description = field['description'].replace('\n', ' ').replace('|', '\\|')
table += f"| `{name}` | {field_type} | {required} | {description} |\n"
return table
def _generate_enum_table(values: List[Dict[str, str]]) -> str:
"""
Generate a markdown table from enum values.
"""
# Table header with much wider Value column hint
table = "| Value | Description |\n"
table += "|:--------------------------------------|:------------|\n"
# Table rows
for value in values:
name = value['name']
description = value['description'].replace('\n', ' ').replace('|', '\\|')
table += f"| `{name}` | {description} |\n"
return table

View File

@ -1,8 +1,3 @@
{% extends "base.html" %}
{% block announce %}
Join the new DeepLearning.AI short course: <strong>A2A: The Agent2Agent Protocol</strong>!
<a href="https://goo.gle/dlai-a2a" class="md-button">
Enroll for free
</a>
{% endblock %}
{% block announce %}{% endblock %}

View File

@ -1,88 +1,10 @@
# Changelog
## [1.0.0](https://github.com/a2aproject/A2A/compare/v0.3.0...v1.0.0) (2026-03-12)
### ⚠ BREAKING CHANGES
* **spec:** Combine `TaskPushNotificationConfig` and `PushNotificationConfig` ([#1500](https://github.com/a2aproject/A2A/issues/1500))
* **spec:** remove duplicated ID from the create task push config request ([#1487](https://github.com/a2aproject/A2A/issues/1487))
* **spec:** pluralize configs in `ListTaskPushNotificationConfigs` ([#1486](https://github.com/a2aproject/A2A/issues/1486))
* **spec:** Add LF prefix to the package. ([#1474](https://github.com/a2aproject/A2A/issues/1474))
* **spec:** Switch to non-complex IDs in requests ([#1389](https://github.com/a2aproject/A2A/issues/1389))
* **spec:** Standardize spelling of "canceled" to use American Spelling throughout ([#1283](https://github.com/a2aproject/A2A/issues/1283))
* **spec:** Align enum format with ADR-001 ProtoJSON specification ([#1384](https://github.com/a2aproject/A2A/issues/1384))
* **spec:** Remove redundant `final` field from `TaskStatusUpdateEvent` ([#1308](https://github.com/a2aproject/A2A/issues/1308))
* **spec:** Move `extendedAgentCard` field to `AgentCapabilities` ([#1307](https://github.com/a2aproject/A2A/issues/1307))
* **spec:** Fixes for the last_updated_after field ([#1358](https://github.com/a2aproject/A2A/issues/1358))
* **spec:** modernize oauth 2.0 flows - remove implicit/password, add device code / pkce ([#1303](https://github.com/a2aproject/A2A/issues/1303))
* **spec:** Make "message" field name consistent between protocol bindings ([#1302](https://github.com/a2aproject/A2A/issues/1302))
* **spec:** Remove deprecated fields from a2a.proto for v1.0 release ([#1301](https://github.com/a2aproject/A2A/issues/1301))
* **spec:** Rename `supportsAuthenticatedExtendedCard` to `supportsExtendedAgentCard` ([#1222](https://github.com/a2aproject/A2A/issues/1222))
* **spec:** Remove v1s from a2a url http bindings
* **spec:** Large refactor of specification to separate application protocol definition from mapping to transports
## [0.4.0](https://github.com/a2aproject/A2A/compare/v0.3.0...v0.4.0) (2025-09-15)
### Features
* **spec:** Add `tasks/list` method with filtering and pagination to the specification ([0a9f629](https://github.com/a2aproject/A2A/commit/0a9f629e801d4ae89f94991fc28afe9429c91cbc))
* **spec:** modernize oauth 2.0 flows - remove implicit/password, add device code / pkce ([#1303](https://github.com/a2aproject/A2A/issues/1303)) ([525ff38](https://github.com/a2aproject/A2A/commit/525ff38e5fe2a118f5be5d25189708b590616dd4))
* **spec:** Natively Support Multi-tenancy on gRPC through an additional scope field on the request. ([#1195](https://github.com/a2aproject/A2A/issues/1195)) ([cfbce32](https://github.com/a2aproject/A2A/commit/cfbce32cb0ac2a630597eb8b771691cac5b20a4b)), closes [#1148](https://github.com/a2aproject/A2A/issues/1148)
* **spec:** Provide ability for SDKs to be backwards compatible. ([#1401](https://github.com/a2aproject/A2A/issues/1401)) ([227e249](https://github.com/a2aproject/A2A/commit/227e2493c317004b7e6f7ef4a484e220ffd0b77e))
* **spec:** Remove v1s from a2a url http bindings ([1bd263f](https://github.com/a2aproject/A2A/commit/1bd263f5373fdc8fa7c17ec8bdb24088996b6828))
### Bug Fixes
* Add missing metadata field to Part message in gRPC specification ([#1019](https://github.com/a2aproject/A2A/issues/1019)) ([b3b266d](https://github.com/a2aproject/A2A/commit/b3b266d127dde3d1000ec103b252d1de81289e83)), closes [#1005](https://github.com/a2aproject/A2A/issues/1005)
* Add name field to FilePart protobuf message ([#983](https://github.com/a2aproject/A2A/issues/983)) ([2b7cb6f](https://github.com/a2aproject/A2A/commit/2b7cb6f8408e6324c48fb82c71839c67a18f1fab)), closes [#984](https://github.com/a2aproject/A2A/issues/984)
* Clarify blocking calls return on interrupted states ([#1403](https://github.com/a2aproject/A2A/issues/1403)) ([0655ff3](https://github.com/a2aproject/A2A/commit/0655ff324a93b7e0eaebc108666e6703998b4a9c))
* **doc:** Makes JSON-RPC SendMessage response clearer ([#1241](https://github.com/a2aproject/A2A/issues/1241)) ([5792804](https://github.com/a2aproject/A2A/commit/57928043727e5e002a1395dadfb5f699d0626b1c))
* **docs:** Clearer wording around context id. ([#1588](https://github.com/a2aproject/A2A/issues/1588)) ([dec790a](https://github.com/a2aproject/A2A/commit/dec790aa063943e3ac70e972f9da513c25ab420c))
* **grpc:** Fix inconsistent property name between gRPC and JSON-RPC in Message object ([#1100](https://github.com/a2aproject/A2A/issues/1100)) ([2a1f819](https://github.com/a2aproject/A2A/commit/2a1f819aaa2540602ee81498e159ebe0192be818))
* **grpc:** missing field in gRPC spec - state_transition_history ([#1138](https://github.com/a2aproject/A2A/issues/1138)) ([a2de798](https://github.com/a2aproject/A2A/commit/a2de7981cadeaa5197bee56cbd6ab7b2c5da2541)), closes [#1139](https://github.com/a2aproject/A2A/issues/1139)
* **grpc:** Update `CreateTaskPushNotificationConfig` endpoint to `/v1/{parent=tasks/*/pushNotificationConfigs}` ([#979](https://github.com/a2aproject/A2A/issues/979)) ([911f9b0](https://github.com/a2aproject/A2A/commit/911f9b059c52dd65497b76ccf63d196ca84c7f0e))
* **proto:** Add icon_url to a2a.proto ([#986](https://github.com/a2aproject/A2A/issues/986)) ([17e7f62](https://github.com/a2aproject/A2A/commit/17e7f62df9a3e4ca0768ab8d4f0bb7573b3d73e1))
* **proto:** Adds metadata field to A2A DataPart proto ([#1004](https://github.com/a2aproject/A2A/issues/1004)) ([a8b45dc](https://github.com/a2aproject/A2A/commit/a8b45dcc429a5571ef8a24c36336bf84b89bbd7f))
* Remove unimplemented state_transition_history capability field ([#1396](https://github.com/a2aproject/A2A/issues/1396)) ([c768a44](https://github.com/a2aproject/A2A/commit/c768a44da0f719595e375636f3cab9898ff6df75)), closes [#1228](https://github.com/a2aproject/A2A/issues/1228)
* Restore CreateTaskPushNotificationConfig method naming ([#1402](https://github.com/a2aproject/A2A/issues/1402)) ([d14f410](https://github.com/a2aproject/A2A/commit/d14f4107119bf0fe0dff9e2c577eb4ab70b51793))
* Revert "chore(gRPC): Update a2a.proto to include metadata on GetTaskRequest" ([#1000](https://github.com/a2aproject/A2A/issues/1000)) ([e6b8c65](https://github.com/a2aproject/A2A/commit/e6b8c654a86a6ee461bb5c7be5d5b81004b80a92))
* Simplify Part message structure by flattening FilePart and DataPart ([#1411](https://github.com/a2aproject/A2A/issues/1411)) ([bfae8f7](https://github.com/a2aproject/A2A/commit/bfae8f7791e019f21f6662dd73fce0b3ab261cd6))
* **spec:** Add LF prefix to the package. ([#1474](https://github.com/a2aproject/A2A/issues/1474)) ([a54e809](https://github.com/a2aproject/A2A/commit/a54e80904aa32c74a14bc2c3d21bf82936ccbbdd))
* **spec:** add metadata to `CancelTaskRequest` ([#1485](https://github.com/a2aproject/A2A/issues/1485)) ([c441b91](https://github.com/a2aproject/A2A/commit/c441b910b64d45514ae929a42e7367c2a9a2f6c3)), closes [#1484](https://github.com/a2aproject/A2A/issues/1484)
* **spec:** Added clarification on timestamps in HTTP query params ([#1425](https://github.com/a2aproject/A2A/issues/1425)) ([6292104](https://github.com/a2aproject/A2A/commit/6292104e359efca05bd8703174517b6f961ae4e1))
* **spec:** Added clarifying text around messages and artifacts ([#1424](https://github.com/a2aproject/A2A/issues/1424)) ([b03d141](https://github.com/a2aproject/A2A/commit/b03d141aeab6abd71a229e85c81f7e4c00b537ec))
* **spec:** Adjust field number for `ListTasksRequest.tenant` to prevent missing number ([#1470](https://github.com/a2aproject/A2A/issues/1470)) ([cd16c52](https://github.com/a2aproject/A2A/commit/cd16c5276b4c662ca1823678d07487a624cad606))
* **spec:** Clarify contextId behavior when message is sent with taskId but without contextId ([#1309](https://github.com/a2aproject/A2A/issues/1309)) ([a336a5a](https://github.com/a2aproject/A2A/commit/a336a5a4846fdf85079d4e310339ea0128922ee7))
* **spec:** Clarify versioning strategy and client responsibilities in protocol specification ([#1259](https://github.com/a2aproject/A2A/issues/1259)) ([a4afeea](https://github.com/a2aproject/A2A/commit/a4afeea788b3877101f7a63c2e50091709490058))
* **spec:** Fix/1251 clarify authentication scheme ([#1256](https://github.com/a2aproject/A2A/issues/1256)) ([3e6c7db](https://github.com/a2aproject/A2A/commit/3e6c7db90790c2d05dad3ab1a313de26debe5cb7))
* **spec:** Fixes for the last_updated_after field ([#1358](https://github.com/a2aproject/A2A/issues/1358)) ([0e204bf](https://github.com/a2aproject/A2A/commit/0e204bf878eb63619e205d3419ebc48d4cd35849))
* **spec:** Make "message" field name consistent between protocol bindings ([#1302](https://github.com/a2aproject/A2A/issues/1302)) ([1e5f462](https://github.com/a2aproject/A2A/commit/1e5f46206403982cc629a0dad535856b28c269aa)), closes [#1230](https://github.com/a2aproject/A2A/issues/1230)
* **spec:** make `history_length` optional ([#1071](https://github.com/a2aproject/A2A/issues/1071)) ([0572953](https://github.com/a2aproject/A2A/commit/057295311b8ddda63bdda56c82a694c76d307e37))
* **spec:** pluralize configs in `ListTaskPushNotificationConfigs` ([#1486](https://github.com/a2aproject/A2A/issues/1486)) ([cf735cb](https://github.com/a2aproject/A2A/commit/cf735cb87056ff6d62abd21a1a66ccb14a23c38e))
* **spec:** Remove config from binding. ([#1587](https://github.com/a2aproject/A2A/issues/1587)) ([010b9cc](https://github.com/a2aproject/A2A/commit/010b9cc936fbafd66610282ad66070da2cb28855))
* **spec:** Remove deprecated fields from a2a.proto for v1.0 release ([#1301](https://github.com/a2aproject/A2A/issues/1301)) ([60f83c3](https://github.com/a2aproject/A2A/commit/60f83c3faac4770b231f038406c9e02282887a25)), closes [#1227](https://github.com/a2aproject/A2A/issues/1227)
* **spec:** remove duplicated ID from the create task push config request ([#1487](https://github.com/a2aproject/A2A/issues/1487)) ([393898d](https://github.com/a2aproject/A2A/commit/393898dfeefa37186aced5b61733c5d2c0d9c34a))
* **spec:** Remove metadata field from ListTasksRequest ([#1235](https://github.com/a2aproject/A2A/issues/1235)) ([b6ef9ee](https://github.com/a2aproject/A2A/commit/b6ef9eec558c877fb69024df090a8bb63c542a1c))
* **spec:** Remove reserved and fix tags ordering ([#1494](https://github.com/a2aproject/A2A/issues/1494)) ([1997c9d](https://github.com/a2aproject/A2A/commit/1997c9d63058ca0b89361a7d6e508f4641a6f68b))
* **spec:** Rename `supportsAuthenticatedExtendedCard` to `supportsExtendedAgentCard` ([#1222](https://github.com/a2aproject/A2A/issues/1222)) ([c196824](https://github.com/a2aproject/A2A/commit/c196824396bb4af4c595f30e2c503a5ab1dbac4b)), closes [#1215](https://github.com/a2aproject/A2A/issues/1215)
* **spec:** Standardize spelling of "canceled" to use American Spelling throughout ([#1283](https://github.com/a2aproject/A2A/issues/1283)) ([4dd980f](https://github.com/a2aproject/A2A/commit/4dd980f6ff1989177faffa631a695aba811c56ad))
* **spec:** Suggest Unique Identifier fields to be UUID ([#966](https://github.com/a2aproject/A2A/issues/966)) ([00cf76e](https://github.com/a2aproject/A2A/commit/00cf76e7bbc752842ef254f3d4136ed1b5751f6e))
* **spec:** Switch to non-complex IDs in requests ([#1389](https://github.com/a2aproject/A2A/issues/1389)) ([2596c1c](https://github.com/a2aproject/A2A/commit/2596c1c5e0effd941880e8487d38d78b74b9c0bf)), closes [#1390](https://github.com/a2aproject/A2A/issues/1390)
* **spec:** Update security schemes example ([#1364](https://github.com/a2aproject/A2A/issues/1364)) ([f9a8f5b](https://github.com/a2aproject/A2A/commit/f9a8f5b85d5b07824c52d55d63f7d71ccc6303c5))
* Update the Java tutorials and descriptions ([#1181](https://github.com/a2aproject/A2A/issues/1181)) ([202aa06](https://github.com/a2aproject/A2A/commit/202aa069e66f701bacf2156d42d8916fc96a5188))
### Documentation
* **spec:** Align enum format with ADR-001 ProtoJSON specification ([#1384](https://github.com/a2aproject/A2A/issues/1384)) ([810eaa1](https://github.com/a2aproject/A2A/commit/810eaa1c6e6462f845a00774f8622b998272116e)), closes [#1344](https://github.com/a2aproject/A2A/issues/1344)
### Code Refactoring
* **spec:** Combine `TaskPushNotificationConfig` and `PushNotificationConfig` ([#1500](https://github.com/a2aproject/A2A/issues/1500)) ([d1ed0da](https://github.com/a2aproject/A2A/commit/d1ed0da587d2d634ba0b81a40d082cee0850b81b))
* **spec:** Large refactor of specification to separate application protocol definition from mapping to transports ([b078419](https://github.com/a2aproject/A2A/commit/b0784199543eebf2e95dcb02e9336cb213923506))
* **spec:** Move `extendedAgentCard` field to `AgentCapabilities` ([#1307](https://github.com/a2aproject/A2A/issues/1307)) ([40d6286](https://github.com/a2aproject/A2A/commit/40d6286fbe29fb083d416b77e84122df8d70ae9d))
* **spec:** Remove redundant `final` field from `TaskStatusUpdateEvent` ([#1308](https://github.com/a2aproject/A2A/issues/1308)) ([5b101cc](https://github.com/a2aproject/A2A/commit/5b101cce0fff449c1120ad50ce360acf7c90bac3))
* **spec:** Add `tasks/list` method for retrieving and filtering tasks with pagination
## [0.3.0](https://github.com/a2aproject/A2A/compare/v0.2.6...v0.3.0) (2025-07-30)

View File

@ -72,7 +72,7 @@ an environment where participants feel welcome and safe.
Reports should be directed to [a2a-coc@googlegroups.com](mailto:a2a-coc@googlegroups.com), the
Project Steward(s) for A2A. It is the Project Steward’s duty to
receive and address reported violations of the code of conduct. They will then
work with a committee consisting of representatives from the A2A project and leadership.
work with a committee consisting of representatives from the A2A project and leadership.
We will investigate every complaint, but you may not receive a direct response.
We will use our discretion in determining when and how to follow up on reported
@ -87,4 +87,4 @@ harassment or threats to anyone's safety, we may take action without notice.
This Code of Conduct is adapted from the Contributor Covenant, version 1.4,
available at
https://www.contributor-covenant.org/version/1/4/code-of-conduct/
https://www.contributor-covenant.org/version/1/4/code-of-conduct.html

View File

@ -2,84 +2,7 @@
We'd love to accept your patches and contributions to this project.
## Development Setup
### Prerequisites
To contribute to this project, you will need the following tools installed:
- [Python 3.10+](https://www.python.org/downloads/)
- [uv](https://docs.astral.sh/uv/getting-started/installation/) - Fast Python package installer and resolver.
- [Node.js & npm](https://nodejs.org/en/download/) - For markdown formatting tools.
- [Docker](https://www.docker.com/get-started) - Required for running the local linter.
## Working with Documentation
The A2A documentation is built using [MkDocs](https://www.mkdocs.org/) with the [Material theme](https://squidfunk.github.io/mkdocs-material/).
### Local Setup
1. **Create a virtual environment:**
```bash
uv venv .doc-venv
```
2. **Activate the virtual environment:**
```bash
source .doc-venv/bin/activate # Unix/macOS
# .doc-venv\Scripts\activate # Windows
```
3. **Install dependencies:**
```bash
uv pip install -r requirements-docs.txt
```
### Build and Serve
1. **Build the documentation:**
This script regenerates the JSON schema from the protocol definition, builds the SDK documentation, and then builds the MkDocs site.
```bash
./scripts/build_docs.sh
```
2. **Serve the documentation locally:**
Run the following command to start a local server with live reloading:
```bash
mkdocs serve
```
3. **View the documentation:**
Open [http://localhost:8000](http://localhost:8000) in your browser.
## Code Standards
### Linting
We use [Super Linter](https://github.com/super-linter/super-linter) to ensure code quality across the repository. You can run the linter locally using Docker:
```bash
./scripts/lint.sh
```
### Formatting
We use [markdownlint](https://github.com/igorshubovych/markdownlint-cli) for formatting markdown files. You can fix most formatting issues automatically by running:
```bash
./scripts/format.sh
```
### Conventional Commits
We follow the [Conventional Commits](https://www.conventionalcommits.org/) specification for our commit messages. This helps us automate our release process and maintain a clear changelog.
## Contribution Process
## Contribution process
### Code reviews
@ -88,17 +11,18 @@ use GitHub pull requests for this purpose. Consult
[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more
information on using pull requests.
### Workflow
### Contributor Guide
You may follow these steps to contribute:
1. **Fork the official repository.** This will create a copy of the official repository in your own account.
2. **Sync the branches.** This will ensure that your copy of the repository is up-to-date with the latest changes from the official repository.
3. **Work on your forked repository's feature branch.** This is where you will make your changes to the code.
4. **Test your changes.** Build and preview the documentation locally to ensure everything looks correct.
5. Format and lint your code. Run ./scripts/format.sh and ./scripts/lint.sh to ensure your changes meet our standards.
6. **Commit your updates.** Use conventional commit messages on your feature branch.
7. **Submit a pull request.** Submit a PR from your fork's feature branch to the official repository's `main` branch.
8. **Resolve any feedback.** Work with reviewers to address any comments or requested changes.
4. **Commit your updates on your forked repository's feature branch.** This will save your changes to your copy of the repository.
5. **Submit a pull request to the official repository's main branch.** This will request that your changes be merged into the official repository.
6. **Resolve any linting errors.** This will ensure that your changes are formatted correctly.
Be patient! It may take some time for your pull request to be reviewed and merged.
Here are some additional things to keep in mind during the process:
- **Test your changes.** Before you submit a pull request, make sure that your changes work as expected.
- **Be patient.** It may take some time for your pull request to be reviewed and merged.

View File

@ -6,8 +6,8 @@ The Agent2Agent project is governed by the Technical Steering Committee. The Com
| :--- | :--- | :--- | :--- |
| **Google** | Todd Segal | Principal Engineer | [@ToddSegal](https://github.com/ToddSegal) |
| **Microsoft** | Darrel Miller | Partner API Architect | [@darrelmiller](https://github.com/darrelmiller) |
| **Cisco** | Luca Muscariello | Distinguished Engineer | [@muscariello](https://github.com/muscariello) |
| **Amazon Web Services** | Abhimanyu Siwach | Senior Software Engineer | [@siwachabhi](https://github.com/siwachabhi) |
| **Cisco** | Luca Muscariello | Principal Engineer | [@muscariello](https://github.com/muscariello) |
| **Amazon Web Services** | Nicholas Aldridge | Principal Engineer | [@000-000-000-000-000](https://github.com/000-000-000-000-000) |
| **Salesforce** | Stephen Petschulat | Principal Architect | [@spetschulatSFDC](https://github.com/spetschulatSFDC) |
| **ServiceNow** | Sean Hughes | Director of Open Science | [@hughesthe1st](https://github.com/hughesthe1st) |
| **SAP** | Sivakumar N. | Vice President | [@SivaNSAP](https://github.com/SivaNSAP) |
@ -32,8 +32,6 @@ The Agent2Agent project is governed by the Technical Steering Committee. The Com
a. **"Startup Phase."** At the inception of the Project, each organization listed in the [`GOVERNANCE`](GOVERNANCE.md) file in the governance repository of the Project will have the right to appoint (and remove and replace) one employee to serve as a voting member of the TSC.
Adding new organizations to the GOVERNANCE file will be determined through a proposal to the TSC GOVERNANCE.md file. Any new organization will be added through a majority vote of the TSC, and an employee of that organization will serve as a voting member of the TSC.
b. **"Steady State."** The TSC will decide upon a "steady state" composition of the TSC (whether by election, subproject technical leads, or other method as determined by the TSC), to take effect from the date that is 18 months following the inception of the Project, or at such other point as determined by the TSC.
c. The TSC may choose an alternative approach for determining the voting members of the TSC, and any such alternative approach will be documented in the GOVERNANCE file. Any meetings of the Technical Steering Committee are intended to be open to the public, and can be conducted electronically, via teleconference, or in person.
@ -69,8 +67,6 @@ While the Project aims to operate as a consensus-based community, if any TSC dec
Quorum for TSC meetings requires at least fifty percent of all voting members of the TSC to be present. The TSC may continue to meet if quorum is not met but will be prevented from making any decisions at the meeting. Except as provided in Section 7.c. and 8.a, decisions by vote at a meeting require a majority vote of those in attendance, provided quorum is met. Decisions made by electronic vote without a meeting require a majority vote of all voting members of the TSC.
A voting member who has not attended a meeting of the TSC within the last six weeks (as measured by the LFX attendance tracking) shall be determined to be an inactive voting member. They will not be included in active votes, which means that they will not be counted for quorum, and the sponsoring organization may choose to replace the named TSC member within a reasonable timeframe.
### TSC Meetings
TSC Meetings are held on the Linux Foundation's meeting platform. [https://zoom-lfx.platform.linuxfoundation.org/meetings/agent2agent](https://zoom-lfx.platform.linuxfoundation.org/meetings/agent2agent) has meeting details and recordings of past meetings.
Our [working doc for TSC Meeting Agendas](https://docs.google.com/document/d/1Dx6qYfCjSChHKRMwLJcvtDjq6igYTAKFW9Vg1IMPCUk/view) is in Google Docs.

View File

@ -56,19 +56,9 @@ With A2A, agents can:
- Securely collaborate on long-running tasks.
- Operate without exposing their internal state, memory, or tools.
## DeepLearning.AI Course
## Intro to A2A Video
[![A2A DeepLearning.AI](https://img.youtube.com/vi/4gYm0Rp7VHc/maxresdefault.jpg)](https://goo.gle/dlai-a2a)
Join this short course on [A2A: The Agent2Agent Protocol](https://goo.gle/dlai-a2a), built in partnership with Google Cloud and IBM Research, and taught by [Holt Skinner](https://github.com/holtskinner), [Ivan Nardini](https://github.com/inardini), and [Sandi Besen](https://github.com/sandijean90).
**What you'll learn:**
- **Make agents A2A-compliant:** Expose agents built with frameworks like Google ADK, LangGraph, or BeeAI as A2A servers.
- **Connect agents:** Create A2A clients from scratch or using integrations to connect to A2A-compliant agents.
- **Orchestrate workflows:** Build sequential and hierarchical workflows of A2A-compliant agents.
- **Multi-agent systems:** Build a healthcare multi-agent system using different frameworks and see how A2A enables collaboration.
- **A2A and MCP:** Learn how A2A complements MCP by enabling agents to collaborate with each other.
[![A2A Intro Video](https://img.youtube.com/vi/Fbr_Solax1w/maxresdefault.jpg)](https://goo.gle/a2a-video)
## Why A2A?

View File

@ -1,55 +0,0 @@
# A2A Protocol Ships v1.0: Production-Ready Standard for Agent-to-Agent Communication
The A2A Protocol community today are announcing the release of A2A Protocol v1.0, marking the first stable, production-ready version of the open standard for communication between AI agents. The protocol is guided by a technical steering committee with representatives from eight major technology companies.
As organizations build increasingly sophisticated multi-agent systems, interoperability has become the defining challenge. Teams can coordinate agents effectively within a single platform, but connecting those systems across technology stacks and organizational boundaries remains difficult. A2A addresses that challenge by combining support for multiple protocol bindings, seamless version negotiation, and a common semantic model so agents can interoperate across systems with predictable behavior.
The v1.0 release emphasizes maturity rather than reinvention: the core ideas remain intact, while rough edges have been removed, ambiguous areas clarified, and enterprise deployment requirements addressed more directly. The official SDKs ensure v1.0 A2A agents work seamlessly with older versions.
## Delivering on enterprise requirements
The v1.0 release introduces several capabilities aimed at production environments where trust, scale, and operational control are non-negotiable.
- **Heterogeneous environment support** enables interoperability across diverse technology stacks through multi-protocol bindings and version negotiation, so enterprises are not tied to a single vendor or platform.
- **Multi-tenancy support** allows a single endpoint to securely host many agents.
- **Signed Agent Cards** provide cryptographic verification of agent identity and metadata, establishing trust before interaction across organizational boundaries.
- **Improved security posture** modernizes security flows and removes legacy patterns that are no longer aligned with current best practices.
Together, these changes move A2A from early adopter implementations toward broader enterprise confidence, especially in regulated or multi-party scenarios.
## Web-aligned architecture for scale
A2A v1.0 aligns with core architectural principles of the web: stateless, layered architecture, standard protocol bindings, and infrastructure-friendly communication patterns. That alignment matters operationally because organizations can scale agent interactions with the same proven load balancing, gateway, security and observability patterns they already use for web systems.
The standard builds on industry-proven protocols, including JSON+HTTP, gRPC, and JSON-RPC. It also keeps the barrier to entry low: in its simplest form, an A2A interaction can begin with a single HTTP request.
A2A also gives consumers flexibility in how they receive results. Depending on workload and operational needs, clients can use polling, streaming, or webhooks to consume task updates and responses.
## Complementary to MCP, not a replacement
The release also reinforces A2A's relationship with the Model Context Protocol (MCP), a point that has generated confusion in early ecosystem discussions.
MCP and A2A solve different layers of the problem. MCP is commonly used for tool and context integration at the individual agent level. A2A focuses on communication and coordination between agents. In practice, many systems will use both: MCP inside agents, A2A between agents.
## Smooth migration from earlier versions
The v1.0 release tightens specification behavior, which includes breaking changes in the interaction protocol. AgentCard, however, has evolved in a backward-compatible way and now allows agents to advertise support for both existing v0.3 protocol behavior and v1.0 simultaneously. This enables clients to migrate progressively rather than through a single cutover.
That approach is intended to protect current investments while still delivering the benefits of a cleaner, more durable standard.
## Why this release matters now
AI agents are increasingly deployed across departments, products, and partner ecosystems. At that scale, the key question is no longer whether agents can coordinate within one stack, but whether they can collaborate reliably across organizational and platform boundaries. Open protocols determine whether organizations can compose best-of-breed systems or become locked into isolated stacks.
A2A v1.0 gives the market a stronger foundation for open multi-agent collaboration. The community is now focused on delivering multi-language v1.0 SDK support to help developers build conformant solutions with ease.
The complete v1.0 materials, including specification and migration documentation, are available at [a2a-protocol.org](https://a2a-protocol.org) and on [GitHub](https://github.com/a2aproject/A2A).
---
**About A2A Protocol**
The Agent-to-Agent (A2A) Protocol is an open standard that enables AI agents to discover capabilities, communicate, and delegate tasks across teams, products, and organizations. The A2A Technical Steering Committee includes representatives from AWS, Cisco, Google, IBM Research, Microsoft, Salesforce, SAP, and ServiceNow.
**Media Contact**
A2A Protocol Community
[https://a2a-protocol.org](https://a2a-protocol.org)

Binary file not shown.

Before

Width:  |  Height:  |  Size: 30 KiB

File diff suppressed because one or more lines are too long

Before

Width:  |  Height:  |  Size: 51 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 31 KiB

File diff suppressed because one or more lines are too long

Before

Width:  |  Height:  |  Size: 51 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 15 KiB

File diff suppressed because one or more lines are too long

Before

Width:  |  Height:  |  Size: 43 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 15 KiB

File diff suppressed because one or more lines are too long

Before

Width:  |  Height:  |  Size: 43 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 14 KiB

File diff suppressed because one or more lines are too long

Before

Width:  |  Height:  |  Size: 43 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 226 KiB

File diff suppressed because one or more lines are too long

Before

Width:  |  Height:  |  Size: 125 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 28 KiB

File diff suppressed because one or more lines are too long

Before

Width:  |  Height:  |  Size: 51 KiB

View File

@ -67,39 +67,6 @@ These agentic frameworks have built-in A2A integration, making it easy to get st
- [Slide (Tyler)](https://slide.mintlify.app/guides/a2a-integration)
- [Strands Agents](https://strandsagents.com/latest/documentation/docs/user-guide/concepts/multi-agent/agent-to-agent/)
## Community SDKs
Building an A2A agent in a language not covered by the [official SDKs](./sdk/index.md)? These community-maintained implementations have you covered.
### 🦀 Rust — a2a-rust
![Stars](https://img.shields.io/github/stars/tomtom215/a2a-rust?style=flat-square) [![Crate](https://img.shields.io/crates/v/a2a-protocol-sdk?style=flat-square)](https://crates.io/crates/a2a-protocol-sdk)
[tomtom215/a2a-rust](https://github.com/tomtom215/a2a-rust) · A2A spec v1.0.0 · Full SDK with JSON-RPC, REST, WebSocket, and gRPC transports.
### 🦀 Rust — a2a-rs
![Stars](https://img.shields.io/github/stars/EmilLindfors/a2a-rs?style=flat-square) [![Crate](https://img.shields.io/crates/v/a2a-rs?style=flat-square)](https://crates.io/crates/a2a-rs)
[EmilLindfors/a2a-rs](https://github.com/EmilLindfors/a2a-rs) · A2A spec v0.3.0 · Modular workspace with core protocol, AP2 extension, and agent framework.
### 🍎 Swift — A2AClient
![Stars](https://img.shields.io/github/stars/tolgaki/a2a-client-swift?style=flat-square)
[tolgaki/a2a-client-swift](https://github.com/tolgaki/a2a-client-swift) · A2A spec v1.0.0 · Swift Package Manager. iOS 15+, macOS 12+, watchOS 8+, tvOS 15+.
### 💧 Elixir — a2a
![Stars](https://img.shields.io/github/stars/actioncard/a2a-elixir?style=flat-square) [![Hex](https://img.shields.io/hexpm/v/a2a?style=flat-square)](https://hex.pm/packages/a2a)
[actioncard/a2a-elixir](https://github.com/actioncard/a2a-elixir) · A2A spec v0.2.0 · OTP-native with Agent behaviour, TaskStore, and supervision tree.
!!! tip "Want to add your SDK?"
Open an issue on [a2aproject/A2A](https://github.com/a2aproject/A2A/issues/new?title=Community%20SDK%20Submission) with a link to your repository and published package.
**Requirements:** Spec compliance, published package on standard registry, documentation, tests with CI, Apache 2.0 license, and active maintenance.
## The Future is Interoperable
The excitement surrounding Google's A2A protocol clearly indicates a strong belief in its potential to revolutionize multi-agent AI systems. By providing a standardized way for AI agents to communicate and collaborate, A2A is poised to unlock new levels of automation and innovation. As enterprises increasingly adopt AI agents, A2A represents a crucial step towards realizing the full power of interconnected AI ecosystems.

View File

@ -31,11 +31,7 @@ Originally developed by Google and now donated to the Linux Foundation, A2A prov
- :material-play-circle:{ .lg .middle } **Video** Intro in <8 min
<iframe class="video-container" src="https://www.youtube.com/embed/Fbr_Solax1w?si=QxPMEEiO5kLr5_0F" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
- :material-play-circle:{ .lg .middle } **Course** [DeepLearning.AI](https://deeplearning.ai) - Intro to A2A
[![A2A DeepLearning.AI](https://img.youtube.com/vi/4gYm0Rp7VHc/maxresdefault.jpg)](https://goo.gle/dlai-a2a)
<iframe width="560" height="315" src="https://www.youtube.com/embed/Fbr_Solax1w?si=QxPMEEiO5kLr5_0F" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
- :material-book-open:{ .lg .middle } **Read the Introduction**
@ -57,8 +53,6 @@ Originally developed by Google and now donated to the Linux Foundation, A2A prov
[:octicons-arrow-right-24: Python Tutorial](./tutorials/python/1-introduction.md)
[:octicons-arrow-right-24: Walkthrough with AI Agent Frameworks](https://github.com/holtskinner/A2AWalkthrough)
- :material-code-braces:{ .lg .middle } **Explore Code Samples**
See A2A in action with sample clients, servers, and agent framework integrations.

View File

@ -1,81 +1,200 @@
# A2A (Agent2Agent) Protocol High-Level Summary
This project defines the **Agent2Agent (A2A) protocol**, an open standard initiated by Google and donated to the Linux Foundation, designed to enable communication and interoperability between disparate AI agent systems. It allows agents built on different frameworks (e.g., LangGraph, CrewAI, Google ADK, Genkit) to discover each other's capabilities, negotiate interaction modes, and collaborate on tasks securely without exposing internal state.
This project defines and demonstrates the **Agent2Agent (A2A) protocol**, an open standard initiated by Google and donated to the Linux Foundation, designed to enable communication and interoperability between disparate AI agent systems. The core goal is to allow agents built on different frameworks (e.g., LangGraph, CrewAI, Google ADK, Genkit) or by different vendors to discover each other's capabilities, negotiate interaction modes, and collaborate on tasks securely.
The repository contains:
1. **Formal Specification:** Protobuf definitions (`specification/a2a.proto`) and JSON Schema (`specification/json/a2a.json`).
2. **Core Concepts Documentation:** Guides on discovery, task lifecycle, streaming, and enterprise-readiness (`docs/topics/`).
3. **SDKs:** Production-ready SDKs for Python, JS/TS, Java, Go, and .NET.
4. **Sample Implementations:** Real-world examples integrated with various agent frameworks.
The repository provides:
## Key Files & Directories
1. **Formal Specification:** A detailed JSON Schema (`specification/json/a2a.json`) and Protobuf definitions (`specification/a2a.proto`) that define the structure of A2A messages, including requests, responses, tasks, artifacts, and agent metadata (Agent Cards).
2. **Core Concepts Documentation:** A comprehensive set of documents in the `docs/topics/` directory covering agent discovery, task lifecycle, streaming, push notifications, and enterprise-readiness.
3. **SDKs and Sample Implementations:**
* **SDKs:** Production-ready SDKs for Python, Java, JavaScript, and C#/.NET, with more in development.
* **Example Agents:** Demonstrations of integrating A2A into various agent frameworks:
* **Python:** LangGraph (currency conversion, streaming), CrewAI (image generation, file artifacts), Google ADK (expense reports, form handling).
* **JavaScript/TypeScript:** Genkit (movie info via API, code generation with file artifacts).
* **Example Hosts:** Applications that consume A2A services, including CLIs for direct interaction and a Python-based multi-agent orchestrator.
4. **Demo Web Application:** A web UI demonstrating multi-agent interactions facilitated by the A2A protocol, including visualization of conversations, tasks, events, and agent discovery.
- `specification/a2a.proto`: The authoritative Protobuf definition of the protocol.
- `docs/topics/`: Detailed conceptual guides (Discovery, Lifecycle, Security, etc.).
- `docs/tutorials/`: Step-by-step guides for building A2A-compliant agents.
- `scripts/`: Utility scripts for building documentation and formatting.
Key features of the A2A protocol include: agent discovery via Agent Cards, standardized task management (`send`, `get`, `cancel`), support for rich content types (text, files, structured data), real-time streaming updates for long-running tasks, and mechanisms for asynchronous push notifications. The project is open-source and encourages community contribution.
# A2A (Agent2Agent) Protocol Reference
# A2A (Agent2Agent) Protocol
## 1. Overview
- **Purpose:** Open standard for agent-to-agent interoperability.
- **Communication Bindings:** Supports JSON-RPC 2.0 (HTTP/SSE), gRPC, and HTTP/REST.
- **Key Concepts:** Agent Cards for discovery, Task-based execution, Multi-turn Messages, and Artifact outputs.
- **Project Name:** Agent2Agent (A2A) Protocol
- **Purpose:** An open protocol enabling communication and interoperability between AI agents built on different frameworks or by different vendors.
- **Core Goal:** Allow agents to discover capabilities, negotiate interaction, and collaborate securely on tasks.
- **Communication:** Uses JSON-RPC 2.0 over HTTP(S). Supports standard request/response and Server-Sent Events (SSE) for streaming. Also includes a gRPC specification.
- **Key Components:** Formal Specification (JSON Schema, Protobuf), SDKs (Python, JS, Java, .NET), Sample Implementations, and Core Documentation.
## 2. Core Data Objects
## 2. Protocol Specification (`specification/json/a2a.json`)
### 2.1 AgentCard (`/.well-known/agent-card.json`)
Describes an agent's identity and capabilities.
- `name`, `description`, `version`: Identity metadata.
- `supported_interfaces`: List of `AgentInterface` (URL, protocol binding, tenant, protocol version).
- `capabilities`: `streaming`, `push_notifications`, `extended_agent_card`, `extensions`.
- `skills`: List of `AgentSkill` (id, name, description, tags, examples).
- `security_schemes`, `security_requirements`: Authentication configuration (API Key, OAuth2, OIDC, mTLS, HTTP Auth).
- `default_input_modes`, `default_output_modes`: Supported MIME types (e.g., `text/plain`, `application/json`).
### 2.1. Core JSON-RPC Structures
### 2.2 Task
Represents a stateful unit of work.
- `id`, `context_id`: Identifiers for the task and its conversational context.
- `status`: `TaskStatus` (state, message, timestamp).
- `artifacts`: List of `Artifact` (outputs produced).
- `history`: List of `Message` (conversation history).
- `metadata`: Custom structured data.
- **`JSONRPCMessage`:** Base for requests/responses. Contains `jsonrpc: "2.0"` and optional `id`.
- **`JSONRPCRequest`:** Represents a request with `method`, `params`, and `id`.
- **`JSONRPCResponse`:** Represents a response with either `result` or `error`, and a matching `id`.
- **`JSONRPCError`:** Represents an error with `code`, `message`, and optional `data`.
### 2.3 TaskState (Enum)
- `SUBMITTED`, `WORKING`, `COMPLETED` (terminal), `FAILED` (terminal), `CANCELED` (terminal), `REJECTED` (terminal), `INPUT_REQUIRED` (interrupted), `AUTH_REQUIRED` (interrupted).
### 2.2. Key A2A Data Objects
### 2.4 Message & Part
- `Message`: Contains `message_id`, `role` (USER/AGENT), `parts`, `context_id`, `task_id`, `reference_task_ids`.
- `Part`: Union type containing `text`, `raw` (bytes), `url`, or `data` (JSON). Includes `media_type` and `filename`.
- **`AgentCard`:** Metadata describing an agent, typically found at `/.well-known/agent-card.json`.
- `protocolVersions`: (string[]) The versions of the A2A protocol supported by the agent.
- `name`, `description`, `version`: (string) Agent's identity.
- `url`: (string) The preferred endpoint URL for the agent's A2A service.
- `provider`: (`AgentProvider`) Organization details.
- `capabilities`: (`AgentCapabilities`) Features supported (streaming, push notifications, state transition history, extended agent card, extensions).
- `securitySchemes`, `security`: (object, array) Authentication and authorization requirements, following OpenAPI specifications.
- `defaultInputModes`, `defaultOutputModes`: (string[]) Default supported MIME types.
- `skills`: (`AgentSkill[]`) List of specific capabilities.
- `signatures`: (`AgentCardSignature[]`) JWS signatures for verifying the card's integrity.
- **`AgentSkill`:** A specific capability of an agent, with `id`, `name`, `description`, `tags`, and `examples`.
- **`Task`:** Represents a stateful unit of work.
- `id`, `contextId`: (string) Unique identifiers for the task and its conversational context.
- `status`: (`TaskStatus`) Current state information.
- `artifacts`: (`Artifact[]`) Outputs produced by the agent.
- `history`: (`Message[]`) The conversation history associated with the task (if enabled by `stateTransitionHistory` capability).
- `metadata`: (object) Custom key-value data.
- `kind`: ("task") Type discriminator.
- **`TaskStatus`:**
- `state`: (`TaskState`) Current lifecycle state (e.g., "working", "completed").
- `message`: (`Message`) An optional, human-readable message from the agent providing status details.
- `timestamp`: (string) ISO-8601 timestamp.
- **`TaskState`:** (enum) `submitted`, `working`, `input-required`, `completed`, `failed`, `canceled`, `rejected`, `auth-required`, `unknown`.
- **`Message`:** A single unit of communication.
- `role`: ("user" | "agent") Sender's role.
- `parts`: (`Part[]`) The content of the message.
- `messageId`, `taskId`, `contextId`: (string) Identifiers linking the message.
- `referenceTaskIds`: (string[]) List of prior tasks for context.
- **`Part` (Union Type):** A segment of content within a `Message` or `Artifact`.
- **`TextPart`:** Plain text content.
- **`FilePart`:** A file, referenced by URI or with inline base64-encoded bytes.
- **`DataPart`:** Structured JSON data.
- **`Artifact`:** A tangible output generated by a task, composed of one or more `Part`s.
- **`PushNotificationConfig`:** Configuration for receiving asynchronous updates via a webhook URL.
- **`GetExtendedAgentCard`:** An RPC method to retrieve a more detailed `AgentCard` after authentication.
### 2.5 Artifact
- A tangible output from a task, containing one or more `Part`s and metadata.
### 2.3. A2A RPC Methods
## 3. RPC Methods
- **`SendMessage`:** (Request/Response)
- Sends a message to initiate or continue a task.
- `params`: `SendMessageRequest` (includes `taskId`, `contextId`, `message`, optionally `configuration`).
- `result`: `Task` (final state after synchronous processing).
- **`SendStreamingMessage`:** (Request/Stream)
- Sends a message and subscribes to real-time updates via Server-Sent Events (SSE).
- `params`: `SendMessageRequest`.
- `result` (stream events): `StreamResponse` containing one of: `Message`, `Task`, `TaskStatusUpdateEvent`, `TaskArtifactUpdateEvent`.
- **`GetTask`:** (Request/Response)
- Retrieves the current state of a task.
- `params`: `GetTaskRequest` (includes `id`, optionally `historyLength`).
- `result`: `Task`.
- **`ListTasks`:** (Request/Response)
- Retrieves a list of tasks with optional filtering and pagination.
- `params`: `ListTasksRequest` (optional: `contextId`, `status`, `pageSize`, `pageToken`, `historyLength`, `statusTimestampAfter`, `includeArtifacts`).
- `result`: `ListTasksResponse` (includes `tasks[]`, `totalSize`, `pageSize`, `nextPageToken`).
- **`CancelTask`:** (Request/Response)
- Requests cancellation of a running task.
- `params`: `CancelTaskRequest` (includes `id`).
- `result`: `Task` (updated state, likely 'canceled') or error if not cancelable.
- **`CreateTaskPushNotificationConfig`:** (Request/Response)
- Creates a push notification configuration for a task.
- `params`: `CreateTaskPushNotificationConfigRequest`.
- `result`: `TaskPushNotificationConfig` (confirmed configuration).
- **`GetTaskPushNotificationConfig`:** (Request/Response)
- Retrieves the current push notification configuration for a task.
- `params`: `GetTaskPushNotificationConfigRequest` (includes `taskId`).
- `result`: `TaskPushNotificationConfig`.
- **`SubscribeToTask`:** (Request/Stream)
- Subscribes to task updates.
- `params`: `SubscribeToTaskRequest`.
- `result` (stream events): `StreamResponse`.
| Method | Request | Response | Description |
| :--- | :--- | :--- | :--- |
| `SendMessage` | `SendMessageRequest` | `SendMessageResponse` | Initiates or continues a task. |
| `SendStreamingMessage` | `SendMessageRequest` | `stream StreamResponse` | Sends message and receives real-time SSE updates. |
| `GetTask` | `GetTaskRequest` | `Task` | Retrieves current task state. |
| `ListTasks` | `ListTasksRequest` | `ListTasksResponse` | Filter and paginate tasks. |
| `CancelTask` | `CancelTaskRequest` | `Task` | Requests cancellation of a task. |
| `SubscribeToTask` | `SubscribeToTaskRequest` | `stream StreamResponse` | Subscribes to updates for an existing task. |
| `GetExtendedAgentCard` | `GetExtendedAgentCardRequest` | `AgentCard` | Fetches detailed metadata after authentication. |
### 2.4. Streaming Update Events (Result of `SendStreamingMessage` or `SubscribeToTask`)
### 3.1 Streaming Events (`StreamResponse`)
Streams return a payload containing one of:
- `task`: Full task state.
- `message`: A discrete message part.
- `status_update`: `TaskStatusUpdateEvent` (taskId, contextId, status).
- `artifact_update`: `TaskArtifactUpdateEvent` (taskId, artifact, append, last_chunk).
- **`StreamResponse`:** Wrapper object for streaming responses.
- `payload`: One of `task`, `message`, `status_update`, `artifact_update`.
- **`TaskStatusUpdateEvent`:** Signals a change in task status.
- `taskId`: (string) Task ID.
- `contextId`: (string) Context identifier the task is associated with.
- `status`: (`TaskStatus`) The new status object.
- **`TaskArtifactUpdateEvent`:** Signals a new or updated artifact.
- `taskId`: (string) Task ID.
- `artifact`: (`Artifact`) The artifact data.
- `append`: (boolean) If true, append parts to artifact; if false (default), replace.
- `lastChunk`: (boolean) If true, indicates this is the final update for the artifact.
## 4. Security & Authentication
- **Transport:** HTTPS/TLS required for production.
- **Authentication:** Declared in `AgentCard` via OpenAPI-style security schemes.
- **Push Notifications:** Webhooks secured via authentication tokens/schemes configured per task.
### 2.5. Standard Error Codes
## 5. Implementation Status
- **Official SDKs:** Python (`a2a-sdk`), JS/TS (`@a2a-js/sdk`), Java, Go, C#/.NET.
- **Integrations:** LangGraph, CrewAI, Google ADK, Genkit, AG2, BeeAI, PydanticAI, and more.
- `-32700`: `JSONParseError`
- `-32600`: `InvalidRequestError`
- `-32601`: `MethodNotFoundError`
- `-32602`: `InvalidParamsError`
- `-32603`: `InternalError`
### 2.6. A2A Specific Error Codes
- `-32001`: `TaskNotFoundError`
- `-32002`: `TaskNotCancelableError`
- `-32003`: `PushNotificationNotSupportedError`
- `-32004`: `UnsupportedOperationError`
- `-32005`: `ContentTypeNotSupportedError`
- `-32006`: `InvalidAgentResponseError`
- `-32007`: `AuthenticatedExtendedCardNotConfiguredError`
## 3. Core Concepts
- **Agent Discovery:** Clients find agents by fetching their `AgentCard` JSON, typically from a `/.well-known/agent-card.json` URI or a curated registry.
- **Task Lifecycle:** Tasks progress through defined states (`submitted` -> `working` -> `completed`/`failed`, etc.), enabling tracking of long-running operations.
- **Communication:** Interactions use `Message` objects containing `Part`s (text, file, data). Task outputs are delivered as `Artifact`s.
- **Streaming:** Long-running tasks provide real-time updates via SSE using the `message/stream` method. Updates can be `Task`, `Message`, `TaskStatusUpdateEvent`, or `TaskArtifactUpdateEvent` objects.
- **Push Notifications:** For disconnected clients, agents can send updates to a webhook URL configured via `CreateTaskPushNotificationConfig`.
- **Authentication:** A2A leverages standard web security (e.g., OAuth, API keys), declared in the `AgentCard`. Credentials are sent via HTTP headers, not in the A2A payload.
## 4. Security Considerations
- **Transport Security:** Production environments MUST use HTTPS with modern TLS.
- **Authentication:** Servers MUST authenticate every request based on schemes declared in the `AgentCard`.
- **Authorization:** Authorization logic is implementation-specific and MUST enforce the principle of least privilege, potentially on a per-skill basis.
- **Push Notification Security:** Both the server (validating webhook URLs to prevent SSRF) and the client (verifying incoming notifications) have critical security responsibilities.
- **Input Validation:** Servers MUST rigorously validate all RPC parameters and message content.
## 5. Implementations & Samples
### 5.1. SDKs
- **Python:** `a2a-sdk` on PyPI.
- **JavaScript/TypeScript:** `@a2a-js/sdk` on npm.
- **Java:** `a2a-java` on Maven.
- **C#/.NET:** `A2A` on NuGet.
### 5.2. Python Samples
- **Location:** `a2a-samples/samples/python/`
- **Agents:**
- **LangGraph:** Currency conversion agent demonstrating tool use, multi-turn conversation (`input-required`), and streaming via `message/stream`.
- **CrewAI:** Image generation agent demonstrating file artifact handling.
- **Google ADK:** Expense report agent demonstrating structured data/forms.
- **Hosts:**
- **CLI:** Command-line client for interacting with any A2A agent.
- **Multi-Agent Orchestrator:** An ADK-based agent that delegates tasks to other A2A agents.
### 5.3. JavaScript/TypeScript Samples
- **Location:** `a2a-samples/samples/js/`
- **Framework:** Genkit
- **Agents:**
- **Movie Agent:** Uses an external API to answer questions.
- **Coder Agent:** Generates code and demonstrates file artifact creation.
### 5.4. Demo Application
- **Location:** `a2a-samples/demo/`
- A web application built with Mesop that visualizes multi-agent conversations orchestrated by a host agent, rendering text, images, and forms.
## 6. Development & Setup
- **Prerequisites:** Python (>=3.10), Node.js (>=18).
- **API Keys:** LLM access requires API keys (e.g., `GOOGLE_API_KEY`), typically set via `.env` files.
- **Running Samples:** Involves starting an agent server and then running a host/client application to interact with it.
## 7. Contribution
- See `CONTRIBUTING.md` for guidelines.
- Join discussions on the [A2A GitHub Discussions page](https://github.com/a2aproject/A2A/discussions).
- Report issues or suggest improvements via [GitHub Issues](https://github.com/a2aproject/A2A/issues).
- Provide private feedback via this [Google Form](https://goo.gle/a2a-feedback).

View File

@ -11,7 +11,6 @@ collaborate effectively with each other and with users.
- [Activeloop](https://www.activeloop.ai/)
- [Adobe](https://www.adobe.com)
- [AG2AI](https://ag2.ai)
- [AgentTrust](https://agenttrust.ai/)
- [AI21 Labs](https://www.ai21.com/)
- [AI71](https://ai71.ai/)
- [Aisera](https://aisera.com/)
@ -82,7 +81,6 @@ collaborate effectively with each other and with users.
- [InfoSys](https://www.infosys.com)
- [Intuit](https://www.intuit.com)
- [Iron Mountain](https://www.ironmountain.com/)
- [JamJet](https://github.com/jamjet-labs/jamjet)
- [JetBrains](https://www.jetbrains.com)
- [JFrog](https://jfrog.com)
- [Kakao](https://www.kakaocorp.com)
@ -109,7 +107,6 @@ collaborate effectively with each other and with users.
- [Nisum](http://www.nisum.com)
- [Noorle Inc](http://www.noorle.com)
- [NTT DATA](https://www.nttdata.com)
- [OIXA Protocol](https://oixa.io)
- [Optimizely Inc](https://www.optimizely.com/)
- [Oracle / NetSuite](https://www.oracle.com/netsuite)
- [Palo Alto Networks](https://www.paloaltonetworks.com/)
@ -118,7 +115,6 @@ collaborate effectively with each other and with users.
- [Pendo](https://www.pendo.io)
- [PerfAI.ai](https://perfai.ai)
- [Personal AI](https://personal.ai)
- [Pinchwork](https://pinchwork.dev)
- [Poppulo](https://www.poppulo.com/blog/poppulo-google-a2a-the-future-of-workplace-communication)
- [Productive Edge](https://www.productiveedge.com/)
- [Proofs](https://proofs.io)
@ -140,7 +136,6 @@ collaborate effectively with each other and with users.
- [Solace](https://solace.com/products/agent-mesh/)
- [Solo.io](https://www.solo.io/)
- [Stacklok, Inc](https://stacklok.com)
- [Strale](https://strale.dev)
- [Supertab](https://www.supertab.co/post/supertab-connect-partners-with-google-cloud-to-enable-ai-agents)
- [Suzega](https://suzega.com/)
- [TCS](https://www.tcs.com)
@ -164,7 +159,6 @@ collaborate effectively with each other and with users.
- [Weights & Biases](https://wandb.ai/wandb_fc/product-announcements-fc/reports/Powering-Agent-Collaboration-Weights-Biases-Partners-with-Google-Cloud-on-Agent2Agent-Interoperability-Protocol---VmlldzoxMjE3NDg3OA)
- [Wipro](https://www.wipro.com)
- [Workday](https://www.workday.com)
- [WritBase](https://github.com/Writbase/writbase)
- [Writer](https://writer.com)
- [Zenity](https://zenity.io)
- [Zeotap](https://www.zeotap.com)

View File

@ -1,13 +1,15 @@
# A2A protocol roadmap
**Last updated:** March 10, 2026
**Last updated:** Jul 16, 2025
## Near-term initiatives
- Release `1.0` version of the protocol which represents significant maturation of the protocol with enhanced clarity, stronger specifications, and important structural improvements.
- [What's New in A2A Protocol v1.0](https://a2a-protocol.org/latest/whats-new-v1/) has further updates.
- Continue to support additional [A2A extensions](topics/extensions.md) with SDK support.
- Prioritize community-led development with standardized processes for contributing to the specification, SDKs and tooling.
- Release `0.3` version of the protocol which we intend to keep supported and without breaking changes for a significant amount of time with backward compatibility of the SDKs starting at version `0.3`. As part of this release there are a few known breaking changes including:
- Update the `/.well-known/agent.json` path for hosting Agent Cards to `/.well-known/agent-card.json` based on feedback from IANA.
- Refactor class fields to be more Pythonic and adopt `snake_case`. [PR 199](https://github.com/a2aproject/a2a-python/pull/199)
- Solidify the support for [A2A extensions](topics/extensions.md) with SDK support (starting with the Python SDK) and publishing sample extensions.
- Introduce support for signed Agent Cards [Discussion 199](https://github.com/a2aproject/A2A/discussions/199#discussioncomment-13770576) to allow verifying the integrity of Agent Card content.
- Enhance the client side support in SDK (starting with Python) to expose ready-to-use A2A clients, streamlined auth handling and improved handling of tasks.
To review recent protocol changes see [Release Notes](https://github.com/a2aproject/A2A/releases).
@ -15,12 +17,15 @@ To review recent protocol changes see [Release Notes](https://github.com/a2aproj
### Governance
The TSC looks to streamline opportunities for contribution through [A2A extensions](topics/extensions.md), [Samples](https://github.com/a2aproject/a2a-samples) and participation.
The protocol has been [donated](https://www.linuxfoundation.org/press/linux-foundation-launches-the-agent2agent-protocol-project-to-enable-secure-intelligent-communication-between-ai-agents) to the Linux Foundation. The TSC is working on implementing a governance structure that prioritizes community-led development with standardized processes for contributing to the specification, SDKs and tooling. As part of the effort there will be dedicated working groups created for specific areas of the protocol.
### Agent Registry
Agent Registry enables the discovery of agents and is a critical component of a multi-agent system. There is an active and ongoing discussion in the community around the latest [Discussion 741](https://github.com/a2aproject/A2A/discussions/741).
### Validation
As the A2A ecosystem matures, it becomes critical for the A2A community to have tools to validate their agents. The community has launched two efforts to help with validation. Learn more about [A2A Inspector](https://github.com/a2aproject/a2a-inspector) and the [A2A Protocol Technology Compatibility Kit](https://github.com/a2aproject/a2a-tck) (TCK).
As the A2A ecosystem matures, it becomes critical for the A2A community to have tools to validate their agents. The community has launched two efforts to help with validation which the group will continue to enhance in the coming months. Learn more about [A2A Inspector](https://github.com/a2aproject/a2a-inspector) and the [A2A Protocol Technology Compatibility Kit](https://github.com/a2aproject/a2a-tck) (TCK).
### SDKs

View File

@ -1,14 +1,15 @@
# A2A SDK
The following table lists the supported languages for official A2A SDKs and their repositories.
A2A currently hosts SDKs in five languages (Python, Go, JS, Java, .NET).
| Language | Repository |
|------------|----------------------------------------------------------|
| Python | [`a2a-python`](https://github.com/a2aproject/a2a-python) |
| Go | [`a2a-go`](https://github.com/a2aproject/a2a-go) |
| Java | [`a2a-java`](https://github.com/a2aproject/a2a-java) |
| JavaScript | [`a2a-js`](https://github.com/a2aproject/a2a-js) |
| C#/.NET | [`a2a-dotnet`](https://github.com/a2aproject/a2a-dotnet) |
| Rust | [`a2a-rs`](https://github.com/a2aproject/a2a-rs) |
The following table lists the supported languages and their stability.
| Language | Support |
| :--------- | :------- |
| Python | [Stable](https://github.com/a2aproject/a2a-python) |
| Go | [Stable](https://github.com/a2aproject/a2a-go) |
| Java | [Stable](https://github.com/a2aproject/a2a-java) |
| JavaScript | [Stable](https://github.com/a2aproject/a2a-js) |
| C#/.NET | [Stable](https://github.com/a2aproject/a2a-dotnet) |
The A2A project provides numerous samples across supported languages in the [a2a-samples repository](https://github.com/a2aproject/a2a-samples).

File diff suppressed because it is too large Load Diff

View File

@ -91,10 +91,3 @@ figure.hero figcaption {
margin-bottom: 0;
text-align: left;
}
iframe.video-container {
width: 100%;
aspect-ratio: 16 / 9;
height: auto;
border-radius: 4px;
}

View File

@ -91,22 +91,6 @@ To mitigate risks, the following protection mechanisms should be considered:
Any Agent Card containing sensitive data must be protected with authentication and authorization mechanisms. The A2A specification strongly recommends the use of out-of-band dynamic credentials rather than embedding static secrets within the Agent Card.
## Caching Considerations
Agent Cards describe an agent's capabilities and typically change infrequently — for example, when skills are added or authentication requirements are updated. Applying standard HTTP caching practices to Agent Card endpoints reduces unnecessary network requests while ensuring clients eventually receive updated information.
### Server Guidance
Servers hosting Agent Card endpoints should include HTTP caching headers in their responses. The `Cache-Control` header with an appropriate `max-age` directive allows clients and intermediaries to cache the card for a specified duration. Including an `ETag` header — derived from the card's `version` field or a content hash — enables clients to make conditional requests and avoid re-downloading unchanged cards.
### Client Guidance
Clients fetching Agent Cards should honor standard HTTP caching semantics. When a cached card expires, clients should use conditional requests (for example, `If-None-Match` with the stored `ETag` or `If-Modified-Since`) rather than unconditionally re-fetching the full card. When the server does not provide caching headers, clients may apply a reasonable default cache duration.
For Extended Agent Cards, clients should also follow the session-scoped caching guidance described in the [specification](../specification.md#133-extended-agent-card-access-control).
For normative requirements, see [Section 8.6](../specification.md#86-caching) of the specification.
## Future Considerations
The A2A community explores standardizing registry interactions or advanced discovery protocols.

View File

@ -1,135 +0,0 @@
# Custom Protocol Bindings
The A2A protocol ships with three standard bindings (JSON-RPC, gRPC, and
HTTP+JSON/REST) that cover the majority of deployment scenarios. Custom protocol
bindings let implementers expose A2A operations over additional transport
mechanisms not covered by the standard set.
Custom protocol bindings are a complementary but distinct concept to
[Extensions](extensions.md). Extensions modify the *behavior* of protocol
interactions by adding new data, methods, or state transitions on top of an
existing transport. Custom protocol bindings change the *transport layer*
itself—for example, exposing A2A over WebSockets for low-latency bidirectional
communication, or over MQTT for IoT environments with constrained connectivity.
## Declaration in the Agent Card
Custom protocol bindings are declared in the Agent Card's `supportedInterfaces`
list. Each entry identifies the transport by URI, the endpoint URL, and the A2A
protocol version it implements. The `protocolBinding` field should be a URI that uniquely identifies the
binding (see [Section 5.8 of the specification](../specification.md#58-custom-binding-identification)
for the normative requirement and versioning guidance).
```json
{
"supportedInterfaces": [
{
"url": "wss://agent.example.com/a2a/websocket",
"protocolBinding": "https://a2a-protocol.org/bindings/websocket",
"protocolVersion": "1.0"
}
]
}
```
Agents that support multiple bindings list all of them. Clients parse
`supportedInterfaces` in order and select the first transport they support, so
entries should be listed in preference order.
## Requirements
Custom protocol bindings must comply with all requirements in the
[Protocol Binding Requirements and Interoperability](../specification.md#5-protocol-binding-requirements-and-interoperability)
section of the specification. In particular:
- **All core operations must be supported.** The binding must expose every
operation defined in the abstract operations layer (send message, get task,
cancel task, streaming, push notifications, etc.).
- **The data model must be preserved.** All data structures must be
functionally equivalent to the canonical Protocol Buffer definitions. JSON
serializations must use camelCase field names, and timestamps must be
ISO 8601 strings in UTC.
- **Behavior must be consistent.** Semantically equivalent requests must
produce semantically equivalent results regardless of which binding is used.
## Key Areas to Specify
A custom binding specification must address each of the following areas.
### Data Type Mappings
Document how each Protocol Buffer type is represented in the custom transport,
including:
- Binary data encoding (e.g., base64 for text-based transports)
- Enum representation (strings, integers, or named constants)
- Timestamp format (ISO 8601 strings in UTC per the core convention)
### Service Parameters
Service parameters are key-value pairs used to carry horizontally applicable
context such as tracing identifiers or authentication hints. The binding
specification must state:
- The mechanism used to carry service parameters (e.g., custom message headers,
a top-level metadata field)
- Any character encoding or size constraints on keys and values
- Any names reserved by the binding itself
For transports that lack native header support, a common pattern is to embed
service parameters as a JSON object in a dedicated metadata field, for example
`a2a-service-parameters`.
### Error Mapping
The binding must map all A2A error types to transport-native error
representations while preserving their semantic meaning. Provide a mapping
table equivalent to the one in the specification's
[Error Code Mappings](../specification.md#54-error-code-mappings) section, showing
how each A2A error type (e.g., `TaskNotFoundError`, `UnsupportedOperationError`) is expressed in the custom binding's native error format.
### Streaming
If the transport supports streaming, document:
- The stream mechanism (e.g., WebSocket frames, chunked encoding, long polling)
- Ordering guarantees (events must be delivered in the order they were
generated)
- Reconnection behavior when a connection is interrupted
- How stream completion or termination is signaled to the client
If the transport does not support streaming, state this limitation clearly in
the Agent Card so clients can fall back to polling.
### Authentication and Authorization
Document how authentication credentials declared in the Agent Card are
transmitted using the custom transport. Define how authentication challenges are
communicated to clients and ensure the custom binding does not inadvertently
bypass the agent's primary security controls.
## Interoperability Testing
Before publishing a custom binding, verify that:
- All operations behave identically to the standard bindings for the same
logical requests
- Error conditions, large payloads, and long-running tasks are handled correctly
- Any intentional deviations from standard binding behavior are clearly
documented
- Sample requests and responses are included in the specification to help
implementers
## Governance
The A2A organization uses a formal governance framework for how custom protocol
bindings are proposed, developed, promoted, and maintained. Official bindings
use the `https://a2a-protocol.org/bindings/` URI prefix and are hosted under
the `a2aproject` organization with the `cpb-` repository prefix (experimental
bindings use `experimental-cpb-`). A2A SDKs SHOULD implement official custom
protocol bindings.
For the full governance process—including tiers, lifecycle, SDK support, and
legal requirements—see the
[Extension and Protocol Binding Governance](extension-and-binding-governance.md)
page.

View File

@ -1,189 +0,0 @@
# Extension and Protocol Binding Governance
The A2A organization uses a unified governance framework for both
[Extensions](extensions.md) and [Custom Protocol Bindings](custom-protocol-bindings.md).
This document defines the formal process for proposing, developing, promoting,
and maintaining these artifacts within the A2A organization.
Anyone may develop and publish extensions or custom protocol bindings
independently. The tiers and lifecycle described here apply specifically to
those hosted under the `a2aproject` GitHub organization.
## Tiers
Both extensions and custom protocol bindings use a two-tier system within the
`a2aproject` organization. Repository naming and URI prefixes differ by type:
| | Extensions | Custom Protocol Bindings |
| :----------------------- | :---------------------------------------------- | :--------------------------------------------- |
| Official repo prefix | `ext-{name}` | `cpb-{name}` |
| Experimental repo prefix | `experimental-ext-{name}` | `experimental-cpb-{name}` |
| Official URI prefix | `https://a2a-protocol.org/extensions/` | `https://a2a-protocol.org/bindings/` |
### Official
Official artifacts are developed and maintained under the `a2aproject` GitHub
organization, officially recommended by the TSC. Each repository has designated
maintainers identified in `MAINTAINERS.md`.
**Requirements:**
- Specifications MUST use the same language as the core specification
([RFC 2119](https://tools.ietf.org/html/rfc2119))
- MUST be licensed under Apache 2.0
- MUST have at least one reference implementation
- SHOULD have associated documentation on the A2A website
### Experimental
Experimental artifacts provide an incubation pathway for community contributors
to prototype and collaborate on ideas before graduation to official status.
**Creation Requirements:**
- An experimental repository can ONLY be created with sponsorship from an A2A
Maintainer
- The sponsoring Maintainer is responsible for initial oversight of the
experimental artifact
- Experimental repositories MUST clearly indicate their experimental/non-official
status in the README
- Any published packages MUST use naming that clearly indicates experimental
status
- The TSC retains oversight, including the ability to archive or remove
experimental repositories
## Lifecycle
Extensions and custom protocol bindings progress through the following phases.
### Proposal Phase
Any community member may propose an extension or custom protocol binding:
1. **Open an Issue**: Create an issue in the main `a2aproject/A2A` repository
describing:
- An abstract describing the extension's purpose or the binding's transport
and use case
- Motivation explaining why this cannot be achieved with the core protocol
or existing standard bindings
- An initial technical approach or specification draft
2. **Community Discussion**: The proposal is open for community feedback and
refinement
### Maintainer Sponsorship
For a proposal to proceed to experimental status:
1. **Secure a Sponsor**: An A2A Maintainer must agree to sponsor the proposal
2. **Repository Creation**: The sponsoring Maintainer creates the
`experimental-ext-*` or `experimental-cpb-*` repository under `a2aproject`
3. **Oversight**: The sponsoring Maintainer provides initial oversight and
ensures alignment with A2A design principles
### Experimental Development
While in experimental status:
- Contributors iterate on the specification and reference implementations
- The experimental artifact MAY be used by early adopters with the
understanding that breaking changes are expected
- Community feedback is gathered and incorporated
- The experimental repository MUST clearly indicate its non-official status
### Graduation to Official Status
To graduate an experimental extension or binding to official status:
1. **Maturity Requirements**:
- At least one production-quality reference implementation
- Documentation meeting A2A standards
- Evidence of community adoption or interest
- Clear maintainer commitment for ongoing maintenance
2. **Graduation Proposal**: Open an issue in `a2aproject/A2A` with:
- Reference to the experimental repository and its implementations
- Summary of community feedback and adoption
- Proposed maintainers for the official artifact
3. **TSC Vote**:
- The proposal is added to the TSC meeting agenda
- **Quorum Requirement**: At least 50% of TSC voting members must be
present
- **Approval**: Requires majority vote of those in attendance (per A2A
governance)
- The TSC may request revisions before a final vote
4. **Acceptance**:
- (Extensions) The repository is renamed from `experimental-ext-*` to
`ext-*`; documentation is added to the A2A website's extensions page
- (Custom Protocol Bindings) The repository is renamed from
`experimental-cpb-*` to `cpb-*`; documentation is added to the A2A
website's custom protocol bindings page
### Official Iteration
Once official, extensions and bindings may be iterated on:
- Repository maintainers are responsible for day-to-day governance
- Changes SHOULD be coordinated via the relevant working group if one exists
- Breaking changes require a new identifier
- Breaking changes require TSC review
- Maintainers SHOULD coordinate with SDK maintainers for implementation updates
### Promotion to Core Protocol
Some extensions may eventually transition to core protocol features, and some
custom protocol bindings may transition to core bindings. This is governed
through the existing A2A specification enhancement process:
- A proposal is submitted following the standard specification change process
- The proposal references the official extension or binding and its adoption
- TSC vote with standard quorum and majority requirements applies
- Not all extensions or bindings are suitable for core inclusion; many will
remain as extensions or custom bindings indefinitely
## SDK Support
SDK support requirements differ between extensions and official custom protocol
bindings, reflecting their different roles in the protocol ecosystem.
**Extensions**: A2A SDKs MAY implement extensions. Where implemented:
- Extensions MUST be disabled by default and require explicit opt-in
- SDK documentation SHOULD list supported extensions
- SDK maintainers have full autonomy over extension support decisions
- Extension support is not required for protocol conformance
**Official Custom Protocol Bindings**: A2A SDKs SHOULD implement official
custom protocol bindings. Where implemented:
- Custom protocol bindings MUST be disabled by default and require explicit
opt-in
- SDK documentation SHOULD list supported custom protocol bindings
- SDK maintainers have full autonomy over binding support decisions
- Custom protocol binding support is not required for protocol conformance
## Legal Requirements
### Licensing
Official extensions and custom protocol bindings MUST be available under the
Apache 2.0 license, consistent with the core A2A project.
### Contributor License Grant
By submitting a contribution to an official A2A extension or custom protocol
binding repository, contributors represent that:
1. They have the legal authority to grant the rights
2. The contribution is original work or they have sufficient rights to submit it
3. They grant to the Linux Foundation and recipients a perpetual, worldwide,
non-exclusive, royalty-free license to use, reproduce, modify, and
distribute the contribution
### Antitrust
Extension and custom protocol binding developers acknowledge that:
- They may compete with other participants
- They have no obligation to implement any extension or binding
- They are free to develop competing extensions or bindings
- Status as an official extension or binding does not create an exclusive
relationship

View File

@ -51,19 +51,6 @@ However, some foreseeable applications include:
| [Traceability Extension](https://github.com/a2aproject/a2a-samples/tree/main/samples/python/extensions/traceability) | Explore the Python implementation and basic usage of the Traceability Extension (v1). |
| [Agent Gateway Protocol (AGP) Extension](https://github.com/a2aproject/a2a-samples/tree/main/extensions/agp) | A Core Protocol Layer or Routing Extension that introduces Autonomous Squads (ASq) and routes Intent payloads based on declared Capabilities, enhancing scalability (v1). |
## Extension Governance
The A2A organization uses a formal governance framework for how extensions are
proposed, developed, promoted, and maintained. Official extensions use the
`https://a2a-protocol.org/extensions/` URI prefix and are hosted under the
`a2aproject` organization with the `ext-` repository prefix (experimental
extensions use `experimental-ext-`).
For the full governance process—including tiers, lifecycle, SDK support, and
legal requirements—see the
[Extension and Protocol Binding Governance](extension-and-binding-governance.md)
page.
## Limitations
There are some changes to the protocol that extensions don't allow, primarily
@ -81,7 +68,9 @@ to prevent breaking core type validations:
Agents declare their support for extensions in their Agent Card by including
`AgentExtension` objects within their `AgentCapabilities` object.
{{ proto_to_table("AgentExtension") }}
```ts { .no-copy }
--8<-- "types/src/types.ts:AgentExtension"
```
The following is an example of an Agent Card with an extension:
@ -239,10 +228,9 @@ versioning, and distributing extension implementations.
- **Permanent Identifiers**: Authors are encouraged to use a permanent
identifier service, such as `w3id.org`, for their extension URIs to
prevent broken links.
- **Community Registry**: The A2A [Extension Governance](#extension-governance)
framework defines a tiered system for official and experimental
extensions hosted under the `a2aproject` organization, including a
lifecycle for proposing and promoting extensions.
- **Community Registry (Future)**: The A2A community might establish a
central registry for discovering and browsing available extensions in
the future.
- **Packaging and Reusability (A2A SDKs and Libraries)**:
To promote adoption, extension logic should be packaged into reusable
libraries that can be integrated into existing A2A client and

View File

@ -28,7 +28,7 @@ The following table describes the fundamental communication elements in A2A:
| Agent Card | A JSON metadata document describing an agent's identity, capabilities, endpoint, skills, and authentication requirements. | Enables clients to discover agents and understand how to interact with them securely and effectively. |
| Task | A stateful unit of work initiated by an agent, with a unique ID and defined lifecycle. | Facilitates tracking of long-running operations and enables multi-turn interactions and collaboration. |
| Message | A single turn of communication between a client and an agent, containing content and a role ("user" or "agent"). | Conveys instructions, context, questions, answers, or status updates that are not necessarily formal artifacts. |
| Part | The fundamental content container used within Messages and Artifacts. A Part holds one of: text content, a file reference (URL or inline bytes), or structured data. | Provides flexibility for agents to exchange various content types within messages and artifacts. |
| Part | The fundamental content container (for example, TextPart, FilePart, DataPart) used within Messages and Artifacts. | Provides flexibility for agents to exchange various content types within messages and artifacts. |
| Artifact | A tangible output generated by an agent during a task (for example, a document, image, or structured data). | Delivers the concrete results of an agent's work, ensuring structured and retrievable outputs. |
## Interaction Mechanisms

View File

@ -141,7 +141,7 @@ The following example illustrates a typical task flow with a follow-up:
{
"jsonrpc": "2.0",
"id": "req-001",
"method": "SendMessage",
"method": "message.send",
"params": {
"message": {
"role": "user",
@ -163,27 +163,25 @@ The following example illustrates a typical task flow with a follow-up:
"jsonrpc": "2.0",
"id": "req-001",
"result": {
"task": {
"id": "task-boat-gen-123",
"contextId": "ctx-conversation-abc",
"status": {
"state": "TASK_STATE_COMPLETED"
},
"artifacts": [
{
"artifactId": "artifact-boat-v1-xyz",
"name": "sailboat_image.png",
"description": "A generated image of a sailboat on the ocean.",
"parts": [
{
"filename": "sailboat_image.png",
"mediaType": "image/png",
"raw": "base64_encoded_png_data_of_a_sailboat"
}
]
}
]
}
"id": "task-boat-gen-123",
"contextId": "ctx-conversation-abc",
"status": {
"state": "TASK_STATE_COMPLETED"
},
"artifacts": [
{
"artifactId": "artifact-boat-v1-xyz",
"name": "sailboat_image.png",
"description": "A generated image of a sailboat on the ocean.",
"parts": [
{
"filename": "sailboat_image.png",
"mediaType": "image/png",
"raw": "base64_encoded_png_data_of_a_sailboat"
}
]
}
]
}
}
```
@ -223,27 +221,25 @@ The following example illustrates a typical task flow with a follow-up:
"jsonrpc": "2.0",
"id": "req-002",
"result": {
"task": {
"id": "task-boat-color-456",
"contextId": "ctx-conversation-abc",
"status": {
"state": "TASK_STATE_COMPLETED"
},
"artifacts": [
{
"artifactId": "artifact-boat-v2-red-pqr",
"name": "sailboat_image.png",
"description": "A generated image of a red sailboat on the ocean.",
"parts": [
{
"filename": "sailboat_image.png",
"mediaType": "image/png",
"raw": "base64_encoded_png_data_of_a_RED_sailboat"
}
]
}
]
}
"id": "task-boat-color-456",
"contextId": "ctx-conversation-abc",
"status": {
"state": "TASK_STATE_COMPLETED"
},
"artifacts": [
{
"artifactId": "artifact-boat-v2-red-pqr",
"name": "sailboat_image.png",
"description": "A generated image of a red sailboat on the ocean.",
"parts": [
{
"filename": "sailboat_image.png",
"mediaType": "image/png",
"raw": "base64_encoded_png_data_of_a_RED_sailboat"
}
]
}
]
}
}
```

View File

@ -1,4 +1,4 @@
# 2. Set Up Your Environment
# 2. Setup Your Environment
## Prerequisites
@ -38,7 +38,7 @@ We recommend using a virtual environment for Python projects. The A2A Python SDK
.venv\Scripts\activate
```
2. **Install the A2A SDK and its required Python dependencies:**
2. **Install needed Python dependencies along with the A2A SDK and its dependencies:**
```bash
pip install -r samples/python/requirements.txt

View File

@ -8,15 +8,14 @@ We'll use the `helloworld` example located in [`a2a-samples/samples/python/agent
An **Agent Skill** describes a specific capability or function the agent can perform. It's a building block that tells clients what kinds of tasks the agent is good for.
Attributes of an `AgentSkill` (defined in `a2a.types`):
Key attributes of an `AgentSkill` (defined in `a2a.types`):
- `id`: A unique identifier for the skill.
- `name`: A human-readable name.
- `description`: A more detailed explanation of what the skill does.
- `tags`: Keywords for categorization and discovery.
- `examples`: Sample prompts or use cases.
- `input_modes` / `output_modes`: Supported Media Types for input and output (e.g., "text/plain", "application/json").
- `security_requirements`: Security schemes necessary for this skill.
- `inputModes` / `outputModes`: Supported Media Types for input and output (e.g., "text/plain", "application/json").
In `__main__.py`, you can see how a skill for the Helloworld agent is defined:
@ -33,9 +32,9 @@ The **Agent Card** is a JSON document that an A2A Server makes available, typica
Key attributes of an `AgentCard` (defined in `a2a.types`):
- `name`, `description`, `version`: Basic identity information.
- `supported_interfaces`: Ordered list of endpoints and protocols where the A2A service can be reached.
- `capabilities`: Supported A2A features like `streaming` or `extended_agent_card`.
- `default_input_modes` / `default_output_modes`: Default Media Types for the agent.
- `url`: The endpoint where the A2A service can be reached.
- `capabilities`: Specifies supported A2A features like `streaming` or `pushNotifications`.
- `defaultInputModes` / `defaultOutputModes`: Default Media Types for the agent.
- `skills`: A list of `AgentSkill` objects that the agent offers.
The `helloworld` example defines its Agent Card like this:
@ -44,4 +43,6 @@ The `helloworld` example defines its Agent Card like this:
--8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/__main__.py:AgentCard"
```
This card tells us the agent is named "Hello World Agent", can be run at `http://127.0.0.1:9999/`, supports text interactions, and has the `hello_world` skill.
This card tells us the agent is named "Hello World Agent", runs at `http://localhost:9999/`, supports text interactions, and has the `hello_world` skill. It also indicates public authentication, meaning no specific credentials are required.
Understanding the Agent Card is crucial because it's how a client discovers an agent and learns how to interact with it.

View File

@ -22,7 +22,7 @@ Let's look at `agent_executor.py`. It defines `HelloWorldAgentExecutor`.
--8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/agent_executor.py:HelloWorldAgent"
```
It has a simple `invoke` method that returns the string "Hello, World!".
It has a simple `invoke` method that returns the string "Hello World".
2. **The Executor (`HelloWorldAgentExecutor`)**:
This class implements the `AgentExecutor` interface.
@ -41,16 +41,17 @@ Let's look at `agent_executor.py`. It defines `HelloWorldAgentExecutor`.
--8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/agent_executor.py:HelloWorldAgentExecutor_execute"
```
When a `Send Message` or `Send Streaming Message` request comes in (both are handled by `execute` in this simplified executor), the following steps occur:
When a `message/send` or `message/stream` request comes in (both are handled by `execute` in this simplified executor):
**Step 1.** The `A2A instance` (server) retrieves the current task from the context. If there is no task in context, then it creates a new task and adds it to the `EventQueue`.
1. It calls `self.agent.invoke()` to get the "Hello World" string.
2. It creates an A2A `Message` object using the `new_agent_text_message` utility function.
3. It enqueues this message onto the `event_queue`. The underlying `DefaultRequestHandler` will then process this queue to send the response(s) to the client. For a single message like this, it will result in a single response for `message/send` or a single event for `message/stream` before the stream closes.
**Step 2.** It enqueues a `TaskStatusUpdateEvent` with a state of `TASK_STATE_WORKING` to indicate the agent has begun processing.
- **`cancel`**:
The Hello World example's `cancel` method simply raises an exception, indicating that cancellation is not supported for this basic agent.
**Step 3.** It calls `self.agent.invoke()` to execute the actual business logic (which simply returns "Hello, World!").
**Step 4.** It enqueues a `TaskArtifactUpdateEvent` containing the result text from the agent.
**Step 5.** Finally, it enqueues a `TaskStatusUpdateEvent` with a state of `TASK_STATE_COMPLETED` to conclude the task.
```python { .no-copy }
--8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/agent_executor.py:HelloWorldAgentExecutor_cancel"
```
The `AgentExecutor` acts as the bridge between the A2A protocol (managed by the request handler and server application) and your agent's specific logic. It receives context about the request and uses an event queue to communicate results or updates back.

View File

@ -2,9 +2,7 @@
Now that we have an Agent Card and an Agent Executor, we can set up and start the A2A server.
To set up an A2A server, the Python SDK provides a route factory and helper functions (`create_agent_card_routes`, `create_jsonrpc_routes`, `create_rest_routes`). Use the route factory to create routes for the A2A server's services. These routes can be attached natively to popular frameworks like [Starlette](https://www.starlette.io/) and [FastAPI](https://fastapi.tiangolo.com/), which give you better control over authentication, logging, and other features.
In this tutorial, we will use Starlette with [Uvicorn](https://www.uvicorn.org/).
The A2A Python SDK provides an `A2AStarletteApplication` class that simplifies running an A2A-compliant HTTP server. It uses [Starlette](https://www.starlette.io/) for the web framework and is typically run with an ASGI server like [Uvicorn](https://www.uvicorn.org/).
## Server Setup in Helloworld
@ -18,22 +16,21 @@ Let's break this down:
1. **`DefaultRequestHandler`**:
- The SDK provides `DefaultRequestHandler`. This handler takes your `AgentExecutor` implementation (`HelloWorldAgentExecutor`), a `TaskStore` (`InMemoryTaskStore`), and the public and extended `AgentCard` objects.
- The SDK provides `DefaultRequestHandler`. This handler takes your `AgentExecutor` implementation (here, `HelloWorldAgentExecutor`) and a `TaskStore` (here, `InMemoryTaskStore`).
- It routes incoming A2A RPC calls to the appropriate methods on your executor (like `execute` or `cancel`).
- The `TaskStore` is used by the `DefaultRequestHandler` to manage the lifecycle of tasks, especially for stateful interactions, streaming, and resubscription. Even if your agent executor is simple, the handler needs a task store.
- `agent_card` is passed to the handler so it can verify the agent's declared capabilities when processing incoming requests. For example, it checks whether streaming or push notifications are supported before handling those request types.
- `extended_agent_card` is passed so the handler can serve it via the `GetExtendedAgentCard` RPC method to authenticated clients.
2. **`create_agent_card_routes` and `create_jsonrpc_routes`**:
2. **`A2AStarletteApplication`**:
- `create_agent_card_routes(public_agent_card)` returns Starlette routes that expose the Agent Card at the `/.well-known/agent-card.json` endpoint for public discovery.
- `create_jsonrpc_routes(request_handler, '/')` returns Starlette routes that handle all incoming A2A JSON-RPC method calls by delegating to the `request_handler`.
- These route lists are combined and passed to a standard `Starlette` application.
- The `A2AStarletteApplication` class is instantiated with the `agent_card` and the `request_handler` (referred to as `http_handler` in its constructor).
- The `agent_card` is crucial because the server will expose it at the `/.well-known/agent-card.json` endpoint (by default).
- The `request_handler` is responsible for processing all incoming A2A method calls by interacting with your `AgentExecutor`.
3. **`uvicorn.run(app, ...)`**:
- The constructed `Starlette` app is run using `uvicorn.run()`, making your agent accessible over HTTP.
- `host='127.0.0.1'` makes the server accessible only from your local machine.
- `port=9999` specifies the port to listen on. This matches the endpoints defined in the `AgentCard`'s `supported_interfaces`.
3. **`uvicorn.run(server_app_builder.build(), ...)`**:
- The `A2AStarletteApplication` has a `build()` method that constructs the actual Starlette application.
- This application is then run using `uvicorn.run()`, making your agent accessible over HTTP.
- `host='0.0.0.0'` makes the server accessible on all network interfaces on your machine.
- `port=9999` specifies the port to listen on. This matches the `url` in the `AgentCard`.
## Running the Helloworld Server
@ -52,7 +49,7 @@ You should see output similar to this, indicating the server is running:
INFO: Started server process [xxxxx]
INFO: Waiting for application startup.
INFO: Application startup complete.
INFO: Uvicorn running on http://127.0.0.1:9999 (Press CTRL+C to quit)
INFO: Uvicorn running on http://0.0.0.0:9999 (Press CTRL+C to quit)
```
Your A2A Helloworld agent is now live and listening for requests! In the next step, we'll interact with it.

View File

@ -1,18 +1,18 @@
# 6. Interacting with the Server
With the Helloworld A2A server running, let's send some requests to it.
With the Helloworld A2A server running, let's send some requests to it. The SDK includes a client (`A2AClient`) that simplifies these interactions.
## The Helloworld Test Client
The `test_client.py` script demonstrates how to:
1. Fetch the Agent Card from the server.
2. Create a client using `create_client`.
3. Send both `Send Message` and `Send Streaming Message` requests.
2. Create an `A2AClient` instance.
3. Send both non-streaming (`message/send`) and streaming (`message/stream`) requests.
Open a **new terminal window**, activate your virtual environment, and navigate to the `a2a-samples` directory.
Activate the virtual environment (be sure to do this in the same directory where you created it):
Activate virtual environment (Be sure to do this in the same directory where you created the virtual environment):
=== "Mac/Linux"
@ -37,201 +37,59 @@ python samples/python/agents/helloworld/test_client.py
Let's look at key parts of `test_client.py`:
1. **Fetching the Agent Card**:
1. **Fetching the Agent Card & Initializing the Client**:
```python { .no-copy }
--8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/test_client.py:A2ACardResolver"
```
The `A2ACardResolver` class is a convenience. When `get_agent_card()` is called, it fetches the `AgentCard` from the server's `/.well-known/agent-card.json` endpoint (based on the provided base URL), which is then used to initialize the client.
The `A2ACardResolver` class is a convenience. It first fetches the `AgentCard` from the server's `/.well-known/agent-card.json` endpoint (based on the provided base URL) and then initializes the client with it.
2. **Initializing the Client & Sending a Non-Streaming Message**:
2. **Sending a Non-Streaming Message (`send_message`)**:
```python { .no-copy }
--8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/test_client.py:message_send"
--8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/test_client.py:send_message"
```
- The `create_client` function creates a `Client` based on the information provided by the `AgentCard` and a `ClientConfig`.
- We construct a `Message` using the `new_text_message` helper (passing `role=Role.ROLE_USER`), then wrap it in a `SendMessageRequest`.
- The client's `send_message` method returns an async iterator that yields a single final `Task` or `Message` response from the agent. In this example, it is a `Task`.
- The `send_message_payload` constructs the data for `MessageSendParams`.
- This is wrapped in a `SendMessageRequest`.
- It includes a `message` object with the `role` set to "user" and the content in `parts`.
- The Helloworld agent's `execute` method will enqueue a single "Hello World" message. The `DefaultRequestHandler` will retrieve this and send it as the response.
- The `response` will be a `SendMessageResponse` object, which contains either a `SendMessageSuccessResponse` (with the agent's `Message` as the result) or a `JSONRPCErrorResponse`.
3. **Initializing the Client & Sending a Streaming Message**:
3. **Handling Task IDs (Illustrative Note for Helloworld)**:
The Helloworld client (`test_client.py`) doesn't attempt `get_task` or `cancel_task` directly because the simple Helloworld agent's `execute` method, when called via `message/send`, results in the `DefaultRequestHandler` returning a direct `Message` response rather than a `Task` object. More complex agents that explicitly manage tasks (like the LangGraph example) would return a `Task` object from `message/send`, and its `id` could then be used for `get_task` or `cancel_task`.
4. **Sending a Streaming Message (`send_message_streaming`)**:
```python { .no-copy }
--8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/test_client.py:message_stream"
--8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/test_client.py:send_message_streaming"
```
- A separate streaming client is created via `create_client` with `streaming=True` in its `ClientConfig`.
- We again call `send_message`, which now streams events: each iteration of the loop prints a discrete chunk as it arrives over the network.
- Call `await streaming_client.close()` after the loop to release the underlying HTTP connection.
- This method calls the agent's `message/stream` endpoint. The `DefaultRequestHandler` will invoke the `HelloWorldAgentExecutor.execute` method.
- The `execute` method enqueues one "Hello World" message, and then the event queue is closed.
- The client will receive this single message as one `SendStreamingMessageResponse` event, and then the stream will terminate.
- The `stream_response` is an `AsyncGenerator`.
## Expected Output
When you run `test_client.py`, you'll see output for:
When you run `test_client.py`, you'll see JSON outputs for:
- The public agent card, displayed in a formatted summary.
- The non-streaming response: a single `task` in protobuf text format containing the completed status, the generated artifact with "Hello, World!", and the agent's intermediate status message in history.
- The streaming response: four chunks — the initial `task`, a `status_update` for WORKING, an `artifact_update` with the result, and a final `status_update` for COMPLETED.
- The extended agent card, displayed in a formatted summary (with an additional `super_hello_world` skill).
- The non-streaming response (a single "Hello World" message).
- The streaming response (a single "Hello World" message as one chunk, after which the stream ends).
The `id` fields in the output will vary with each run.
```console { .no-copy }
AgentCard
--- General ---
Name : Hello World Agent
Description : Just a hello world agent
Version : 0.0.1
--- Interfaces ---
[0] http://127.0.0.1:9999 (JSONRPC)
--- Capabilities ---
Streaming : True
Push notifications : False
Extended agent card : True
--- I/O Modes ---
Input : text/plain
Output : text/plain
--- Skills ---
----------------------------------------------------
ID : hello_world
Name : Returns hello world
Description : just returns hello world
Tags : hello world
Example : hi
Example : hello world
--- Non-Streaming Call ---
Non-streaming Client initialized.
Response:
// Non-streaming response
task {
id: "xxxxxxxx"
context_id: "yyyyyyyy"
status {
state: TASK_STATE_COMPLETED
}
artifacts {
artifact_id: "zzzzzzzz"
name: "result"
parts {
text: "Hello, World!"
}
}
history {
message_id: "vvvvvvvv"
context_id: "yyyyyyyy"
task_id: "xxxxxxxx"
role: ROLE_USER
parts {
text: "Say hello."
}
}
history {
message_id: "wwwwwwww"
role: ROLE_AGENT
parts {
text: "Processing request..."
}
}
}
// Streaming response
task {
id: "xxxxxxxx-s"
context_id: "yyyyyyyy-s"
status {
state: TASK_STATE_SUBMITTED
}
history {
message_id: "vvvvvvvv"
context_id: "yyyyyyyy-s"
task_id: "xxxxxxxx-s"
role: ROLE_USER
parts {
text: "Say hello."
}
}
}
Response chunk:
status_update {
task_id: "xxxxxxxx-s"
context_id: "yyyyyyyy-s"
status {
state: TASK_STATE_WORKING
message {
message_id: "zzzzzzzz-s"
role: ROLE_AGENT
parts {
text: "Processing request..."
}
}
}
}
Response chunk:
artifact_update {
task_id: "xxxxxxxx-s"
context_id: "yyyyyyyy-s"
artifact {
artifact_id: "wwwwwwww-s"
name: "result"
parts {
text: "Hello, World!"
}
}
}
Response chunk:
status_update {
task_id: "xxxxxxxx-s"
context_id: "yyyyyyyy-s"
status {
state: TASK_STATE_COMPLETED
}
}
AgentCard
--- General ---
Name : Hello World Agent - Extended Edition
Description : The full-featured hello world agent for authenticated users.
Version : 0.0.2
--- Interfaces ---
[0] http://127.0.0.1:9999 (JSONRPC)
--- Capabilities ---
Streaming : True
Push notifications : False
Extended agent card : True
--- I/O Modes ---
Input : text/plain
Output : text/plain
--- Skills ---
----------------------------------------------------
ID : hello_world
Name : Returns hello world
Description : just returns hello world
Tags : hello world
Example : hi
Example : hello world
----------------------------------------------------
ID : super_hello_world
Name : Returns a SUPER Hello World
Description : A more enthusiastic greeting, only for authenticated users.
Tags : hello world, super, extended
Example : super hi
Example : give me a super hello
{"jsonrpc":"2.0","id":"xxxxxxxx","result":{"message":{"role":"ROLE_AGENT","parts":[{"text":"Hello World"}],"messageId":"yyyyyyyy"}}}
// Streaming response (one chunk)
{"jsonrpc":"2.0","id":"zzzzzzzz","result":{"message":{"role":"ROLE_AGENT","parts":[{"text":"Hello World"}],"messageId":"wwwwwwww"}}}
```
_(Actual IDs like `xxxxxxxx`, `yyyyyyyy`, `zzzzzzzz`, `wwwwwwww`, and `vvvvvvvv` will be different UUIDs in each run.)_
_(Actual IDs like `xxxxxxxx`, `yyyyyyyy`, `zzzzzzzz`, `wwwwwwww` will be different UUIDs/request IDs)_
This confirms your server is correctly handling basic A2A interactions with the updated SDK structure.
This confirms your server is correctly handling basic A2A interactions with the updated SDK structure!
You can now shut down the server by pressing Ctrl+C in the terminal window where `__main__.py` is running.
Now you can shut down the server by typing Ctrl+C in the terminal window where `__main__.py` is running.

View File

@ -6,7 +6,7 @@ This example features a "Currency Agent" that uses the Gemini model via LangChai
## Setting up the LangGraph Example
1. Create a [Gemini API Key](https://ai.google.dev/gemini-api/docs/api-key) if you don't already have one.
1. Create a [Gemini API Key](https://ai.google.dev/gemini-api/docs/api-key), if you don't already have one.
2. **Environment Variable:**
@ -64,14 +64,14 @@ The `langgraph` example showcases several important A2A concepts:
```
- The `CurrencyAgentExecutor` (in `samples/langgraph/agent_executor.py`), when its `execute` method is called by the `DefaultRequestHandler`, interacts with the `RequestContext` which contains the current task (if any).
- For `Send Message`, the `DefaultRequestHandler` uses the `TaskStore` to persist and retrieve task state across interactions. The response to `Send Message` will be a full `Task` object if the agent's execution flow involves multiple steps or results in a persistent task.
- For `message/send`, the `DefaultRequestHandler` uses the `TaskStore` to persist and retrieve task state across interactions. The response to `message/send` will be a full `Task` object if the agent's execution flow involves multiple steps or results in a persistent task.
- The `test_client.py`'s `run_single_turn_test` demonstrates getting a `Task` object back and then querying it using `get_task`.
3. **Streaming with `TaskStatusUpdateEvent` and `TaskArtifactUpdateEvent`**:
- The `execute` method in `CurrencyAgentExecutor` is responsible for handling both non-streaming and streaming requests, orchestrated by the `DefaultRequestHandler`.
- As the LangGraph agent processes the request (which might involve calling tools like `get_exchange_rate`), the `CurrencyAgentExecutor` enqueues different types of events onto the `EventQueue`:
- `TaskStatusUpdateEvent`: For intermediate updates (e.g., "Looking up exchange rates...", "Processing the exchange rates...").
- `TaskStatusUpdateEvent`: For intermediate updates (e.g., "Looking up exchange rates...", "Processing the exchange rates..").
- `TaskArtifactUpdateEvent`: When the final answer is ready, it's enqueued as an artifact. The `lastChunk` flag is `True`.
- A final `TaskStatusUpdateEvent` with `state=TaskState.completed` is sent to signify the end of the task, closing the stream.
- The `test_client.py`'s `run_streaming_test` function will print these individual event chunks as they are received from the server.

View File

@ -31,7 +31,7 @@ Here are some ideas and resources to continue your A2A journey:
- **Experiment with Advanced Features:**
- Implement robust task management with a persistent `TaskStore` if your agent handles long-running or multi-session tasks.
- Explore implementing push notifications if your agent's tasks are very long-lived.
- Consider more complex input and output modalities (e.g., handling file uploads/downloads via file Parts, or structured data via data Parts).
- Consider more complex input and output modalities (e.g., handling file uploads/downloads, or structured data via `DataPart`).
- **Contribute to the A2A Community:**
- Join the discussions on the [A2A GitHub Discussions page](https://github.com/a2aproject/A2A/discussions).
- Report issues or suggest improvements via [GitHub Issues](https://github.com/a2aproject/A2A/issues).

View File

@ -8,8 +8,7 @@ The v1.0 release focuses on four major themes:
### 1. **Protocol Maturity and Standardization**
- Elevate a2a.proto from being a gRPC-specific implementation file to the universal, normative source of truth
- Leverage formal specification standards (RFC 8785, RFC 7515) and google.rpc.Status where possible
- Leverage formal specification standards (RFC 9457, RFC 8785, RFC 7515) where possible
- Stricter adherence to industry-standard patterns for REST, gRPC, and JSON-RPC bindings
- Enhanced versioning strategy with explicit backward compatibility rules
- Comprehensive error taxonomy with protocol-specific mappings
@ -50,18 +49,28 @@ The v1.0 release focuses on four major themes:
**v0.3.0 Behavior:**
- Operation named `message/send`
- Blocking behavior not explicitly controllable
- Less formal specification of when `Task` vs `Message` is returned
**v1.0 Changes:**
- **✅ RENAMED:** Operation now **`SendMessage`**
- **✅ NEW:** Operation formally named **`SendMessage`** (with legacy alias support)
- **✅ NEW:** `SendMessageConfiguration.blocking` parameter explicitly controls wait behavior
- `blocking: true` - Server waits until task reaches terminal or interrupted state
- `blocking: false` - Server returns immediately; client polls/streams for updates
- **✅ CLARIFIED:** More precise specification of Task vs Message return semantics
- Simple queries MAY return Message directly without creating a Task
- Complex operations MUST return Task for asynchronous handling
- **✅ NEW:** Service parameters transmitted as headers/metadata:
- `A2A-Version`: Protocol version (Major.Minor format)
- `A2A-Extensions`: Comma-separated extension URIs
### Send Streaming Message (`message/stream` → **SendStreamingMessage**)
**v0.3.0 Behavior:**
- Operation named `message/stream`
- SSE-based streaming for JSON-RPC, unspecified for gRPC
- Stream events had `kind` discriminator field
**v1.0 Changes:**
@ -69,8 +78,10 @@ The v1.0 release focuses on four major themes:
- **✅ RENAMED:** Operation now **`SendStreamingMessage`**
- **✅ BREAKING:** Stream events no longer have `kind` field
- Use JSON member names to discriminate between `TaskStatusUpdateEvent` and `TaskArtifactUpdateEvent`
- **✅ NEW:** Formal gRPC streaming semantics defined
- **✅ REMOVED:** `final` boolean field removed from TaskStatusUpdateEvent. Leverage protocol binding specific stream closure mechanism instead.
- **✅ CLARIFIED:** Multiple concurrent streams allowed; all receive same ordered events
- **✅ NEW:** Blocking parameter applies but streaming always provides real-time updates
### Get Task (`tasks/get` → **GetTask**)
@ -92,11 +103,17 @@ The v1.0 release focuses on four major themes:
**v0.3.0 Behavior:**
- Operation unavailable.
- Operation named `tasks/list`
- Available in gRPC and REST only
- Basic pagination with page numbers
**v1.0 Changes:**
- **✅ NEW:** New operation **ListTasks** with filtering capabilities
- **✅ RENAMED:** Operation now **ListTasks**
- **✅ BREAKING:** Changed to cursor-based pagination for scalability
- Request: `cursor` (opaque token from previous response), `limit` (max results)
- Response: `tasks[]`, `nextCursor` (for next page)
- **✅ NEW:** Enhanced filtering capabilities with more explicit specifications
- **✅ CLARIFIED:** Task visibility scoped to authenticated caller
### Cancel Task (`tasks/cancel` → **CancelTask**)
@ -105,10 +122,12 @@ The v1.0 release focuses on four major themes:
- Operation named `tasks/cancel`
- Request with taskId, returns Task
- Error if task not cancelable (implicit)
**v1.0 Changes:**
- **✅ RENAMED:** Operation now **CancelTask**
- **✅ NEW:** Explicit `TaskNotCancelableError` for terminal/non-cancelable tasks
- **✅ CLARIFIED:** More precise specification of when cancellation is allowed
- **✅ CLARIFIED:** Task state transitions for cancellation scenarios
@ -124,12 +143,15 @@ The v1.0 release focuses on four major themes:
- **✅ RENAMED:** `agent/getAuthenticatedExtendedCard` → **GetExtendedAgentCard**
- **✅ BREAKING:** `supportsAuthenticatedExtendedCard` moved to `capabilities.extendedAgentCard`
- **✅ NEW:** Canonicalization (RFC 8785) clarified for Agent Card signature
- **✅ NEW:** Agent Card signature support with JWS (RFC 7515) and canonicalization (RFC 8785)
- **✅ NEW:** `agentId` field added to identify agent instances
- **✅ BREAKING:** `protocolVersion` moved from AgentCard to individual AgentInterface objects
- **✅ BREAKING:** `preferredTransport` and `additionalInterfaces` consolidated into `supportedInterfaces[]`
- Each interface has `url`, `protocolBinding`, and `protocolVersion`
- **✅ NEW:** Extension declarations now include `uri`, `description`, and `required` flag
- **✅ NEW:** Mutual TLS security scheme support added
### Subscribe to task (`tasks/resubscribe` → **SubscribeToTask**)
### NEW: Subscribe to Task (**SubscribeToTask**)
**v0.3.0 Behavior:**
@ -138,10 +160,11 @@ The v1.0 release focuses on four major themes:
**v1.0 Changes:**
- **✅ RENAMED:** Operation now **SubscribeToTask**
- **✅ NEW OPERATION:** **SubscribeToTask** replaces informal resubscription
- **✅ CLARIFIED:** Formal specification of streaming subscription lifecycle
- **✅ CLARIFIED:** Stream closure behavior when task reaches terminal state
- **✅ CLARIFIED:** Multiple concurrent subscriptions supported per task
- **✅ BEHAVIOR CHANGE:** Can subscribe to tasks not originally created via streaming
### Push Notification Operations
@ -154,10 +177,12 @@ The v1.0 release focuses on four major themes:
**v1.0 Changes:**
- **✅ RENAMED:** Operations now **CreateTaskPushNotificationConfig**, **GetTaskPushNotificationConfig**, **ListTaskPushNotificationConfigs**, **DeleteTaskPushNotificationConfig**
- **✅ RENAMED:** Operations now **CreatePushNotificationConfig**, **GetPushNotificationConfig**, **ListPushNotificationConfigs**, **DeletePushNotificationConfig**
- **✅ NEW:** `createdAt` timestamp field added to PushNotificationConfig
- **✅ BREAKING:** `token` field removed from PushNotificationConfig (authentication handled via schemes)
- **✅ NEW:** `configId` field added for unique identification
- **✅ CLARIFIED:** Push notification payloads now use StreamResponse format
- **✅ BREAKING:** model changed for all methods, with TaskPushNotificationConfig flattened
- **✅ NEW:** Explicit `PushNotificationNotSupportedError` when capability not available
### NEW: Multi-Tenancy Support
@ -168,10 +193,20 @@ The v1.0 release focuses on four major themes:
**v1.0 Changes:**
- **✅ NEW:** `tenant` field added to all request messages
- **✅ NEW:** `tenant` field added to all gRPC request messages
- **✅ NEW:** `tenant` field added to `AgentInterface` to specify default tenant
- **✅ CLARIFIED:** Tenant provided per-request, inherited from AgentInterface
- **✅ USE CASE:** Enables to serve multiple agents from a single endpoint
- **✅ CLARIFIED:** Tenant can be provided per-request or inherited from AgentInterface
- **✅ USE CASE:** Enables agents to serve multiple organizations from single endpoint
**Example:**
```protobuf
message SendMessageRequest {
string tenant = 1; // Optional tenant identifier
Message message = 2;
SendMessageConfiguration configuration = 3;
}
```
### Protocol Simplifications
@ -200,21 +235,46 @@ The v1.0 release focuses on four major themes:
- **✅ BREAKING:** Removed `/v1` prefix from HTTP+JSON URL paths
- **✅ NEW:** Examples: `POST /message:send`, `GET /tasks/{id}`
- **✅ RATIONALE:** Version can be part of the base url if required by agent owner
- **✅ RATIONALE:** Version specified in `AgentInterface.protocolVersion` field instead
- **✅ BENEFIT:** Cleaner URLs, version management at interface level
---
## Structural Changes in Core Model Objects
### Task Object
**Added Fields:**
- ✅ `createdAt`: Timestamp (ISO 8601) - Task creation time
- ✅ `lastModified`: Timestamp (ISO 8601) - Last state change time
**Modified Fields:**
- ✅ `status`: TaskStatus object now includes more precise timestamp semantics
**Removed Fields:**
- ⛔ `kind`: Discriminator field removed (was always "task")
**Behavior Changes:**
- Messages in `history[]` now include `extensions[]` array
- Artifacts now include `extensions[]` array and `metadata` map
### TaskStatus Object
**Added Fields:**
- No new top-level fields
**Modified Fields:**
- ✅ `state`: **BREAKING** - Enum values changed from lowercase to `SCREAMING_SNAKE_CASE` with `TASK_STATE_` prefix
- v0.3.0: `"submitted"`, `"working"`, `"completed"`, `"failed"`, `"canceled"`, `"rejected"`, `"input-required"`, `"auth-required"`
- v1.0: `"TASK_STATE_SUBMITTED"`, `"TASK_STATE_WORKING"`, `"TASK_STATE_COMPLETED"`, `"TASK_STATE_FAILED"`, `"TASK_STATE_CANCELED"`, `"TASK_STATE_REJECTED"`, `"TASK_STATE_INPUT_REQUIRED"`, `"TASK_STATE_AUTH_REQUIRED"`
- ✅ `timestamp`: Now explicitly ISO 8601 UTC with millisecond precision (YYYY-MM-DDTHH:mm:ss.sssZ)
- ✅ `message`: Optional Message with enhanced extension support
**Removed Fields:**
@ -244,6 +304,7 @@ The v1.0 release focuses on four major themes:
**Added Fields:**
- ✅ `timestamp`: ISO 8601 timestamp - Message creation time
- ✅ `extensions[]`: Array of extension URIs applicable to this message
**Modified Fields:**
@ -251,6 +312,11 @@ The v1.0 release focuses on four major themes:
- ✅ `role`: **BREAKING** - Enum values changed from lowercase to `SCREAMING_SNAKE_CASE` with `ROLE_` prefix
- v0.3.0: `"user"`, `"agent"`
- v1.0: `"ROLE_USER"`, `"ROLE_AGENT"`
- ✅ `metadata`: Remains optional key-value map but with stricter typing
**Removed Fields:**
- None
**Example Migration:**
@ -265,6 +331,7 @@ The v1.0 release focuses on four major themes:
{
"role": "ROLE_USER",
"parts": [{"text": "Hello"}],
"timestamp": "2024-03-15T10:15:00.000Z"
}
```
@ -344,6 +411,7 @@ The Part structure has been completely redesigned in v1.0. Instead of separate T
- ✅ **NEW:** `filename` field - available for all part types (not just files)
- ✅ **NEW:** `raw` field for inline binary content (base64 in JSON)
- ✅ **NEW:** `url` field for file references (replaces `file.fileWithUri`)
- ✅ **RETAINED:** `metadata` optional map
**Migration Examples:**
@ -367,17 +435,34 @@ if ("text" in part) { ... } // v1.0
**Added Fields:**
- ✅ `createdAt`: Timestamp - Artifact creation time
- ✅ `extensions[]`: Array of extension URIs
**Modified Fields:**
- ✅ `parts[]`: Now uses member-based Part discrimination (see Part changes above)
**Removed Fields:**
- None
**Behavior Changes:**
- Metadata now more formally specified with extension integration
### AgentCard Object
**Added Fields:**
- ✅ `supportedInterfaces[]`: Array of `AgentInterface` objects
- ✅ `agentId`: Unique identifier for the agent instance
- ✅ `supportedInterfaces[]`: Array of AgentInterface objects (each with url, protocolBinding, and protocolVersion)
- ✅ `signatures[]`: Array of JWS signatures for card verification
**Modified Fields:**
- ✅ `capabilities.extendedAgentCard`: Moved from top-level `supportsAuthenticatedExtendedCard`
- ✅ `extensions[]`: Enhanced with `uri`, `description`, and `required` fields (previously simpler Extension type)
- ✅ `securitySchemes`: Enhanced with mutual TLS support
**Removed Fields:**
@ -405,6 +490,7 @@ if ("text" in part) { ... } // v1.0
```json
{
"agentId": "agent-abc-123",
"supportedInterfaces": [
{
"url": "https://agent.example.com/a2a",
@ -419,11 +505,74 @@ if ("text" in part) { ... } // v1.0
}
```
### AgentExtension Object
**v0.3.0 Structure:**
```json
{
"id": "extension-id",
"name": "Extension Name",
"version": "1.0",
"description": "Description",
"documentation": "https://...",
"metadata": {}
}
```
**v1.0 Structure:**
```json
{
"uri": "https://example.com/extensions/custom-ext/v1",
"description": "Description",
"required": false
}
```
**Changes:**
- ⛔ **REMOVED:** `id`, `name`, `version` fields
- ⛔ **REMOVED:** `documentation` field
- ⛔ **REMOVED:** `metadata` field
- ✅ **NEW:** `uri` field - Versioned URI identifying the extension
- ✅ **NEW:** `required` boolean - Indicates if client must support this extension
- ✅ **SIMPLIFIED:** Description remains, but structure dramatically simplified
- ✅ **PATTERN:** Extension versioning now embedded in URI (e.g., `/v1`, `/v2`)
### AgentCapabilities Object
**Removed Fields:**
- ⛔ `stateTransitionHistory` (#1396) - Removed as no API implementation existed for this feature
**Rationale:**
The `stateTransitionHistory` capability flag was misleading as v1.0 has no corresponding API to:
- Store status history in Task objects
- Retrieve status history via Get/List operations
- Query historical state transitions
This capability may be reintroduced in a future version with proper implementation.
**Modified Fields:**
- ✅ `extendedAgentCard`: Moved from top-level `supportsAuthenticatedExtendedCard` field
- ✅ `pushNotifications`: More formally specified with enhanced configuration options
- ✅ `streaming`: Enhanced with clearer semantics for SSE support
### SecurityScheme Objects
**Added:**
- ✅ `MutualTLSSecurityScheme`: Support for mutual TLS authentication
**Enhanced:**
- ✅ More formal alignment with OpenAPI security scheme patterns
- ✅ Better documentation of OAuth2 flows and scopes
- ✅ Clearer distinction between security scheme definitions and requirements
### PushNotificationConfig Object
@ -436,6 +585,15 @@ if ("text" in part) { ... } // v1.0
- ✅ `authentication`: Enhanced PushNotificationAuthenticationInfo structure
**Removed Fields:**
- ⛔ `token`: Client-provided token removed (auth handled via schemes)
**Behavior Changes:**
- Configuration now identified by `configId` instead of implicit task association
- Authentication schemes formalized with proper standards alignment
### Stream Event Objects
**TaskStatusUpdateEvent:**
@ -556,11 +714,11 @@ v1.0 introduces several new formal dependencies on industry-standard specificati
### Added Specifications
#### ✅ google.rpc.Status / google.rpc.ErrorInfo
#### ✅ RFC 9457 - Problem Details for HTTP APIs
- **Purpose:** Standardized error response model with ProtoJSON representation
- **Usage:** Error responses for HTTP+JSON and JSON-RPC bindings
- **Impact:** Replaces RFC 9457 for HTTP errors. Enforces structured `ErrorInfo` with `reason` and `domain` for A2A-specific errors.
- **Purpose:** Standardized error response format
- **Usage:** HTTP+JSON binding error responses
- **Impact:** More consistent, machine-readable error handling in REST APIs
#### ✅ RFC 8785 - JSON Canonicalization Scheme (JCS)
@ -758,85 +916,16 @@ const message = { role: "ROLE_USER", parts: [...] };
- `file.mimeType` → `mediaType`
- Operation names (aliases provided during transition)
#### 7. Standardized Error Handling via google.rpc.Status (HIGH IMPACT)
HTTP+JSON error responses have been updated to use the ProtoJSON representation of `google.rpc.Status` instead of RFC 9457 (Problem Details). JSON-RPC and HTTP+JSON bindings now use `google.rpc.ErrorInfo` within the `data` / `details` array to provide A2A-specific error context.
**Changes:**
- **HTTP+JSON Content-Type:** Changed from `application/problem+json` to `application/json`.
- **Error Model:** Uses `google.rpc.Status` fields (`code`, `message`, `details`).
- **A2A Error Info:** MUST include a `google.rpc.ErrorInfo` object in `details` with `reason` (UPPER_SNAKE_CASE from A2A error types) and `domain: "a2a-protocol.org"`.
**JSON-RPC Example Migration:**
```json
// v0.3.0
"error": {
"code": -32001,
"message": "Task not found",
"data": { "taskId": "123" }
}
// v1.0
"error": {
"code": -32001,
"message": "Task not found",
"data": [
{
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
"reason": "TASK_NOT_FOUND",
"domain": "a2a-protocol.org",
"metadata": { "taskId": "123" }
}
]
}
```
**HTTP+JSON Example Migration:**
```http
// v0.3.0 (Draft using RFC 9457)
HTTP/1.1 404 Not Found
Content-Type: application/problem+json
{
"type": "https://a2a-protocol.org/errors/task-not-found",
"title": "Task Not Found",
"status": 404,
"detail": "The specified task ID does not exist"
}
// v1.0
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error": {
"code": 404,
"status": "NOT_FOUND",
"message": "The specified task ID does not exist",
"details": [
{
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
"reason": "TASK_NOT_FOUND",
"domain": "a2a-protocol.org"
}
]
}
}
```
### New Capabilities to Leverage
#### 1. Execution Mode Control
#### 1. Blocking Parameter Control
```typescript
// Wait for task completion (Default)
const result = await sendMessage(message, { returnImmediately: false });
// Wait for task completion
const result = await sendMessage(message, { blocking: true });
// Return immediately, poll later
const task = await sendMessage(message, { returnImmediately: true });
const task = await sendMessage(message, { blocking: false });
```
#### 2. Agent Card Signature Verification
@ -964,7 +1053,7 @@ class A2AClient {
- Implement cursor-based pagination
- Update enum value handling (state field)
- Add return_immediately parameter support
- Add blocking parameter support
#### Medium (Within 3 Months)

View File

@ -1,11 +1,12 @@
exclude = [
'https://fonts.gstatic.com/',
'https://fonts.googleapis.com/',
'http://go/github',
'http://go/github-googlecloudplatform',
'https://medium.com/',
'https://x.com/',
'http://localhost:12000/',
'http://localhost:10020/',
'https://goo.gle/',
]
exclude_path = [
".github/actions/spelling",

View File

@ -20,7 +20,6 @@ extra:
# Navigation
nav:
- Home: index.md
- 🆕 Announcing Version 1.0: announcing-1.0.md
- Documentation:
- What is A2A?: topics/what-is-a2a.md
- Core Concepts: topics/key-concepts.md
@ -28,8 +27,6 @@ nav:
- Enterprise Features: topics/enterprise-ready.md
- Life of a Task: topics/life-of-a-task.md
- Extensions: topics/extensions.md
- Custom Protocol Bindings: topics/custom-protocol-bindings.md
- Extension & Binding Governance: topics/extension-and-binding-governance.md
- Streaming & Asynchronous Operations: topics/streaming-and-async.md
- A2A and MCP: topics/a2a-and-mcp.md
- Tutorials and Samples:
@ -43,10 +40,8 @@ nav:
- Interact with Server: tutorials/python/6-interact-with-server.md
- Streaming & Multiturn: tutorials/python/7-streaming-and-multiturn.md
- Next Steps: tutorials/python/8-next-steps.md
- DeepLearning.AI Course: https://goo.gle/dlai-a2a
- Specification:
- Overview: specification.md
- What's New in v1.0: whats-new-v1.md
- Protocol Definition: definitions.md
- SDK Reference:
- sdk/index.md

View File

@ -6,5 +6,3 @@ mkdocs-macros-plugin
sphinx
furo
myst-parser
proto-schema-parser
tabulate

27
scripts/api-linter.sh Executable file
View File

@ -0,0 +1,27 @@
#!/bin/bash
# Exit on error (-e), undefined variable usage (-u), or failed pipe command (-o pipefail).
set -euo pipefail
# Determine the repository root directory based on the script's location.
SCRIPT_DIR=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" &>/dev/null && pwd)
REPO_ROOT=$(cd -- "${SCRIPT_DIR}/.." &>/dev/null && pwd)
# Change to the repository root so that file paths are relative to it.
cd "${REPO_ROOT}"
# Run API Linter locally using Docker.
# This mirrors the configuration used in GitHub Actions.
# Using the image used by the googleapis/api-linter action.
echo "Running API Linter..."
docker run \
--rm \
-t \
-v "${REPO_ROOT}:/workspace" \
-w /workspace \
gcr.io/gapic-images/api-linter:latest \
--proto-path=specification \
--config-path=specification/.api-linter.yaml \
specification/*.proto
echo "API Linter finished."

View File

@ -8,51 +8,23 @@ set -e
OUTPUT_FILE="docs/llms-full.txt"
DOCS_DIR="docs"
SPEC_DIR="specification"
SDK_DOCS_SCRIPT="scripts/build_sdk_docs.sh"
PROJECT_NAME="A2A (Agent2Agent) Protocol"
echo "--- Generating consolidated LLM file: ${OUTPUT_FILE} ---"
# --- Generate Python SDK Text Documentation ---
if [ -f "$SDK_DOCS_SCRIPT" ]; then
echo "Generating Python SDK documentation..."
bash "$SDK_DOCS_SCRIPT"
else
echo "Warning: SDK docs script not found at $SDK_DOCS_SCRIPT"
fi
# Clear the output file to start fresh
true >"${OUTPUT_FILE}"
# Clear the output file and add introduction
cat <<EOF >"${OUTPUT_FILE}"
# ${PROJECT_NAME} - Full Documentation
This file is a consolidated version of all documentation, specifications, and API references
for the ${PROJECT_NAME} project, optimized for LLM consumption.
EOF
# Include llms.txt as the core summary if it exists
if [ -f "${DOCS_DIR}/llms.txt" ]; then
echo "Including summary from ${DOCS_DIR}/llms.txt"
{
echo "## Project Summary"
echo
cat "${DOCS_DIR}/llms.txt"
echo
echo "---"
echo
} >>"${OUTPUT_FILE}"
fi
# --- Helper function to append file content with XML-style tags ---
# --- Helper function to append file content with a header ---
append_file() {
local file_path="$1"
local display_path="${2:-$file_path}"
if [ -f "$file_path" ]; then
echo "Appending: $file_path"
{
echo "<file path=\"${display_path}\">"
echo "--- START OF FILE ${file_path} ---"
echo
cat "$file_path"
echo "</file>"
echo
echo "================================================="
echo
} >>"${OUTPUT_FILE}"
else
@ -60,59 +32,15 @@ append_file() {
fi
}
# --- Build File List ---
echo "## File Index" >>"${OUTPUT_FILE}"
echo >>"${OUTPUT_FILE}"
# Collect all files we intend to include
FILES_TO_INCLUDE=()
FILES_TO_INCLUDE+=("README.md")
# Doc files
while IFS= read -r doc_file; do
FILES_TO_INCLUDE+=("$doc_file")
done < <(find "${DOCS_DIR}" -type f \( -name "*.md" -o -name "*.rst" \) \
-not -path "docs/sdk/python/*" \
-not -path "docs/README.md" \
-not -path "docs/sdk/python.md" \
-not -path "docs/llms-full.txt" | sort)
# SDK text files
SDK_TEXT_DIR="docs/sdk/python/_build/text"
if [ -d "$SDK_TEXT_DIR" ]; then
while IFS= read -r sdk_file; do
FILES_TO_INCLUDE+=("$sdk_file")
done < <(find "$SDK_TEXT_DIR" -type f -name "*.txt" | sort)
fi
# Specification
if [ -f "${SPEC_DIR}/a2a.proto" ]; then
FILES_TO_INCLUDE+=("${SPEC_DIR}/a2a.proto")
fi
# Write the index to the output file
for f in "${FILES_TO_INCLUDE[@]}"; do
display_name="$f"
# Clean up display name for SDK files
if [[ "$f" == "$SDK_TEXT_DIR"* ]]; then
display_name="sdk/python/${f#"$SDK_TEXT_DIR"/}"
fi
echo "- ${display_name}" >>"${OUTPUT_FILE}"
# --- Process Documentation Files ---
# Find all markdown and rst files in the docs directory, sort them for consistent output,
# and append each one.
find "${DOCS_DIR}" -type f \( -name "*.md" -o -name "*.rst" \) | sort | while read -r doc_file; do
append_file "$doc_file"
done
{
echo
echo "---"
echo
} >>"${OUTPUT_FILE}"
# --- Append file contents ---
for f in "${FILES_TO_INCLUDE[@]}"; do
display_name="$f"
if [[ "$f" == "$SDK_TEXT_DIR"* ]]; then
display_name="sdk/python/${f#"$SDK_TEXT_DIR"/}"
fi
append_file "$f" "$display_name"
done
# --- Process Specification Files ---
append_file "${SPEC_DIR}/grpc/a2a.proto"
append_file "${SPEC_DIR}/json/a2a.json"
echo "✅ Consolidated LLM file generated successfully at ${OUTPUT_FILE}"

View File

@ -43,11 +43,6 @@ echo "--- Building HTML documentation ---"
# Build the HTML documentation
sphinx-build -b html "${DOCS_SOURCE_DIR}" "${DOCS_BUILD_DIR}/html"
echo "--- Building Text documentation ---"
# Build the Text documentation
sphinx-build -b text "${DOCS_SOURCE_DIR}" "${DOCS_BUILD_DIR}/text"
echo "--- Copying SDK docs to MkDocs integration path ---"
# Copy SDK docs to where MkDocs expects them (docs/sdk/python/api/)

View File

@ -1,58 +1,35 @@
# API Linter Configuration
# https://linter.aip.dev/
- included_paths:
- "**/*.proto"
disabled_rules:
- "core::0140::abbreviations"
- "core::0191::java-multiple-files"
- "core::0191::java-outer-classname"
- "core::0191::java-package"
- "core::0191::proto-package"
- "core::0123::resource-annotation"
- "core::0203::optional"
- "core::0203::required"
- "core::0127::http-annotation"
- "core::0131::request-message-name"
- "core::0132::response-message-name"
- "core::0158::request-required-fields"
- "core::0203::input-only"
- "core::0203::output-only"
- "core::0203::immutable"
# Disable rules related to blank lines and formatting
disabled_rules:
# Formatting and blank line rules
- core::0191::java-multiple-files
- core::0191::java-outer-classname
- core::0191::java-package
- core::0191::csharp-namespace
- core::0191::go-package
# TODO: Evaluate if the following should be enabled due to breaking changes
- "core::0131::method-signature"
- "core::0131::http-uri-name"
- "core::0127::resource-name-extraction"
- "core::0131::request-name-required"
- "core::0131::request-required-fields"
- "core::0131::response-message-name"
- "core::0131::request-unknown-fields"
- "core::0132::request-required-fields"
- "core::0132::request-unknown-fields"
- "core::0132::request-parent-required"
- "core::0132::response-unknown-fields"
- "core::0133::http-body"
- "core::0133::request-required-fields"
- "core::0133::request-unknown-fields"
- "core::0133::request-parent-required"
- "core::0133::request-resource-field"
- "core::0133::request-id-field"
- "core::0133::http-uri-parent"
- "core::0135::http-uri-name"
- "core::0135::request-name-required"
- "core::0135::method-signature"
- "core::0135::request-unknown-fields"
- "core::0135::request-required-fields"
- "core::0136::http-uri-suffix"
- "core::0136::prepositions"
- "core::0136::request-message-name"
- "core::0136::response-message-name"
- "core::0140::uri"
- "core::0140::base64"
- "core::0140::prepositions"
- "core::0142::time-field-names"
- "core::0191::file-layout"
- "core::0203::field-behavior-required"
- "core::0216::state-field-output-only"
- "core::0216::nesting"
# Comment and documentation rules
# Enabled relevant rules for better checks
# - core::0192::has-comments # Suppress missing comment warnings
# - core::0123::resource-annotation # Resource name annotations
# - core::0203::optional # Optional field comments
# - core::0203::required # Required field comments
# - core::0127::http-annotation # HTTP annotation comments
# - core::0131::request-message-name # Request naming
# - core::0132::response-message-name # Response naming
# - core::0158::request-required-fields # Required request fields
# Keeping these disabled as they might be too strict for now, but can be enabled later
- core::0203::input-only # Input only field comments
- core::0203::output-only # Output only field comments
- core::0203::immutable # Immutable field comments
# You can also use include_rules to be more specific
# enabled_rules:
# - all
# Set the minimum severity level to report
# Options: disabled, info, warning, error
# severity: warning

View File

@ -1,6 +1,6 @@
// Older protoc compilers don't understand edition yet.
syntax = "proto3";
package lf.a2a.v1;
package a2a.v1;
import "google/api/annotations.proto";
import "google/api/client.proto";
@ -9,15 +9,15 @@ import "google/protobuf/empty.proto";
import "google/protobuf/struct.proto";
import "google/protobuf/timestamp.proto";
option csharp_namespace = "Lf.A2a.V1";
option go_package = "google.golang.org/lf/a2a/v1";
option csharp_namespace = "A2a.V1";
option go_package = "google.golang.org/a2a/v1";
option java_multiple_files = true;
option java_outer_classname = "A2A";
option java_package = "com.google.lf.a2a.v1";
option java_package = "com.google.a2a.v1";
// Provides operations for interacting with agents using the A2A protocol.
// A2AService defines the operations of the A2A protocol.
service A2AService {
// Sends a message to an agent.
// Send a message to the agent.
rpc SendMessage(SendMessageRequest) returns (SendMessageResponse) {
option (google.api.http) = {
post: "/message:send"
@ -28,8 +28,7 @@ service A2AService {
}
};
}
// Sends a streaming message to an agent, allowing for real-time interaction and status updates.
// Streaming version of `SendMessage`
// SendStreamingMessage is a streaming version of SendMessage.
rpc SendStreamingMessage(SendMessageRequest) returns (stream StreamResponse) {
option (google.api.http) = {
post: "/message:stream"
@ -41,7 +40,7 @@ service A2AService {
};
}
// Gets the latest state of a task.
// Get the current state of a task from the agent.
rpc GetTask(GetTaskRequest) returns (Task) {
option (google.api.http) = {
get: "/tasks/{id=*}"
@ -51,7 +50,7 @@ service A2AService {
};
option (google.api.method_signature) = "id";
}
// Lists tasks that match the specified filter.
// List tasks with optional filtering and pagination.
rpc ListTasks(ListTasksRequest) returns (ListTasksResponse) {
option (google.api.http) = {
get: "/tasks"
@ -60,7 +59,7 @@ service A2AService {
}
};
}
// Cancels a task in progress.
// Cancel a task.
rpc CancelTask(CancelTaskRequest) returns (Task) {
option (google.api.http) = {
post: "/tasks/{id=*}:cancel"
@ -71,8 +70,8 @@ service A2AService {
}
};
}
// Subscribes to task updates for tasks not in a terminal state.
// Returns `UnsupportedOperationError` if the task is already in a terminal state (completed, failed, canceled, rejected).
// SubscribeToTask allows subscribing to task updates for tasks not in terminal state.
// Returns UnsupportedOperationError if task is in terminal state (completed, failed, canceled, rejected).
rpc SubscribeToTask(SubscribeToTaskRequest) returns (stream StreamResponse) {
option (google.api.http) = {
get: "/tasks/{id=*}:subscribe"
@ -82,23 +81,19 @@ service A2AService {
};
}
// (-- api-linter: client-libraries::4232::required-fields=disabled
// api-linter: core::0133::method-signature=disabled
// api-linter: core::0133::request-message-name=disabled
// aip.dev/not-precedent: method_signature preserved for backwards compatibility --)
// Creates a push notification config for a task.
rpc CreateTaskPushNotificationConfig(TaskPushNotificationConfig) returns (TaskPushNotificationConfig) {
// Create a push notification config for a task.
rpc CreateTaskPushNotificationConfig(CreateTaskPushNotificationConfigRequest) returns (TaskPushNotificationConfig) {
option (google.api.http) = {
post: "/tasks/{task_id=*}/pushNotificationConfigs"
body: "*"
body: "config"
additional_bindings: {
post: "/{tenant}/tasks/{task_id=*}/pushNotificationConfigs"
body: "*"
body: "config"
}
};
option (google.api.method_signature) = "task_id,config";
}
// Gets a push notification config for a task.
// Get a push notification config for a task.
rpc GetTaskPushNotificationConfig(GetTaskPushNotificationConfigRequest) returns (TaskPushNotificationConfig) {
option (google.api.http) = {
get: "/tasks/{task_id=*}/pushNotificationConfigs/{id=*}"
@ -109,7 +104,7 @@ service A2AService {
option (google.api.method_signature) = "task_id,id";
}
// Get a list of push notifications configured for a task.
rpc ListTaskPushNotificationConfigs(ListTaskPushNotificationConfigsRequest) returns (ListTaskPushNotificationConfigsResponse) {
rpc ListTaskPushNotificationConfig(ListTaskPushNotificationConfigRequest) returns (ListTaskPushNotificationConfigResponse) {
option (google.api.http) = {
get: "/tasks/{task_id=*}/pushNotificationConfigs"
additional_bindings: {
@ -118,7 +113,7 @@ service A2AService {
};
option (google.api.method_signature) = "task_id";
}
// Gets the extended agent card for the authenticated agent.
// GetExtendedAgentCard returns the extended agent card for authenticated agents.
rpc GetExtendedAgentCard(GetExtendedAgentCardRequest) returns (AgentCard) {
option (google.api.http) = {
get: "/extendedAgentCard"
@ -127,7 +122,7 @@ service A2AService {
}
};
}
// Deletes a push notification config for a task.
// Delete a push notification config for a task.
rpc DeleteTaskPushNotificationConfig(DeleteTaskPushNotificationConfigRequest) returns (google.protobuf.Empty) {
option (google.api.http) = {
delete: "/tasks/{task_id=*}/pushNotificationConfigs/{id=*}"
@ -139,28 +134,27 @@ service A2AService {
}
}
///////// Data Model ////////////
// --8<-- [start:SendMessageConfiguration]
// Configuration of a send message request.
message SendMessageConfiguration {
// A list of media types the client is prepared to accept for response parts.
// Agents SHOULD use this to tailor their output.
// A list of media types the client is prepared to accept for response parts. Agents SHOULD use this to tailor their output.
repeated string accepted_output_modes = 1;
// Configuration for the agent to send push notifications for task updates.
// Task id should be empty when sending this configuration in a `SendMessage` request.
TaskPushNotificationConfig task_push_notification_config = 2;
PushNotificationConfig push_notification_config = 2;
// The maximum number of most recent messages from the task's history to retrieve in
// the response. An unset value means the client does not impose any limit. A
// value of zero is a request to not include any messages. The server MUST NOT
// return more messages than the provided value, but MAY apply a lower limit.
optional int32 history_length = 3;
// If `true`, the operation returns immediately after creating the task,
// even if processing is still in progress.
// If `false` (default), the operation MUST wait until the task reaches a
// terminal (`COMPLETED`, `FAILED`, `CANCELED`, `REJECTED`) or interrupted
// (`INPUT_REQUIRED`, `AUTH_REQUIRED`) state before returning.
bool return_immediately = 4;
// If true, the operation waits until the task reaches a terminal or interrupted state before returning. Default is false.
bool blocking = 4;
}
// --8<-- [end:SendMessageConfiguration]
// `Task` is the core unit of action for A2A. It has a current status
// --8<-- [start:Task]
// Task is the core unit of action for A2A. It has a current status
// and when results are created for the task they are stored in the
// artifact. If there are multiple turns for a task, these are stored in
// history.
@ -169,44 +163,51 @@ message Task {
// new task.
string id = 1 [(google.api.field_behavior) = REQUIRED];
// Unique identifier (e.g. UUID) for the contextual collection of interactions
// (tasks and messages).
string context_id = 2;
// The current status of a `Task`, including `state` and a `message`.
// (tasks and messages). Created by the A2A server.
string context_id = 2 [(google.api.field_behavior) = REQUIRED];
// The current status of a Task, including state and a message.
TaskStatus status = 3 [(google.api.field_behavior) = REQUIRED];
// A set of output artifacts for a `Task`.
// A set of output artifacts for a Task.
repeated Artifact artifacts = 4;
// protolint:disable REPEATED_FIELD_NAMES_PLURALIZED
// The history of interactions from a `Task`.
// The history of interactions from a task.
repeated Message history = 5;
// protolint:enable REPEATED_FIELD_NAMES_PLURALIZED
// A key/value object to store custom metadata about a task.
google.protobuf.Struct metadata = 6;
}
// --8<-- [end:Task]
// Defines the possible lifecycle states of a `Task`.
// --8<-- [start:TaskState]
// Defines the possible lifecycle states of a Task.
enum TaskState {
// The task is in an unknown or indeterminate state.
TASK_STATE_UNSPECIFIED = 0;
// Indicates that a task has been successfully submitted and acknowledged.
// Represents the status that acknowledges a task is created.
TASK_STATE_SUBMITTED = 1;
// Indicates that a task is actively being processed by the agent.
// Represents the status that a task is actively being processed.
TASK_STATE_WORKING = 2;
// Indicates that a task has finished successfully. This is a terminal state.
// Represents the status a task is finished. This is a terminal state.
TASK_STATE_COMPLETED = 3;
// Indicates that a task has finished with an error. This is a terminal state.
// Represents the status a task is done but failed. This is a terminal state.
TASK_STATE_FAILED = 4;
// Indicates that a task was canceled before completion. This is a terminal state.
// Represents the status a task was canceled before it finished.
// This is a terminal state.
TASK_STATE_CANCELED = 5;
// Indicates that the agent requires additional user input to proceed. This is an interrupted state.
// Represents the status that the task requires information to complete.
// This is an interrupted state.
TASK_STATE_INPUT_REQUIRED = 6;
// Indicates that the agent has decided to not perform the task.
// Represents the status that the agent has decided to not perform the task.
// This may be done during initial task creation or later once an agent
// has determined it can't or won't proceed. This is a terminal state.
TASK_STATE_REJECTED = 7;
// Indicates that authentication is required to proceed. This is an interrupted state.
// Represents the state that some authentication is needed from the upstream
// client. This is an interrupted state. Authentication is expected to come out-of-band.
TASK_STATE_AUTH_REQUIRED = 8;
}
// --8<-- [end:TaskState]
// --8<-- [start:TaskStatus]
// A container for the status of a task
message TaskStatus {
// The current state of this task.
@ -217,98 +218,118 @@ message TaskStatus {
// Example: "2023-10-27T10:00:00Z"
google.protobuf.Timestamp timestamp = 3;
}
// --8<-- [end:TaskStatus]
// `Part` represents a container for a section of communication content.
// --8<-- [start:Part]
// Part represents a container for a section of communication content.
// Parts can be purely textual, some sort of file (image, video, etc) or
// a structured data blob (i.e. JSON).
message Part {
oneof content {
// The string content of the `text` part.
// The string content of the text part.
string text = 1;
// The `raw` byte content of a file. In JSON serialization, this is encoded as a base64 string.
// The raw byte content of a file. In JSON serialization, this is encoded as a base64 string.
bytes raw = 2;
// A `url` pointing to the file's content.
// A URL pointing to the file's content.
string url = 3;
// Arbitrary structured `data` as a JSON value (object, array, string, number, boolean, or null).
// Arbitrary structured data as a JSON value (object, array, string, number, boolean, or null).
google.protobuf.Value data = 4;
}
// Optional. metadata associated with this part.
// Optional metadata associated with this part.
google.protobuf.Struct metadata = 5;
// An optional `filename` for the file (e.g., "document.pdf").
// An optional name for the file (e.g., "document.pdf").
string filename = 6;
// The `media_type` (MIME type) of the part content (e.g., "text/plain", "application/json", "image/png").
// The media type (MIME type) of the part content (e.g., "text/plain", "application/json", "image/png").
// This field is available for all part types.
string media_type = 7;
}
// --8<-- [end:Part]
// --8<-- [start:Role]
// Defines the sender of a message in A2A protocol communication.
enum Role {
// The role is unspecified.
ROLE_UNSPECIFIED = 0;
// The message is from the client to the server.
// USER role refers to communication from the client to the server.
ROLE_USER = 1;
// The message is from the server to the client.
// AGENT role refers to communication from the server to the client.
ROLE_AGENT = 2;
}
// --8<-- [end:Role]
// `Message` is one unit of communication between client and server. It can be
// associated with a context and/or a task. For server messages, `context_id` must
// be provided, and `task_id` only if a task was created. For client messages, both
// --8<-- [start:Message]
// Message is one unit of communication between client and server. It can be
// associated with a context and/or a task. For server messages, context_id must
// be provided, and task_id only if a task was created. For client messages, both
// fields are optional, with the caveat that if both are provided, they have to
// match (the `context_id` has to be the one that is set on the task). If only
// `task_id` is provided, the server will infer `context_id` from it.
// match (the context_id has to be the one that is set on the task). If only
// task_id is provided, the server will infer context_id from it.
message Message {
// The unique identifier (e.g. UUID) of the message. This is created by the message creator.
// The unique identifier (e.g. UUID) of the message. This is required and
// created by the message creator.
string message_id = 1 [(google.api.field_behavior) = REQUIRED];
// Optional. The context id of the message. If set, the message will be associated with the given context.
// The context id of the message. This is optional and if set, the message
// will be associated with the given context.
string context_id = 2;
// Optional. The task id of the message. If set, the message will be associated with the given task.
// The task id of the message. This is optional and if set, the message
// will be associated with the given task.
string task_id = 3;
// Identifies the sender of the message.
Role role = 4 [(google.api.field_behavior) = REQUIRED];
// protolint:disable REPEATED_FIELD_NAMES_PLURALIZED
// Parts is the container of the message content.
repeated Part parts = 5 [(google.api.field_behavior) = REQUIRED];
// Optional. Any metadata to provide along with the message.
// protolint:enable REPEATED_FIELD_NAMES_PLURALIZED
// Any optional metadata to provide along with the message.
google.protobuf.Struct metadata = 6;
// The URIs of extensions that are present or contributed to this Message.
repeated string extensions = 7;
// A list of task IDs that this message references for additional context.
repeated string reference_task_ids = 8;
}
// --8<-- [end:Message]
// --8<-- [start:Artifact]
// Artifacts represent task outputs.
message Artifact {
// Unique identifier (e.g. UUID) for the artifact. It must be unique within a task.
// Unique identifier (e.g. UUID) for the artifact. It must be at least unique
// within a task.
string artifact_id = 1 [(google.api.field_behavior) = REQUIRED];
// A human readable name for the artifact.
string name = 2;
// Optional. A human readable description of the artifact.
string description = 3;
string name = 3;
// A human readable description of the artifact, optional.
string description = 4;
// The content of the artifact. Must contain at least one part.
repeated Part parts = 4 [(google.api.field_behavior) = REQUIRED];
// Optional. Metadata included with the artifact.
google.protobuf.Struct metadata = 5;
repeated Part parts = 5 [(google.api.field_behavior) = REQUIRED];
// Optional metadata included with the artifact.
google.protobuf.Struct metadata = 6;
// The URIs of extensions that are present or contributed to this Artifact.
repeated string extensions = 6;
repeated string extensions = 7;
}
// --8<-- [end:Artifact]
// An event sent by the agent to notify the client of a change in a task's status.
// --8<-- [start:TaskStatusUpdateEvent]
// An event sent by the agent to notify the client of a change in a task's
// status.
message TaskStatusUpdateEvent {
// The ID of the task that has changed.
// The id of the task that is changed
string task_id = 1 [(google.api.field_behavior) = REQUIRED];
// The ID of the context that the task belongs to.
// The id of the context that the task belongs to
string context_id = 2 [(google.api.field_behavior) = REQUIRED];
// The new status of the task.
TaskStatus status = 3 [(google.api.field_behavior) = REQUIRED];
// Optional. Metadata associated with the task update.
google.protobuf.Struct metadata = 4;
reserved 4;
// Optional metadata to associate with the task update.
google.protobuf.Struct metadata = 5;
}
// --8<-- [end:TaskStatusUpdateEvent]
// A task delta where an artifact has been generated.
// --8<-- [start:TaskArtifactUpdateEvent]
// TaskArtifactUpdateEvent represents a task delta where an artifact has
// been generated.
message TaskArtifactUpdateEvent {
// The ID of the task for this artifact.
// The id of the task for this artifact.
string task_id = 1 [(google.api.field_behavior) = REQUIRED];
// The ID of the context that this task belongs to.
// The id of the context that this task belongs to.
string context_id = 2 [(google.api.field_behavior) = REQUIRED];
// The artifact that was generated or updated.
Artifact artifact = 3 [(google.api.field_behavior) = REQUIRED];
@ -317,20 +338,37 @@ message TaskArtifactUpdateEvent {
bool append = 4;
// If true, this is the final chunk of the artifact.
bool last_chunk = 5;
// Optional. Metadata associated with the artifact update.
// Optional metadata associated with the artifact update.
google.protobuf.Struct metadata = 6;
}
// --8<-- [end:TaskArtifactUpdateEvent]
// --8<-- [start:PushNotificationConfig]
// Configuration for setting up push notifications for task updates.
message PushNotificationConfig {
// A unique identifier (e.g. UUID) for this push notification.
string id = 1;
// Url to send the notification too
string url = 2 [(google.api.field_behavior) = REQUIRED];
// Token unique for this task/session
string token = 3;
// Authentication information required to send the notification
AuthenticationInfo authentication = 4;
}
// --8<-- [end:PushNotificationConfig]
// --8<-- [start:PushNotificationAuthenticationInfo]
// Defines authentication details, used for push notifications.
message AuthenticationInfo {
// HTTP Authentication Scheme from the [IANA registry](https://www.iana.org/assignments/http-authschemes/).
// Examples: `Bearer`, `Basic`, `Digest`.
// Scheme names are case-insensitive per [RFC 9110 Section 11.1](https://www.rfc-editor.org/rfc/rfc9110#section-11.1).
// Common values: `Bearer`, `Basic`, `Digest`. Scheme names are case-insensitive per [RFC 9110 Section 11.1](https://www.rfc-editor.org/rfc/rfc9110#section-11.1).
string scheme = 1 [(google.api.field_behavior) = REQUIRED];
// Push Notification credentials. Format depends on the scheme (e.g., token for Bearer).
string credentials = 2;
}
// --8<-- [end:PushNotificationAuthenticationInfo]
// --8<-- [start:AgentInterface]
// Declares a combination of a target URL, transport and protocol version for interacting with the agent.
// This allows agents to expose the same functionality over multiple protocol binding mechanisms.
message AgentInterface {
@ -341,19 +379,24 @@ message AgentInterface {
// easily extended for other protocol bindings. The core ones officially
// supported are `JSONRPC`, `GRPC` and `HTTP+JSON`.
string protocol_binding = 2 [(google.api.field_behavior) = REQUIRED];
// Tenant ID to be used in the request when calling the agent.
// Tenant to be set in the request when calling the agent.
string tenant = 3;
// The version of the A2A protocol this interface exposes.
// Use the latest supported minor version per major version.
// Examples: "0.3", "1.0"
string protocol_version = 4 [(google.api.field_behavior) = REQUIRED];
}
// --8<-- [end:AgentInterface]
// A self-describing manifest for an agent. It provides essential
// --8<-- [start:AgentCard]
// AgentCard is a self-describing manifest for an agent. It provides essential
// metadata including the agent's identity, capabilities, skills, supported
// communication methods, and security requirements.
// Next ID: 20
message AgentCard {
// Reserve these field numbers as they were previously used by removed
// fields.
reserved 3, 9, 14, 15, 16;
// A human readable name for the agent.
// Example: "Recipe Agent"
string name = 1 [(google.api.field_behavior) = REQUIRED];
@ -361,37 +404,39 @@ message AgentCard {
// in understanding its purpose.
// Example: "Agent that helps users with recipes and cooking."
string description = 2 [(google.api.field_behavior) = REQUIRED];
// Ordered list of supported interfaces. The first entry is preferred.
repeated AgentInterface supported_interfaces = 3 [(google.api.field_behavior) = REQUIRED];
// Ordered list of supported interfaces. First entry is preferred.
repeated AgentInterface supported_interfaces = 19 [(google.api.field_behavior) = REQUIRED];
// The service provider of the agent.
AgentProvider provider = 4;
// The version of the agent.
// Example: "1.0.0"
string version = 5 [(google.api.field_behavior) = REQUIRED];
// A URL providing additional documentation about the agent.
// A url to provide additional documentation about the agent.
optional string documentation_url = 6;
// A2A Capability set supported by the agent.
AgentCapabilities capabilities = 7 [(google.api.field_behavior) = REQUIRED];
// The security scheme details used for authenticating with this agent.
map<string, SecurityScheme> security_schemes = 8;
// Security requirements for contacting the agent.
repeated SecurityRequirement security_requirements = 9;
repeated SecurityRequirement security_requirements = 13;
// protolint:enable REPEATED_FIELD_NAMES_PLURALIZED
// The set of interaction modes that the agent supports across all skills.
// This can be overridden per skill. Defined as media types.
repeated string default_input_modes = 10 [(google.api.field_behavior) = REQUIRED];
// The media types supported as outputs from this agent.
repeated string default_output_modes = 11 [(google.api.field_behavior) = REQUIRED];
// Skills represent the abilities of an agent.
// It is largely a descriptive concept but represents a more focused set of behaviors that the
// Skills represent an ability of an agent. It is largely
// a descriptive concept but represents a more focused set of behaviors that the
// agent is likely to succeed at.
repeated AgentSkill skills = 12 [(google.api.field_behavior) = REQUIRED];
// JSON Web Signatures computed for this `AgentCard`.
repeated AgentCardSignature signatures = 13;
// Optional. A URL to an icon for the agent.
optional string icon_url = 14;
// JSON Web Signatures computed for this AgentCard.
repeated AgentCardSignature signatures = 17;
// An optional URL to an icon for the agent.
optional string icon_url = 18;
}
// --8<-- [end:AgentCard]
// --8<-- [start:AgentProvider]
// Represents the service provider of an agent.
message AgentProvider {
// A URL for the agent provider's website or relevant documentation.
@ -401,7 +446,9 @@ message AgentProvider {
// Example: "Google"
string organization = 2 [(google.api.field_behavior) = REQUIRED];
}
// --8<-- [end:AgentProvider]
// --8<-- [start:AgentCapabilities]
// Defines optional capabilities supported by an agent.
message AgentCapabilities {
// Indicates if the agent supports streaming responses.
@ -410,10 +457,14 @@ message AgentCapabilities {
optional bool push_notifications = 2;
// A list of protocol extensions supported by the agent.
repeated AgentExtension extensions = 3;
// Field 4 was previously used by state_transition_history capability.
reserved 4;
// Indicates if the agent supports providing an extended agent card when authenticated.
optional bool extended_agent_card = 4;
optional bool extended_agent_card = 5;
}
// --8<-- [end:AgentCapabilities]
// --8<-- [start:AgentExtension]
// A declaration of a protocol extension supported by an Agent.
message AgentExtension {
// The unique URI identifying the extension.
@ -422,10 +473,12 @@ message AgentExtension {
string description = 2;
// If true, the client must understand and comply with the extension's requirements.
bool required = 3;
// Optional. Extension-specific configuration parameters.
// Optional, extension-specific configuration parameters.
google.protobuf.Struct params = 4;
}
// --8<-- [end:AgentExtension]
// --8<-- [start:AgentSkill]
// Represents a distinct capability or function that an agent can perform.
message AgentSkill {
// A unique identifier for the agent's skill.
@ -445,52 +498,51 @@ message AgentSkill {
// Security schemes necessary for this skill.
repeated SecurityRequirement security_requirements = 8;
}
// --8<-- [end:AgentSkill]
// --8<-- [start:AgentCardSignature]
// AgentCardSignature represents a JWS signature of an AgentCard.
// This follows the JSON format of an RFC 7515 JSON Web Signature (JWS).
message AgentCardSignature {
// (-- api-linter: core::0140::reserved-words=disabled
// aip.dev/not-precedent: Backwards compatibility --)
// Required. The protected JWS header for the signature. This is always a
// base64url-encoded JSON object.
// The protected JWS header for the signature. This is always a
// base64url-encoded JSON object. Required.
string protected = 1 [(google.api.field_behavior) = REQUIRED];
// Required. The computed signature, base64url-encoded.
// The computed signature, base64url-encoded. Required.
string signature = 2 [(google.api.field_behavior) = REQUIRED];
// The unprotected JWS header values.
google.protobuf.Struct header = 3;
}
// --8<-- [end:AgentCardSignature]
// A container associating a push notification configuration with a specific task.
// --8<-- [start:TaskPushNotificationConfig]
// A container associating a push notification configuration with a specific
// task.
message TaskPushNotificationConfig {
// Optional. Tenant ID.
string tenant = 1;
// Optional tenant
string tenant = 4;
// The id of the config.
string id = 1 [(google.api.field_behavior) = REQUIRED];
// The id of the task this config is associated with.
string task_id = 3 [(google.api.field_behavior) = REQUIRED];
// The push notification configuration details.
// A unique identifier (e.g. UUID) for this push notification configuration.
string id = 2;
// The ID of the task this configuration is associated with.
string task_id = 3;
// The URL where the notification should be sent.
string url = 4 [(google.api.field_behavior) = REQUIRED];
// A token unique for this task or session.
string token = 5;
// Authentication information required to send the notification.
AuthenticationInfo authentication = 6;
PushNotificationConfig push_notification_config = 2 [(google.api.field_behavior) = REQUIRED];
}
// --8<-- [end:TaskPushNotificationConfig]
// protolint:disable REPEATED_FIELD_NAMES_PLURALIZED
// A list of strings.
message StringList {
// The individual string values.
repeated string list = 1;
}
// protolint:enable REPEATED_FIELD_NAMES_PLURALIZED
// Defines the security requirements for an agent.
message SecurityRequirement {
// A map of security schemes to the required scopes.
map<string, StringList> schemes = 1;
}
// --8<-- [start:SecurityScheme]
// Defines a security scheme that can be used to secure an agent's endpoints.
// This is a discriminated union type based on the OpenAPI 3.2 Security Scheme Object.
// See: https://spec.openapis.org/oas/v3.2.0.html#security-scheme-object
@ -508,7 +560,9 @@ message SecurityScheme {
MutualTlsSecurityScheme mtls_security_scheme = 5;
}
}
// --8<-- [end:SecurityScheme]
// --8<-- [start:APIKeySecurityScheme]
// Defines a security scheme using an API key.
message APIKeySecurityScheme {
// An optional description for the security scheme.
@ -518,7 +572,9 @@ message APIKeySecurityScheme {
// The name of the header, query, or cookie parameter to be used.
string name = 3 [(google.api.field_behavior) = REQUIRED];
}
// --8<-- [end:APIKeySecurityScheme]
// --8<-- [start:HTTPAuthSecurityScheme]
// Defines a security scheme using HTTP authentication.
message HTTPAuthSecurityScheme {
// An optional description for the security scheme.
@ -528,35 +584,44 @@ message HTTPAuthSecurityScheme {
// This value should be registered in the IANA Authentication Scheme registry.
string scheme = 2 [(google.api.field_behavior) = REQUIRED];
// A hint to the client to identify how the bearer token is formatted (e.g., "JWT").
// Primarily for documentation purposes.
// This is primarily for documentation purposes.
string bearer_format = 3;
}
// --8<-- [end:HTTPAuthSecurityScheme]
// --8<-- [start:OAuth2SecurityScheme]
// Defines a security scheme using OAuth 2.0.
message OAuth2SecurityScheme {
// An optional description for the security scheme.
string description = 1;
// An object containing configuration information for the supported OAuth 2.0 flows.
OAuthFlows flows = 2 [(google.api.field_behavior) = REQUIRED];
// URL to the OAuth2 authorization server metadata [RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414).
// TLS is required.
// URL to the oauth2 authorization server metadata
// RFC8414 (https://datatracker.ietf.org/doc/html/rfc8414). TLS is required.
string oauth2_metadata_url = 3;
}
// --8<-- [end:OAuth2SecurityScheme]
// --8<-- [start:OpenIdConnectSecurityScheme]
// Defines a security scheme using OpenID Connect.
message OpenIdConnectSecurityScheme {
// An optional description for the security scheme.
string description = 1;
// The [OpenID Connect Discovery URL](https://openid.net/specs/openid-connect-discovery-1_0.html) for the OIDC provider's metadata.
// The OpenID Connect Discovery URL for the OIDC provider's metadata.
// See: https://openid.net/specs/openid-connect-discovery-1_0.html
string open_id_connect_url = 2 [(google.api.field_behavior) = REQUIRED];
}
// --8<-- [end:OpenIdConnectSecurityScheme]
// --8<-- [start:MutualTlsSecurityScheme]
// Defines a security scheme using mTLS authentication.
message MutualTlsSecurityScheme {
// An optional description for the security scheme.
string description = 1;
}
// --8<-- [end:MutualTlsSecurityScheme]
// --8<-- [start:OAuthFlows]
// Defines the configuration for the supported OAuth 2.0 flows.
message OAuthFlows {
oneof flow {
@ -564,15 +629,15 @@ message OAuthFlows {
AuthorizationCodeOAuthFlow authorization_code = 1;
// Configuration for the OAuth Client Credentials flow.
ClientCredentialsOAuthFlow client_credentials = 2;
// Deprecated: Use Authorization Code + PKCE instead.
ImplicitOAuthFlow implicit = 3 [deprecated = true];
// Deprecated: Use Authorization Code + PKCE or Device Code.
PasswordOAuthFlow password = 4 [deprecated = true];
// Configuration for the OAuth Device Code flow.
DeviceCodeOAuthFlow device_code = 5;
}
}
// --8<-- [end:OAuthFlows]
// --8<-- [start:AuthorizationCodeOAuthFlow]
// Defines configuration details for the OAuth 2.0 Authorization Code flow.
message AuthorizationCodeOAuthFlow {
// The authorization URL to be used for this flow.
@ -587,7 +652,9 @@ message AuthorizationCodeOAuthFlow {
// PKCE should always be used for public clients and is recommended for all clients.
bool pkce_required = 5;
}
// --8<-- [end:AuthorizationCodeOAuthFlow]
// --8<-- [start:ClientCredentialsOAuthFlow]
// Defines configuration details for the OAuth 2.0 Client Credentials flow.
message ClientCredentialsOAuthFlow {
// The token URL to be used for this flow.
@ -597,8 +664,9 @@ message ClientCredentialsOAuthFlow {
// The available scopes for the OAuth2 security scheme.
map<string, string> scopes = 3 [(google.api.field_behavior) = REQUIRED];
}
// --8<-- [end:ClientCredentialsOAuthFlow]
// Deprecated: Use Authorization Code + PKCE instead.
// DEPRECATED
message ImplicitOAuthFlow {
// The authorization URL to be used for this flow. This MUST be in the
// form of a URL. The OAuth2 standard requires the use of TLS
@ -611,7 +679,7 @@ message ImplicitOAuthFlow {
map<string, string> scopes = 3;
}
// Deprecated: Use Authorization Code + PKCE or Device Code.
// DEPRECATED
message PasswordOAuthFlow {
// The token URL to be used for this flow. This MUST be in the form of a URL.
// The OAuth2 standard requires the use of TLS.
@ -624,6 +692,7 @@ message PasswordOAuthFlow {
map<string, string> scopes = 3;
}
// --8<-- [start:DeviceCodeOAuthFlow]
// Defines configuration details for the OAuth 2.0 Device Code flow (RFC 8628).
// This flow is designed for input-constrained devices such as IoT devices,
// and CLI tools where the user authenticates on a separate device.
@ -637,143 +706,169 @@ message DeviceCodeOAuthFlow {
// The available scopes for the OAuth2 security scheme.
map<string, string> scopes = 4 [(google.api.field_behavior) = REQUIRED];
}
// --8<-- [end:DeviceCodeOAuthFlow]
///////////// Request Messages ///////////
// --8<-- [start:SendMessageRequest]
// Represents a request for the `SendMessage` method.
message SendMessageRequest {
// Optional. Tenant ID, provided as a path parameter.
string tenant = 1;
// Optional tenant, provided as a path parameter.
string tenant = 4;
// The message to send to the agent.
Message message = 2 [(google.api.field_behavior) = REQUIRED];
Message message = 1 [(google.api.field_behavior) = REQUIRED];
// Configuration for the send request.
SendMessageConfiguration configuration = 3;
SendMessageConfiguration configuration = 2;
// A flexible key-value map for passing additional context or parameters.
google.protobuf.Struct metadata = 4;
google.protobuf.Struct metadata = 3;
}
// --8<-- [end:SendMessageRequest]
// --8<-- [start:GetTaskRequest]
// Represents a request for the `GetTask` method.
message GetTaskRequest {
// Optional. Tenant ID, provided as a path parameter.
string tenant = 1;
// The resource ID of the task to retrieve.
string id = 2 [(google.api.field_behavior) = REQUIRED];
// Optional tenant, provided as a path parameter.
string tenant = 3;
// The resource id of the task.
string id = 1 [(google.api.field_behavior) = REQUIRED];
// The maximum number of most recent messages from the task's history to retrieve. An
// unset value means the client does not impose any limit. A value of zero is
// a request to not include any messages. The server MUST NOT return more
// messages than the provided value, but MAY apply a lower limit.
optional int32 history_length = 3;
optional int32 history_length = 2;
}
// --8<-- [end:GetTaskRequest]
// --8<-- [start:ListTasksRequest]
// Parameters for listing tasks with optional filtering criteria.
message ListTasksRequest {
// Tenant ID, provided as a path parameter.
string tenant = 1;
// Optional tenant, provided as a path parameter.
string tenant = 9;
// Filter tasks by context ID to get tasks from a specific conversation or session.
string context_id = 2;
string context_id = 1;
// Filter tasks by their current status state.
TaskState status = 3;
// The maximum number of tasks to return. The service may return fewer than this value.
// If unspecified, at most 50 tasks will be returned.
// The minimum value is 1.
// The maximum value is 100.
optional int32 page_size = 4;
// A page token, received from a previous `ListTasks` call.
// `ListTasksResponse.next_page_token`.
// Provide this to retrieve the subsequent page.
string page_token = 5;
TaskState status = 2;
// Maximum number of tasks to return. Must be between 1 and 100.
// Defaults to 50 if not specified.
optional int32 page_size = 3;
// Token for pagination. Use the next_page_token from a previous ListTasksResponse.
string page_token = 4;
// The maximum number of messages to include in each task's history.
optional int32 history_length = 6;
optional int32 history_length = 5;
// Filter tasks which have a status updated after the provided timestamp in ISO 8601 format (e.g., "2023-10-27T10:00:00Z").
// Only tasks with a status timestamp time greater than or equal to this value will be returned.
google.protobuf.Timestamp status_timestamp_after = 7;
google.protobuf.Timestamp status_timestamp_after = 6;
// Whether to include artifacts in the returned tasks.
// Defaults to false to reduce payload size.
optional bool include_artifacts = 8;
optional bool include_artifacts = 7;
}
// --8<-- [end:ListTasksRequest]
// Result object for `ListTasks` method containing an array of tasks and pagination information.
// --8<-- [start:ListTasksResponse]
// Result object for tasks/list method containing an array of tasks and pagination information.
message ListTasksResponse {
// Array of tasks matching the specified criteria.
repeated Task tasks = 1 [(google.api.field_behavior) = REQUIRED];
// A token to retrieve the next page of results, or empty if there are no more results in the list.
// Token for retrieving the next page. Empty string if no more results.
string next_page_token = 2 [(google.api.field_behavior) = REQUIRED];
// The page size used for this response.
// The size of page requested.
int32 page_size = 3 [(google.api.field_behavior) = REQUIRED];
// Total number of tasks available (before pagination).
int32 total_size = 4 [(google.api.field_behavior) = REQUIRED];
}
// --8<-- [end:ListTasksResponse]
// --8<-- [start:CancelTaskRequest]
// Represents a request for the `CancelTask` method.
message CancelTaskRequest {
// Optional. Tenant ID, provided as a path parameter.
string tenant = 1;
// The resource ID of the task to cancel.
string id = 2 [(google.api.field_behavior) = REQUIRED];
// A flexible key-value map for passing additional context or parameters.
google.protobuf.Struct metadata = 3;
// Optional tenant, provided as a path parameter.
string tenant = 2;
// The resource id of the task to cancel.
string id = 1 [(google.api.field_behavior) = REQUIRED];
}
// --8<-- [end:CancelTaskRequest]
// Represents a request for the `GetTaskPushNotificationConfig` method.
// --8<-- [start:GetTaskPushNotificationConfigRequest]
message GetTaskPushNotificationConfigRequest {
// Optional. Tenant ID, provided as a path parameter.
string tenant = 1;
// The parent task resource ID.
string task_id = 2 [(google.api.field_behavior) = REQUIRED];
// The resource ID of the configuration to retrieve.
string id = 3 [(google.api.field_behavior) = REQUIRED];
// Optional tenant, provided as a path parameter.
string tenant = 2;
// The parent task resource id.
string task_id = 3 [(google.api.field_behavior) = REQUIRED];
// The resource id of the config to retrieve.
string id = 1 [(google.api.field_behavior) = REQUIRED];
}
// --8<-- [end:GetTaskPushNotificationConfigRequest]
// --8<-- [start:DeleteTaskPushNotificationConfigRequest]
// Represents a request for the `DeleteTaskPushNotificationConfig` method.
message DeleteTaskPushNotificationConfigRequest {
// Optional. Tenant ID, provided as a path parameter.
string tenant = 1;
// The parent task resource ID.
string task_id = 2 [(google.api.field_behavior) = REQUIRED];
// The resource ID of the configuration to delete.
string id = 3 [(google.api.field_behavior) = REQUIRED];
// Optional tenant, provided as a path parameter.
string tenant = 2;
// The parent task resource id.
string task_id = 3 [(google.api.field_behavior) = REQUIRED];
// The resource id of the config to delete.
string id = 1 [(google.api.field_behavior) = REQUIRED];
}
// --8<-- [end:DeleteTaskPushNotificationConfigRequest]
// Represents a request for the `SubscribeToTask` method.
message SubscribeToTaskRequest {
// Optional. Tenant ID, provided as a path parameter.
string tenant = 1;
// The resource ID of the task to subscribe to.
string id = 2 [(google.api.field_behavior) = REQUIRED];
}
// Represents a request for the `ListTaskPushNotificationConfigs` method.
message ListTaskPushNotificationConfigsRequest {
// Optional. Tenant ID, provided as a path parameter.
// --8<-- [start:CreateTaskPushNotificationConfigRequest]
// Represents a request for the `CreateTaskPushNotificationConfig` method.
message CreateTaskPushNotificationConfigRequest {
reserved 3;
// Optional tenant, provided as a path parameter.
string tenant = 4;
// The parent task resource ID.
// The parent task resource id.
string task_id = 1 [(google.api.field_behavior) = REQUIRED];
// The ID for the new config.
string config_id = 2 [(google.api.field_behavior) = REQUIRED];
// The configuration to create.
PushNotificationConfig config = 5 [(google.api.field_behavior) = REQUIRED];
}
// --8<-- [end:CreateTaskPushNotificationConfigRequest]
// --8<-- [start:SubscribeToTaskRequest]
message SubscribeToTaskRequest {
// Optional tenant, provided as a path parameter.
string tenant = 2;
// The resource id of the task to subscribe to.
string id = 1 [(google.api.field_behavior) = REQUIRED];
}
// --8<-- [end:SubscribeToTaskRequest]
// --8<-- [start:ListTaskPushNotificationConfigRequest]
message ListTaskPushNotificationConfigRequest {
// Optional tenant, provided as a path parameter.
string tenant = 4;
// The parent task resource id.
string task_id = 1 [(google.api.field_behavior) = REQUIRED];
// The maximum number of configurations to return.
int32 page_size = 2;
// A page token received from a previous `ListTaskPushNotificationConfigsRequest` call.
// A page token received from a previous ListTaskPushNotificationConfigRequest call.
string page_token = 3;
}
// --8<-- [end:ListTaskPushNotificationConfigRequest]
// Represents a request for the `GetExtendedAgentCard` method.
// --8<-- [start:GetExtendedAgentCardRequest]
message GetExtendedAgentCardRequest {
// Optional. Tenant ID, provided as a path parameter.
// Optional tenant, provided as a path parameter.
string tenant = 1;
}
// --8<-- [end:GetExtendedAgentCardRequest]
// Represents the response for the `SendMessage` method.
//////// Response Messages ///////////
// --8<-- [start:SendMessageResponse]
message SendMessageResponse {
// The payload of the response.
oneof payload {
// The task created or updated by the message.
Task task = 1;
// A message from the agent.
Message message = 2;
}
}
// --8<-- [end:SendMessageResponse]
// --8<-- [start:StreamResponse]
// A wrapper object used in streaming operations to encapsulate different types of response data.
message StreamResponse {
// The payload of the stream response.
oneof payload {
// A Task object containing the current state of the task.
Task task = 1;
@ -785,12 +880,16 @@ message StreamResponse {
TaskArtifactUpdateEvent artifact_update = 4;
}
}
// --8<-- [end:StreamResponse]
// Represents a successful response for the `ListTaskPushNotificationConfigs`
// --8<-- [start:ListTaskPushNotificationConfigResponse]
// Represents a successful response for the `ListTaskPushNotificationConfig`
// method.
message ListTaskPushNotificationConfigsResponse {
message ListTaskPushNotificationConfigResponse {
// The list of push notification configurations.
repeated TaskPushNotificationConfig configs = 1;
// A token to retrieve the next page of results, or empty if there are no more results in the list.
// A token, which can be sent as `page_token` to retrieve the next page.
// If this field is omitted, there are no subsequent pages.
string next_page_token = 2;
}
// --8<-- [end:ListTaskPushNotificationConfigResponse]

View File

@ -7,7 +7,6 @@ lint:
# Indicates that all the default rules should be used.
# See https://buf.build/docs/lint/rules for more details.
- STANDARD
- COMMENTS
except:
- PACKAGE_DIRECTORY_MATCH
- RPC_REQUEST_RESPONSE_UNIQUE