Hello-world

Quickstart: Running Your First Agent ("Hello World")

This guide will walk you through the complete end-to-end process of using the Nexus platform. You will learn how to find an agent, run it locally using Docker, and communicate with it using a simple Python script.

We'll use the "Hello World" agent as our example.

This example demonstrates how to:

Fetch an Agent Card from Nexus.
Pull the agent’s Docker image.
Run it locally in a container.
Use the A2A Client to send and receive messages.

Prerequisites

Before you begin, make sure you have the following installed and running on your system:

Python (3.8 or newer).
Docker Desktop (or the Docker daemon). Make sure it's running.
The necessary Python libraries. You can install them with pip:

Workflow Overview

Step 1: Query Nexus API to fetch the agent card.
Step 2: Pull and start the agent’s Docker image.
Step 3: Initialize an A2AClient with the agent card.
Step 4: Send a message and receive the response.

Step 1: Fetch the Agent Details (Agent Card & Docker Image)

To run an agent, you first need two key pieces of information: its Agent Card and its Docker Image name. You can get these in two ways: programmatically via our API or by downloading them manually from the agent's repository.d.

What is an Agent Card?

An Agent Card is a JSON file that acts as a digital passport for the agent. It tells you everything you need to know: who the agent is, what skills it has, and critically, what Docker image to use and how to communicate with it.

Via API (Recommended)
Manual Download

This is the standard, programmatic way to fetch agent details. You make a single API call to get everything you need.

Call the API Endpoint: Use a tool like cURL to query the Nexus API for the agent you want.

url = "https://hncugknujacihsgyrvtd.supabase.co/functions/v1/get-agents-card?query=agent-name"
payload = ""
headers = {
'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImhuY3Vna251amFjaWhzZ3lydnRkIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NTUyNzExNzIsImV4cCI6MjA3MDg0NzEMn0.X6JDJveHFO__gWtff1dzQievPimVFRZTimtuIVD7W6c',
'Content-Type': 'application/json',
'api-key': 'your api key',
'user-id': 'your user id'
}

response = requests.request("POST", url, headers=headers, data=payload)
data = response.json()
agent_card = data['data'][0]['agent_card']
agent_card_validate = AgentCard.model_validate(agent_card)
# Docker image
image = data['data'][0]['docker_image']

Save the Agent Card: The API will return a JSON object. Inside this object, you'll find the agent_card and the docker_image. Copy the entire agent_card JSON object and save it to a new file named agent_card.json. You'll need this for your Python script. The docker_image will be something like ashu4u/helloworld:latest.

You are now ready to proceed to Step 2.

This method is useful if you are browsing the Nexus repository directly and want to quickly test an agent.

Navigate to the My Agent's Page : In My Agent's Page you see your agents, click the hello-world agents (Login first to see your installed agents).
Go to the Agent Card : Find the agent_card.json file and download it to your project directory.
Copy the Docker Image Name: On the same page, find the Docker Image name. It will look something like this:

ashu4u/helloworld:latest

Copy this name, as you will need it in the next step.

You are now ready to proceed to Step 2.

Step 2: Run the Agent with Docker

Now that you have the Docker image name, you can run the agent on your local machine.

Pull the Image: Download the agent's image from the Docker registry.

# Pull the image
client.images.pull(image)
container = client.containers.run(
    image,
    detach = True,
    ports={'9999/tcp':9999}
    
)

# Wait for the container to initialize (e.g., 5 seconds)
time.sleep(5)

Run the Container: Start the agent. We'll map port 9999 on your local machine to the port inside the container, allowing your script to talk to it.

Your agent is now running locally and listening for requests on localhost:9999!

Step 3: Communicate with the Agent

With the agent running, you can now write a Python script to interact with it. Your script will use the agent_card.json file to initialize the A2AClient, which handles all the communication details for you.

Create a Python file (e.g., run_agent.py) and add the following code:

# The client uses the Agent Card to know how to communicate with the agent.
async with httpx.AsyncClient() as httpx_client:
    client = A2AClient(httpx_client=httpx_client, agent_card=agent_card_validate)
    print("A2A Client initialized.")
    # Prepare your message
    message_payload = {
        'message': {
            'role': 'user',
            'parts': [
                {'kind': 'text', 'text': 'Hello World!'}
            ],
        },
    }

Step 4: Send a message and receive the response.

request = SendMessageRequest(
            id=str(uuid4()), params=MessageSendParams(**send_message_payload)
    )
    response = await client.send_message(request)
    print(response.model_dump(mode='json', exclude_none=True))
    # --8<-- [end:send_message]
    # --8<-- [start:send_message_streaming]
    streaming_request = SendStreamingMessageRequest(
        id=str(uuid4()), params=MessageSendParams(**send_message_payload)
    )
    stream_response = client.send_message_streaming(streaming_request)
    async for chunk in stream_response:
        print(chunk.model_dump(mode='json', exclude_none=True))

Once you're finished, it's good practice to stop the Docker container to free up resources.

container.stop()

Congratulations! You have successfully run and interacted with your first agent from the Nexus platform.

Full Example Code (Automated - Recommended)

Below is the complete working code that directly uses the Agent Card and pulls the Docker Image through the Docker SDK in Python:

import logging

import time
from typing import Any
from uuid import uuid4
import docker
import os
import json

import requests
import httpx

from a2a.client import A2ACardResolver, A2AClient
from a2a.types import (
    AgentCard,
    MessageSendParams,
    SendMessageRequest,
    SendStreamingMessageRequest,
)


async def main() -> None:
    logging.basicConfig(level=logging.INFO)
    logger = logging.getLogger(__name__)

    url = "https://hncugknujacihsgyrvtd.supabase.co/functions/v1/get-agents-card?query=agent-name"
    payload = ""
    headers = {
    'Authorization': 'Bearer    eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImhuY3Vna251amFjaWhzZ3lydnRkIiwicm9sZSI6ImFub24iLCJpYXQiOjE3   NTUyNzExNzIsImV4cCI6MjA3MDg0NzEMn0.X6JDJveHFO__gWtff1dzQievPimVFRZTimtuIVD7W6c',
    'Content-Type': 'application/json',
    'api-key': 'your api key',
    'user-id': 'your user id'
    }

    response = requests.request("POST", url, headers=headers, data=payload)
    data = response.json()
    agent_card = data['data'][0]['agent_card']
    agent_card_validate = AgentCard.model_validate(agent_card)
    # Docker image
    image = data['data'][0]['docker_image']

    logger.info(f'Docker image pulled : {image}')

    # Pull the image
    client.images.pull(image)
    container = client.containers.run(
        image,
        detach = True,
        ports={'9999/tcp':9999}

    )

    # Wait for the container to initialize (e.g., 5 seconds)
    time.sleep(5)
    logger.info(f'Agent running at {container.name}')

    async with httpx.AsyncClient() as httpx_client:

        try:
            logger.info('Successfully fetched public agent card:')

            logger.info(
                '\nUsing PUBLIC agent card for client initialization (default).'
            )

        except Exception as e:
            logger.error(
                f'Critical error fetching public agent card: {e}', exc_info=True
            )
            raise RuntimeError(
                'Failed to fetch the public agent card. Cannot continue.'
            ) from e

        # --8<-- [start:send_message]
        client = A2AClient(
            httpx_client=httpx_client, agent_card=agent_card_validate
        )
        logger.info('A2AClient initialized.')

        send_message_payload: dict[str, Any] = {
            'message': {
                'role': 'user',
                'parts': [
                    {'kind': 'text', 'text': 'how much is 10 USD in INR?'}
                ],
                'messageId': uuid4().hex,
            },
        }
        request = SendMessageRequest(
            id=str(uuid4()), params=MessageSendParams(**send_message_payload)
        )

        response = await client.send_message(request)
        print(response.model_dump(mode='json', exclude_none=True))
        # --8<-- [end:send_message]

        # --8<-- [start:send_message_streaming]

        streaming_request = SendStreamingMessageRequest(
            id=str(uuid4()), params=MessageSendParams(**send_message_payload)
        )

        stream_response = client.send_message_streaming(streaming_request)

        async for chunk in stream_response:
            print(chunk.model_dump(mode='json', exclude_none=True))
        # --8<-- [end:send_message_streaming]

        container.stop()

if __name__ == '__main__':
    import asyncio

    asyncio.run(main())

Now that your agent is set up, check out the integration guides below to use agents with different methods:

Quickstart: Running Your First Agent ("Hello World")​

Prerequisites​

Workflow Overview​

Step 1: Fetch the Agent Details (Agent Card & Docker Image)​

Step 2: Run the Agent with Docker​

Step 3: Communicate with the Agent​

Step 4: Send a message and receive the response.​

Full Example Code (Automated - Recommended)​