Custom Framework Agent¶

This guide demonstrates how to integrate a custom agentic framework with the Agentstr SDK, using the Google ADK as an example. By following these steps, you can bring your own framework and connect it to the Nostr ecosystem for advanced agent functionality.

Tip

This example is more advanced and requires knowledge of other agentic frameworks. If you are new to agent development, we recommend starting with the Hello World guide.

Step 1: Initialize Your Project¶

Start by initializing a new project if you haven’t already:

agentstr init custom_framework_agent

This sets up a custom_framework_agent directory with the basic structure for your agent.

Step 2: Update Environment Variables¶

Update the custom_framework_agent/.env file with your LLM information and NWC connection string.

LLM_BASE_URL=https://api.openai.com/v1
LLM_API_KEY=your-api-key
LLM_MODEL_NAME=gpt-3.5-turbo
NWC_CONN_STR=nostr+walletconnect://<your-nwc-connection-string>
MCP_SERVER_PUBKEY=<your-mcp-server-public-key>

Note

NWC_CONN_STR is the default environment variable for NWCRelay to enable Nostr Wallet Connect. You can override this by passing a connection string directly to the NostrClient constructor.
LLM_BASE_URL, LLM_API_KEY, and LLM_MODEL_NAME are the default environment variables for AgentstrAgent to enable LLM integration. You can override these by passing them directly to the agent constructor.
Replace <your-mcp-server-key> with the actual public key of a Nostr MCP server. If you’re testing locally, ensure an MCP server is also running locally.
You can follow the Creating an MCP Server guide to set up Nostr MCP server.

Step 3: Modify the Agent Code¶

Open the main.py file in your project to review and customize the agent setup for Google ADK:

"""Custom Framework agent (Google ADK) - Bring your own framework."""

from dotenv import load_dotenv
load_dotenv()

import asyncio
import os

from google.adk.agents import Agent
from google.adk.models.lite_llm import LiteLlm
from agentstr import NostrAgent, AgentCard, NostrAgentServer, NostrMCPClient
from agentstr.mcp.providers.google import to_google_tools
from agentstr.agents.providers.google import google_chat_generator

# Note: the NWC_CONN_STR environment variable is used by default for payment processing
if os.getenv("NWC_CONN_STR") is None:
    raise ValueError("NWC_CONN_STR environment variable is not set")

# Note: make sure MCP_SERVER_PUBKEY is set
if os.getenv("MCP_SERVER_PUBKEY") is None:
    raise ValueError("MCP_SERVER_PUBKEY environment variable is not set")


async def main():
    # Create Nostr MCP client
    nostr_mcp_client = NostrMCPClient(mcp_pubkey=os.getenv("MCP_SERVER_PUBKEY"))

    # Convert tools to Google ADK tools
    google_tools = await to_google_tools(nostr_mcp_client)

    # Define Google agent
    agent = Agent(
        name="google_agent",
        model=LiteLlm(
            model=os.getenv("LLM_MODEL_NAME"),
            api_base=os.getenv("LLM_BASE_URL").rstrip('/v1'),
            api_key=os.getenv("LLM_API_KEY")
        ),
        instruction="You are a helpful assistant.",
        tools=google_tools,
    )

    # Define agent callable
    chat_generator = google_chat_generator(agent, [nostr_mcp_client])

    # Create Nostr Agent
    nostr_agent = NostrAgent(
        agent_card=AgentCard(
            name="Google Agent", 
            description="A helpful assistant", 
            skills=await nostr_mcp_client.get_skills(), 
            satoshis=0,
        ), 
        chat_generator=chat_generator
    )

    # Create Nostr Agent Server
    server = NostrAgentServer(nostr_mcp_client=nostr_mcp_client,
                              nostr_agent=nostr_agent)

    # Start server
    await server.start()


# Run the server
if __name__ == "__main__":
    asyncio.run(main())

Customize the agent name, description, and skills as needed. You can also modify the payment amount (satoshis) for using the agent.

Step 4: Update Test Client¶

Update custom_framework_agent/test_client.py to interact with your tool-enabled agent.

from dotenv import load_dotenv
load_dotenv()

import os
from agentstr import NostrClient, PrivateKey

agent_pubkey = os.getenv("NOSTR_PUBKEY")

async def chat():
    client = NostrClient(private_key=PrivateKey().bech32())
    response = await client.send_direct_message_and_receive_response(
        agent_pubkey,
        "What's 59 + 88232?",
    )
    print(response.message)

if __name__ == "__main__":
    import asyncio
    asyncio.run(chat())

Step 5: Start a Local Relay¶

Start a local Nostr relay for testing:

agentstr relay start

Keep this running in a separate terminal.

Step 6: Run Your Custom Framework Agent¶

Run your custom framework agent with tool calling capabilities:

python custom_framework_agent/main.py

Step 7: Test Your Agent¶

Use the test client to interact with your agent and see the tool listing response:

python custom_framework_agent/test_client.py

You should see a response indicating the answer to a math question. If you check the MCP Server logs, you’ll see that the addition tool was called by the agent.

Feel free to play around with the test client to ask the agent additional questions. Just note that any premium tools will require a Lightning payment.

Note

If you encounter connection issues with the MCP server, ensure the server is running and accessible. Refer to troubleshooting tips in the Hello World guide for general connectivity issues.

Step 8 (Optional): Deploy to the Cloud¶

Deploy your Custom Framework Agent to the cloud for continuous operation. Assuming you are already logged into the Agentstr CLI, follow these steps:

Set your cloud provider:

export AGENTSTR_PROVIDER=aws  # or gcp, azure

Deploy the agent:
```
agentstr deploy -f custom_framework_agent/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¶

More Framework Providers: Check out Custom Agent Frameworks for more information on other agentic framework providers.
Dive into the API: Learn more about the capabilities of the SDK by exploring the Module Reference documentation.
Explore the Cookbook: Check out the Agentstr Cookbook for more advanced use cases and examples.