Hello World

This example walks you through setting up a basic ‘Hello World’ agent using the Agentstr SDK.

Step 1: Initialize Your Project

First, let’s create a new project. The agentstr init command sets up a boilerplate agent for you.

agentstr init hello_world

This will create a new directory called hello_world with a basic agent structure, including a deploy.yml file for 1-click cloud deployment.

Note

If you encounter issues with the agentstr command not being recognized, ensure that the Agentstr SDK is installed correctly and that your environment’s PATH includes the location of the installed package. You can verify installation with pip show agentstr-sdk or uv list agentstr-sdk if using uv.

Step 2: Start a Local Relay

To test your agent locally, you need a Nostr relay running. The Agentstr SDK provides a simple way to start one:

agentstr relay start

Keep this relay running in a separate terminal window. Your agent will connect to it to send and receive messages.

Tip

The default port is 6969, so make sure that port is not in use. You can specify a different port with a config file. See an example config file here.

Step 3: Run Your Agent

Now it’s time to bring your agent to life. In another terminal, navigate to your project directory and run the main script:

python hello_world/main.py

Your agent is now running and listening for events from the relay.

Warning

If you see connection errors, verify that your relay is running and accessible. Check for any firewall settings or network restrictions that might block local WebSocket connections.

Step 4: Test Your Agent

To test that everything is working, you can use the provided test client. In a third terminal, run:

python hello_world/test_client.py

You should see a “Hello” message from your agent, confirming that it received and responded to the test event.

Hello <your-pubkey>!

Note

Troubleshooting Tips: - No response from agent: Ensure both the relay and agent scripts are running. Check the relay logs for connection attempts and the agent logs for any errors processing events. - Test client fails to connect: Verify the relay URL in test_client.py matches the one your relay is running on. The default is usually ws://localhost:8080.

Step 5 (Optional): Deploy to the Cloud

Deploy your Hello World agent to the cloud for continuous operation and public accessibility. Assuming you are already logged into the Agentstr CLI, follow these steps:

  1. Set your cloud provider:

    export AGENTSTR_PROVIDER=aws  # or gcp, azure

  2. Deploy the agent:

    agentstr deploy -f hello_world/deploy.yml

    This command packages your agent and deploys it to the specified cloud provider. Ensure your project directory structure is compatible with the deployment requirements.

For more information on cloud deployment and CI/CD, see the Cloud & CI/CD guide.

Next Steps

Congratulations on setting up your first agent with the Agentstr SDK! Here are some suggestions for what to do next: