A2A (Agent-to-Agent)¶

This module provides the core functionality for agent-to-agent communication in the Agentstr SDK. It includes base classes and utilities for defining agent capabilities, handling messages, and managing agent interactions within the Nostr network.

pydantic model agentstr.a2a.Skill[source]

Bases: BaseModel

Represents a specific capability or service that an agent can perform.

A Skill defines a discrete unit of functionality that an agent can provide to other agents or users. Skills are the building blocks of an agent’s service offerings and can be priced individually to create a market for agent capabilities.

name

A unique identifier for the skill that should be descriptive and concise. This name is used for referencing the skill in agent interactions.

Type:: str

description

A detailed explanation of what the skill does, including: - The specific functionality provided - How to use the skill - Any limitations or prerequisites - Expected inputs and outputs

Type:: str

satoshis

The price in satoshis for using this skill. This allows agents to: - Set different prices for different capabilities - Create premium services - Implement usage-based pricing If None, the skill is either free or priced at the agent’s base rate.

Type:: int, optional

Show JSON schema

{
   "title": "Skill",
   "description": "Represents a specific capability or service that an agent can perform.\n\nA Skill defines a discrete unit of functionality that an agent can provide to other\nagents or users. Skills are the building blocks of an agent's service offerings and\ncan be priced individually to create a market for agent capabilities.\n\nAttributes:\n    name (str): A unique identifier for the skill that should be descriptive and\n        concise. This name is used for referencing the skill in agent interactions.\n    description (str): A detailed explanation of what the skill does, including:\n        - The specific functionality provided\n        - How to use the skill\n        - Any limitations or prerequisites\n        - Expected inputs and outputs\n    satoshis (int, optional): The price in satoshis for using this skill. This allows\n        agents to:\n        - Set different prices for different capabilities\n        - Create premium services\n        - Implement usage-based pricing\n        If None, the skill is either free or priced at the agent's base rate.",
   "type": "object",
   "properties": {
      "name": {
         "title": "Name",
         "type": "string"
      },
      "description": {
         "title": "Description",
         "type": "string"
      },
      "satoshis": {
         "anyOf": [
            {
               "type": "integer"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Satoshis"
      }
   },
   "required": [
      "name",
      "description"
   ]
}

Fields:

description (str)
name (str)
satoshis (int | None)

field name: str [Required]

field description: str [Required]

field satoshis: int | None = None

pydantic model agentstr.a2a.AgentCard[source]

Bases: BaseModel

Represents an agent’s profile and capabilities in the Nostr network.

An AgentCard is the public identity and capabilities card for an agent in the Nostr network. It contains essential information about the agent’s services, pricing, and communication endpoints.

name

A human-readable name for the agent. This is the agent’s display name.

Type:: str

description

A detailed description of the agent’s purpose, capabilities, and intended use cases.

Type:: str

skills

A list of specific skills or services that the agent can perform. Each skill is represented by a Skill model.

Type:: list[Skill]

satoshis

The base price in satoshis for interacting with the agent. If None, the agent may have free services or use skill-specific pricing.

Type:: int, optional

nostr_pubkey

The agent’s Nostr public key. This is used for identifying and communicating with the agent on the Nostr network.

Type:: str

nostr_relays

A list of Nostr relay URLs that the agent uses for communication. These relays are where the agent publishes and receives messages.

Type:: list[str]

Show JSON schema

{
   "title": "AgentCard",
   "description": "Represents an agent's profile and capabilities in the Nostr network.\n\nAn AgentCard is the public identity and capabilities card for an agent in the Nostr\nnetwork. It contains essential information about the agent's services, pricing,\nand communication endpoints.\n\nAttributes:\n    name (str): A human-readable name for the agent. This is the agent's display name.\n    description (str): A detailed description of the agent's purpose, capabilities,\n        and intended use cases.\n    skills (list[Skill]): A list of specific skills or services that the agent can perform.\n        Each skill is represented by a Skill model.\n    satoshis (int, optional): The base price in satoshis for interacting with the agent.\n        If None, the agent may have free services or use skill-specific pricing.\n    nostr_pubkey (str): The agent's Nostr public key. This is used for identifying\n        and communicating with the agent on the Nostr network.\n    nostr_relays (list[str]): A list of Nostr relay URLs that the agent uses for\n        communication. These relays are where the agent publishes and receives messages.",
   "type": "object",
   "properties": {
      "name": {
         "title": "Name",
         "type": "string"
      },
      "description": {
         "title": "Description",
         "type": "string"
      },
      "skills": {
         "default": [],
         "items": {
            "$ref": "#/$defs/Skill"
         },
         "title": "Skills",
         "type": "array"
      },
      "satoshis": {
         "anyOf": [
            {
               "type": "integer"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Satoshis"
      },
      "nostr_pubkey": {
         "title": "Nostr Pubkey",
         "type": "string"
      },
      "nostr_relays": {
         "default": [],
         "items": {
            "type": "string"
         },
         "title": "Nostr Relays",
         "type": "array"
      }
   },
   "$defs": {
      "Skill": {
         "description": "Represents a specific capability or service that an agent can perform.\n\nA Skill defines a discrete unit of functionality that an agent can provide to other\nagents or users. Skills are the building blocks of an agent's service offerings and\ncan be priced individually to create a market for agent capabilities.\n\nAttributes:\n    name (str): A unique identifier for the skill that should be descriptive and\n        concise. This name is used for referencing the skill in agent interactions.\n    description (str): A detailed explanation of what the skill does, including:\n        - The specific functionality provided\n        - How to use the skill\n        - Any limitations or prerequisites\n        - Expected inputs and outputs\n    satoshis (int, optional): The price in satoshis for using this skill. This allows\n        agents to:\n        - Set different prices for different capabilities\n        - Create premium services\n        - Implement usage-based pricing\n        If None, the skill is either free or priced at the agent's base rate.",
         "properties": {
            "name": {
               "title": "Name",
               "type": "string"
            },
            "description": {
               "title": "Description",
               "type": "string"
            },
            "satoshis": {
               "anyOf": [
                  {
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Satoshis"
            }
         },
         "required": [
            "name",
            "description"
         ],
         "title": "Skill",
         "type": "object"
      }
   },
   "required": [
      "name",
      "description",
      "nostr_pubkey"
   ]
}

Fields:

description (str)
name (str)
nostr_pubkey (str)
nostr_relays (list[str])
satoshis (int | None)
skills (list[agentstr.a2a.Skill])

field name: str [Required]

field description: str [Required]

field skills: list[Skill] = []

field satoshis: int | None = None

field nostr_pubkey: str [Required]

field nostr_relays: list[str] = []

pydantic model agentstr.a2a.ChatInput[source]

Bases: BaseModel

Represents input data for an agent-to-agent chat interaction.

messages

A list of messages in the conversation.

Type:: list[str]

thread_id

The ID of the conversation thread. Defaults to None.

Type:: str, optional

extra_inputs

Additional metadata or parameters for the chat.

Type:: dict[str, Any]

Show JSON schema

{
   "title": "ChatInput",
   "description": "Represents input data for an agent-to-agent chat interaction.\n\nAttributes:\n    messages (list[str]): A list of messages in the conversation.\n    thread_id (str, optional): The ID of the conversation thread. Defaults to None.\n    extra_inputs (dict[str, Any]): Additional metadata or parameters for the chat.",
   "type": "object",
   "properties": {
      "messages": {
         "items": {
            "type": "string"
         },
         "title": "Messages",
         "type": "array"
      },
      "thread_id": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Thread Id"
      },
      "extra_inputs": {
         "additionalProperties": true,
         "default": {},
         "title": "Extra Inputs",
         "type": "object"
      }
   },
   "required": [
      "messages"
   ]
}

Fields:

extra_inputs (dict[str, Any])
messages (list[str])
thread_id (str | None)

field messages: list[str] [Required]

field thread_id: str | None = None

field extra_inputs: dict[str, Any] = {}

pydantic model agentstr.a2a.PriceHandlerResponse[source]

Bases: BaseModel

Response model for the price handler.

can_handle: Whether the agent can handle the request

cost_sats: Total cost in satoshis (0 if free or not applicable)

user_message: Friendly message to show the user about the action to be taken

skills_used: List of skills that would be used, if any

Show JSON schema

{
   "title": "PriceHandlerResponse",
   "description": "Response model for the price handler.\n\nAttributes:\n    can_handle: Whether the agent can handle the request\n    cost_sats: Total cost in satoshis (0 if free or not applicable)\n    user_message: Friendly message to show the user about the action to be taken\n    skills_used: List of skills that would be used, if any",
   "type": "object",
   "properties": {
      "can_handle": {
         "title": "Can Handle",
         "type": "boolean"
      },
      "cost_sats": {
         "default": 0,
         "title": "Cost Sats",
         "type": "integer"
      },
      "user_message": {
         "default": "",
         "title": "User Message",
         "type": "string"
      },
      "skills_used": {
         "default": [],
         "items": {
            "type": "string"
         },
         "title": "Skills Used",
         "type": "array"
      }
   },
   "required": [
      "can_handle"
   ]
}

Fields:

can_handle (bool)
cost_sats (int)
skills_used (list[str])
user_message (str)

field can_handle: bool [Required]

field cost_sats: int = 0

field user_message: str = ''

field skills_used: list[str] = []

class agentstr.a2a.PriceHandler(llm_callable: Callable[[str], str])[source]

Bases: object

__init__(llm_callable: Callable[[str], str])[source]

async handle(user_message: str, agent_card: AgentCard, thread_id: str | None = None) → PriceHandlerResponse[source]

Determine if an agent can handle a user’s request and calculate the cost.

This function uses an LLM to analyze whether the agent’s skills match the user’s request and returns the cost in satoshis if the agent can handle it.

Parameters:

user_message – The user’s request message.
agent_card – The agent’s model card.
thread_id – Optional thread ID for conversation context.

Returns:

PriceHandlerResponse

agentstr.a2a.default_price_handler(base_url: str | None = None, api_key: str | None = None, model_name: str | None = None) → PriceHandler[source]: Create a default price handler using the given LLM parameters.