docs: update README.md and CONTRIBUTING.md (#567)

# Description

We are updating the repository's foundational documentation to
streamline the onboarding experience for new contributors and ensure
consistent code quality.

### Summary of Updates:
1. **README.md:** Added a 2-step **Quick Start** guide for running the
`helloworld` sample and a **Repository Structure** directory table.

2. **CONTRIBUTING.md:** Fully detailed the local development workflow
using `uv`. Added step-by-step commands for running linting (`ruff`),
type checking (`mypy`/`pyright`), and test coverage (`pytest`).

> Note: As of now mypy, pyright and pytest are added as suggestion only.

3. **Tooling Configurations:** Bumped `ruff` line-length to 100 in
`.ruff.toml` and add static analysis tools (`mypy`, `pyright`, `pytest`)
in `pyproject.toml`.

Author: msampathkumar

.ruff.toml

@@ -6,7 +6,7 @@
 # https://google.github.io/styleguide/pyguide.html
 #
 
-line-length = 80 # Google Style Guide §3.2: 80 columns
+line-length = 100 # Relaxed Google Style limit (of 80) for modern IDEs and wider screens
 indent-width = 4 # Google Style Guide §3.4: 4 spaces
 
 target-version = "py310" # Minimum Python version
@@ -91,6 +91,7 @@ exclude = [
     ".svn",
     ".tox",
     ".venv",
+    "uv.lock",
     "__pypackages__",
     "_build",
     "buck-out",

CONTRIBUTING.md

@@ -1,41 +1,100 @@
-# How to contribute
+# Contributing to Agent2Agent (A2A) Samples
 
-We'd love to accept your patches and contributions to this project.
+We'd love to accept your patches and contributions to this project. This repository contains code samples and demos demonstrating the [Agent2Agent (A2A) Protocol](https://goo.gle/a2a).
 
-## Before you begin
+## Table of Contents
 
-### Sign our Contributor License Agreement
+- [Before You Begin](#before-you-begin)
+- [Contribution Process](#contribution-process)
+- [Development Workflow](#development-workflow)
 
-Contributions to this project must be accompanied by a
-[Contributor License Agreement](https://cla.developers.google.com/about) (CLA).
-You (or your employer) retain the copyright to your contribution; this simply
-gives us permission to use and redistribute your contributions as part of the
-project.
+## Before You Begin
 
-If you or your current employer have already signed the Google CLA (even if it
-was for a different project), you probably don't need to do it again.
+### Prerequisites (for Python agents)
 
-Visit <https://cla.developers.google.com/> to see your current agreements or to
-sign a new one.
+Ensure your local environment meets the following requirements before starting development:
 
-### Review our community guidelines
+- **Python**: Version 3.12 or higher (3.13+ recommended for agent development).
+- **Package Manager**: [uv](https://docs.astral.sh/uv/) is required for managing dependencies and workspaces.
 
-This project follows
-[Google's Open Source Community Guidelines](https://opensource.google/conduct/).
+### Local Setup
 
-## Contribution process
+1. **Fork and Clone**: [Fork this repository](https://github.com/a2aproject/a2a-samples/fork) to your GitHub account, then clone your fork locally:
+   ```bash
+   git clone https://github.com/<your-username>/a2a-samples.git
+   cd a2a-samples
+   ```
 
-### Code reviews
+2. **Install Dependencies**: Ensure your workspace dependencies are installed:
+   ```bash
+   uv sync
+   ```
 
-All submissions, including submissions by project members, require review. We
-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.
+3. **Create a Branch**: Create a feature branch for your changes:
+   ```bash
+   git checkout -b feature/my-new-sample
+   ```
 
----
+## Contribution Process
 
-## For Google Employees
+### Issues and Proposals
 
-Complete the following steps to register your GitHub account and be added as a contributor to this repository.
+Before undertaking significant work, check the [issues page](https://github.com/a2aproject/a2a-samples/issues) to see if your feature or bug fix is already being discussed. If not, open a new issue to discuss your proposed changes.
 
-1. Register your GitHub account at [go/GitHub](http://go/github)
+### Code Reviews
+
+All submissions, including submissions by project members, require review using GitHub pull requests. Consult [GitHub Help](https://help.github.com/articles/about-pull-requests/) for more information on using pull requests.
+
+## Development Workflow
+
+We use `uv` for dependency management, linting, formatting, type checking, and testing. Make sure all checks pass before submitting a pull request.
+
+### Formatting and Linting
+
+All code **must** be formatted and linted using `ruff` tool. Check its [.ruff.toml](.ruff.toml) configuration for more details.
+
+To check and automatically fix linting errors across the workspace:
+
+```bash
+uv run ruff check --fix
+```
+
+To format the codebase:
+
+```bash
+uv run ruff format
+```
+
+#### Checking a Specific Sample
+
+If you are working on a single agent sample (e.g., `helloworld`), you can target it directly:
+
+```bash
+uv run ruff check --fix --config .ruff.toml samples/python/agents/helloworld/
+uv run ruff format --config .ruff.toml samples/python/agents/helloworld/
+```
+
+Alternatively, you can use [./format.sh](./format.sh) for formatting Python and Notebook files.
+
+### Type Checking
+
+Use static type checks to improve your code readability and maintainability. Run the following commands from the workspace root or target directory:
+
+```bash
+uv run mypy samples/python
+uv run pyright samples/python
+```
+
+### Testing
+
+Build and run your tests using `pytest`. Use `--verbose` for more detailed output.
+
+```bash
+uv run pytest --verbose
+```
+
+To run tests for a specific agent sample or extension:
+
+```bash
+uv run pytest tests/python/agents/<sample-name>/
+```

README.md

@@ -43,28 +43,85 @@
   </details>
 </div>
 
-This repository contains code samples and demos which use the [Agent2Agent (A2A) Protocol](https://goo.gle/a2a).
+Welcome to the official code samples and demonstrations for the [Agent2Agent (A2A) Protocol](https://goo.gle/a2a).
 
-## Related Repositories
+We are thrilled to have you here! Whether you are exploring multi-agent architectures for the first time or building advanced interoperable agent networks, this repository provides simple, inspiring, and accessible learning resources to accelerate your development.
+
+## Why Agent2Agent?
+
+In a world of diverse AI frameworks and ecosystems, agents need a common language to communicate, collaborate, and delegate tasks securely. The A2A protocol establishes a standardized, open standard for multi-agent interoperability.
+
+Our samples demonstrate how easily complex multi-agent problems can be solved across different languages and host applications.
+
+## Quick Start
+
+Get up and running immediately by launching a Helloworld agent and communicating with it via our Python CLI host.
+
+1. **Start the Agent Server**:
+   Open a terminal and start the Helloworld agent server:
+
+   ```bash
+   cd samples/python/agents/helloworld
+   uv run .
+   ```
 
-- [A2A](https://github.com/a2aproject/A2A) - A2A Specification and documentation.
-- [a2a-python](https://github.com/a2aproject/a2a-python) - A2A Python SDK.
-- [a2a-inspector](https://github.com/a2aproject/a2a-inspector) - UI tool for inspecting A2A enabled agents.
+2. **Run the Host Client**:
+   Open a second terminal and run the CLI client to send a task to the agent:
+
+   ```bash
+   cd samples/python/agents/helloworld
+   uv run test_client.py
+   ```
+
+## Repository Structure
+
+The repository is organized into several key directories by language:
+
+| Directory | Description |
+| --- | --- |
+| [samples](/samples) | Core A2A samples organized by programming language. |
+| [samples/python](/samples/python) | Demonstrates Python agent implementations using the A2A Python SDK. |
+| [samples/go](/samples/go) | Demonstrates Go agent implementations using the A2A Go SDK. |
+| [samples/dotnet](/samples/dotnet) | Demonstrates C# agent implementations using the A2A .NET SDK. |
+| [samples/java](/samples/java) | Demonstrates Java agent implementations using the A2A Java SDK. |
+| [samples/js](/samples/js) | Demonstrates Node.js agent implementations using the A2A JavaScript SDK. |
 
 ## Contributing
 
-Contributions welcome! See the [Contributing Guide](CONTRIBUTING.md).
+We welcome and encourage contributions of all skill levels! If you have an idea for a new sample, a bug fix, or a documentation improvement, please check out our [Contributing Guide](CONTRIBUTING.md).
 
-## Getting help
+## Getting Help
 
-Please use the [issues page](https://github.com/a2aproject/a2a-samples/issues) to provide suggestions, feedback or submit a bug report.
+We are dedicated to providing a welcoming and supportive community. If you have questions, feedback, or run into any issues, please reach out on our [issues page](https://github.com/a2aproject/a2a-samples/issues).
 
-## Disclaimer
+## Related Repositories
 
-This repository itself is not an officially supported Google product. The code in this repository is for demonstrative purposes only.
+| Repository | Category | Description |
+| --- | --- | --- |
+| [A2A](https://github.com/a2aproject/A2A) | Core Specification | A2A Specification and documentation. |
+| [a2a-inspector](https://github.com/a2aproject/a2a-inspector) | Tooling | UI tool for inspecting A2A enabled agents. |
+| [a2a-tck](https://github.com/a2aproject/a2a-tck) | Testing | Test suite for validating A2A Protocol compliance. |
+| [a2a-itk](https://github.com/a2aproject/a2a-itk) | Testing | Toolkit to verify compatibility across different A2A SDK implementations and versions using multi-hop traversal model and varied transport protocols. |
+| [a2a-python](https://github.com/a2aproject/a2a-python) | SDK (Python) | Official Python SDK for A2A. |
+| [a2a-go](https://github.com/a2aproject/a2a-go) | SDK (Go) | Official Go SDK for A2A. |
+| [a2a-java](https://github.com/a2aproject/a2a-java) | SDK (Java) | Official Java SDK for A2A. |
+| [a2a-js](https://github.com/a2aproject/a2a-js) | SDK (JavaScript) | Official Node.js/JavaScript SDK for A2A. |
+| [a2a-dotnet](https://github.com/a2aproject/a2a-dotnet) | SDK (C#/.NET) | Official C#/.NET SDK for A2A. |
+| [a2a-rs](https://github.com/a2aproject/a2a-rs) | SDK (Rust) | Official Rust SDK for A2A. |
+
+## Disclaimer
 
-Important: The sample code provided is for demonstration purposes and illustrates the mechanics of the Agent-to-Agent (A2A) protocol. When building production applications, it is critical to treat any agent operating outside of your direct control as a potentially untrusted entity.
+**Important:** The sample code provided is for demonstration purposes and illustrates the mechanics of the
+Agent-to-Agent (A2A) protocol. When building production applications, it is critical to treat any agent
+operating outside of your direct control as a potentially untrusted entity.
 
-All data received from an external agent—including but not limited to its AgentCard, messages, artifacts, and task statuses—should be handled as untrusted input. For example, a malicious agent could provide an AgentCard containing crafted data in its fields (e.g., description, name, skills.description). If this data is used without sanitization to construct prompts for a Large Language Model (LLM), it could expose your application to prompt injection attacks.  Failure to properly validate and sanitize this data before use can introduce security vulnerabilities into your application.
+All data received from an external agent—including but not limited to its AgentCard, messages,
+artifacts, and task statuses—should be handled as untrusted input. For example, a malicious agent
+could provide an AgentCard containing crafted data in its fields (e.g., description, name,
+skills.description). If this data is used without sanitization to construct prompts for a Large
+Language Model (LLM), it could expose your application to prompt injection attacks. Failure to
+properly validate and sanitize this data before use can introduce security vulnerabilities into
+your application.
 
-Developers are responsible for implementing appropriate security measures, such as input validation and secure handling of credentials to protect their systems and users.
+> Developers are responsible for implementing appropriate security measures, such as input validation
+> and secure handling of credentials to protect their systems and users.

pyproject.toml

@@ -6,6 +6,13 @@ readme = "README.md"
 requires-python = ">=3.12"
 dependencies = []
 
+[dependency-groups]
+dev = [
+    "mypy>=1.19.1",
+    "pyright>=1.1.409",
+    "pytest>=9.0.2",
+]
+
 [tool.uv.workspace]
 members = [
     "samples/python/agents/crewai",