# Getting Started

A2A (Agent-to-Agent) agents are intelligent, autonomous applications that can process messages, handle document operations, and communicate with other agents in the Health Universe platform. They're perfect for building AI-powered healthcare workflows, document processing pipelines, and clinical decision support tools.

This guide will walk you through creating, testing, and deploying your first A2A agent.

## Prerequisites

Before you begin, make sure you have:

* Python 3.10+ installed
* A [GitHub account](/overview/building-apps-in-health-universe/getting-started-with-health-universe/create-a-github-account.md)
* A [Health Universe account](/overview/building-apps-in-health-universe/getting-started-with-health-universe/create-a-health-universe-account.md) with [GitHub linked](/overview/building-apps-in-health-universe/getting-started-with-health-universe/link-your-github-account-to-your-health-universe-account.md)
* Basic familiarity with Python and async programming

## Installation

### 1. Create a New Repository

Create a new GitHub repository for your agent:

```bash
git clone https://github.com/<your_username>/<your_repo_name>.git
cd <your_repo_name>
```

### 2. Set Up Your Environment

Create and activate a virtual environment:

```bash
python -m venv .env
source .env/bin/activate  # On Windows: .env\Scripts\activate
```

### 3. Install the SDK

Install the Health Universe A2A SDK:

```bash
pip install health-universe-a2a
```

## Creating Your First Agent

### Basic Agent Structure

Create a file called `main.py` with your first agent:

```python
from health_universe_a2a import Agent, AgentContext
import json

class MedicalDataAnalyzer(Agent):
    def get_agent_name(self) -> str:
        return "Medical Data Analyzer"

    def get_agent_description(self) -> str:
        return "Analyzes medical datasets and generates clinical insights"

    async def process_message(self, message: str, context: AgentContext) -> str:
        # Update progress for the user
        await context.update_progress("Starting analysis...", 0.1)

        # List documents in the thread
        docs = await context.document_client.list_documents()
        
        if not docs:
            return "No documents found to analyze. Please upload medical data files."

        # Process each document
        results = []
        for i, doc in enumerate(docs):
            await context.update_progress(
                f"Analyzing {doc.name}...", 
                (i + 1) / len(docs) * 0.8
            )
            
            # Read document content
            try:
                content = await context.document_client.download_text(doc.id)
                # Simple analysis example
                word_count = len(content.split())
                results.append({
                    "document": doc.name,
                    "word_count": word_count,
                    "size_bytes": len(content.encode('utf-8'))
                })
            except Exception as e:
                results.append({
                    "document": doc.name,
                    "error": f"Could not process: {str(e)}"
                })

        # Write results as a new document
        await context.document_client.write(
            "Analysis Results",
            json.dumps(results, indent=2),
            filename="analysis_results.json"
        )

        await context.update_progress("Analysis complete!", 1.0)
        
        return f"Successfully analyzed {len(docs)} documents. Results saved to analysis_results.json"

if __name__ == "__main__":
    agent = MedicalDataAnalyzer()
    agent.serve()
```

### Understanding the Agent Structure

Every A2A agent must implement three core methods:

* **`get_agent_name()`**: Returns the display name for your agent
* **`get_agent_description()`**: Describes what your agent does
* **`process_message()`**: The main logic that processes user requests

The `AgentContext` provides access to:

* **Document operations**: `context.document_client` for reading/writing files
* **Progress updates**: `context.update_progress()` for user feedback
* **Inter-agent communication**: `context.call_agent()` for calling other agents

## Testing Locally

### 1. Create Test Data

Create a local test environment:

```bash
mkdir test_data
mkdir test_data/source
echo "Patient ID: 12345, Age: 45, Diagnosis: Hypertension" > test_data/source/patient_data.txt
```

### 2. Local Testing Script

Create `test_local.py`:

```python
import asyncio
from health_universe_a2a.local import create_local_context
from main import MedicalDataAnalyzer

async def test_agent():
    # Create local context
    context = create_local_context("./test_data")
    
    # Create agent instance
    agent = MedicalDataAnalyzer()
    
    # Test the agent
    result = await agent.process_message(
        "Please analyze the medical data", 
        context
    )
    
    print("Agent result:", result)

if __name__ == "__main__":
    asyncio.run(test_agent())
```

Run the test:

```bash
python test_local.py
```

### 3. Test the Server

You can also test the full HTTP server locally:

```bash
python main.py
```

Then visit:

* <http://localhost:8000> - Main endpoint
* <http://localhost:8000/.well-known/agent-card.json> - Agent metadata
* <http://localhost:8000/health> - Health check

## Creating Requirements File

Generate your dependencies:

```bash
pip freeze > requirements.txt
```

Your `requirements.txt` should include at minimum:

```txt
health-universe-a2a>=0.2.0
```

## Deploying to Health Universe

### 1. Prepare Your Repository

Ensure your repository contains:

* `main.py` - Your agent code
* `requirements.txt` - Dependencies
* `README.md` - Documentation (optional but recommended)

### 2. Commit and Push

```bash
git add .
git commit -m "Initial A2A agent implementation"
git push origin main
```

### 3. Deploy on Health Universe

1. Go to your [Health Universe workspace](/overview/building-apps-in-health-universe/creating-a-workspace.md)
2. Click **"Deploy a new app"**
3. Fill in the deployment form:
   * **GitHub Repository**: Select your repository
   * **App Name**: "Medical Data Analyzer"
   * **Description**: "Analyzes medical datasets and generates clinical insights"
   * **Runtime**: Select **FastAPI** → **Add to Navigator**
   * **Main File**: `main.py`
4. Click **"Deploy App"**

### 4. Monitor Deployment

Watch the build logs to ensure your agent deploys successfully. Once complete, your agent will be available in Health Universe Navigator.

## Using Your Agent in Navigator

1. **Open Navigator** in your Health Universe workspace
2. **Upload documents** to a thread (medical data files, reports, etc.)
3. **Search for your agent** by name or description
4. **Click "Use Tool"** to run your agent
5. **Monitor progress** as your agent processes the documents
6. **View results** in the artifacts panel when complete

## Next Steps

Now that you have a basic agent working, you can:

* [Learn about document operations](/overview/building-apps-in-health-universe/developing-your-health-universe-app/working-with-a2a-agents/document-operations.md) for advanced file handling
* [Explore inter-agent communication](/overview/building-apps-in-health-universe/developing-your-health-universe-app/working-with-a2a-agents/inter-agent-communication.md) for building agent workflows
* [Add validation](https://github.com/Health-Universe/docs/blob/main/building-apps-in-health-universe/developing-your-health-universe-app/working-with-a2a-agents/validation-and-error-handling.md) to make your agents more robust
* [Integrate with LLMs](https://github.com/Health-Universe/docs/blob/main/deploying-your-app-to-health-universe/connecting-to-an-llm.md) for AI-powered analysis

## Common Issues

**Agent not appearing in Navigator?**

* Ensure you selected "Add to Navigator" during deployment
* Check that your agent implements all required methods

**Local testing not working?**

* Make sure you activated your virtual environment
* Verify the `test_data/source/` directory exists with sample files

**Deployment fails?**

* Check your `requirements.txt` includes `health-universe-a2a`
* Ensure your `main.py` file is in the repository root
* Review the build logs for specific error messages

**Need help?**

* Check the [Health Universe documentation](https://docs.healthuniverse.com)
* Review the [SDK source code](https://github.com/Health-Universe/health-universe-a2a-sdk) for examples


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.healthuniverse.com/overview/building-apps-in-health-universe/developing-your-health-universe-app/working-with-a2a-agents/getting-started.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.