agentconnect.core package

Core components for the AgentConnect framework.

This module provides the foundational building blocks for agent-based systems in the decentralized AgentConnect framework, including:

  • Base Agent: Abstract base class for all agent implementations

  • Message Handling: Secure, signed message creation and verification

  • Agent Identity: Decentralized identity and cryptographic verification

  • Capability Registry: Dynamic discovery of agent capabilities

  • Type System: Rich type definitions for the entire framework

The core module focuses on establishing the foundation for decentralized agent interaction without imposing centralized control structures.

class Message(id, sender_id, receiver_id, content, message_type, timestamp, metadata=<factory>, protocol_version=ProtocolVersion.V1_0, signature=None)

Bases: object

Message class for agent communication.

This class represents messages exchanged between agents, with support for content, metadata, and cryptographic signatures for verification.

Parameters:
id

Unique identifier for the message

sender_id

ID of the sending agent

receiver_id

ID of the receiving agent

content

Message content

message_type

Type of message (text, command, response, etc.)

timestamp

When the message was created

metadata

Additional information about the message

protocol_version

Version of the communication protocol

signature

Cryptographic signature for verification

classmethod create(sender_id, receiver_id, content, sender_identity, message_type=MessageType.TEXT, metadata=None)

Create a new signed message.

Parameters:

  • sender_id (str) – ID of the sending agent

  • receiver_id (str) – ID of the receiving agent

  • content (str) – Message content

  • sender_identity (AgentIdentity) – Identity of the sending agent

  • message_type (MessageType) – Type of message being sent

  • metadata (Optional[Dict]) – Additional information about the message

Return type:

Message

Returns:

A signed Message object

Raises:

ValueError – If the sender identity doesn’t have a private key for signing

protocol_version: ProtocolVersion = '1.0'
sign(identity)

Sign message with sender’s private key.

Parameters:

identity (AgentIdentity) – The identity containing the private key for signing

Raises:

ValueError – If the identity doesn’t have a private key

Return type:

None

signature: Optional[str] = None
verify(sender_identity)

Verify message signature using sender’s public key.

Parameters:

sender_identity (AgentIdentity) – The identity containing the public key for verification

Return type:

bool

Returns:

True if the signature is valid, False otherwise

Raises:

SecurityError – If the sender identity is not verified

id: str
sender_id: str
receiver_id: str
content: str
message_type: MessageType
timestamp: datetime
metadata: Dict
class AgentType(value)

Bases: str, Enum

Types of agents in the system.

This enum defines the different types of agents that can exist in the system.

HUMAN = 'human'
AI = 'ai'
class Capability(name, description, input_schema=None, output_schema=None, version='1.0')

Bases: object

Capability definition for agents.

This class defines a capability that an agent can provide, including its name, description, and input/output schemas.

Parameters:
name

Name of the capability

description

Description of what the capability does

input_schema

Schema for the input data

output_schema

Schema for the output data

version

Version of the capability

input_schema: Optional[Dict[str, str]] = None
output_schema: Optional[Dict[str, str]] = None
version: str = '1.0'
name: str
description: str
class AgentIdentity(did, public_key, private_key=None, verification_status=VerificationStatus.PENDING, created_at=<factory>, metadata=<factory>)

Bases: object

Decentralized Identity for Agents.

This class provides identity management for agents, including cryptographic keys for signing and verification.

Parameters:
did

Decentralized Identifier

public_key

Public key for verification

private_key

Private key for signing (optional)

verification_status

Status of identity verification

created_at

When the identity was created

metadata

Additional information about the identity

classmethod create_key_based()

Create a new key-based identity for an agent.

This method generates a new RSA key pair and creates a key-based decentralized identifier (DID) for the agent.

Return type:

AgentIdentity

Returns:

A new AgentIdentity with generated keys and DID

classmethod from_dict(data)

Create identity from dictionary format.

Parameters:

data (Dict) – Dictionary containing identity data

Return type:

AgentIdentity

Returns:

AgentIdentity instance created from the dictionary

private_key: Optional[str] = None
sign_message(message)

Sign a message using the private key.

Parameters:

message (str) – The message to sign

Return type:

str

Returns:

Base64-encoded signature

Raises:

ValueError – If the private key is not available

to_dict()

Convert identity to dictionary format.

Return type:

Dict

Returns:

Dictionary representation of the identity

verification_status: VerificationStatus = 'pending'
verify_signature(message, signature)

Verify a message signature using the public key.

Parameters:

  • message (str) – The message that was signed

  • signature (str) – The base64-encoded signature to verify

Return type:

bool

Returns:

True if the signature is valid, False otherwise

did: str
public_key: str
created_at: datetime
metadata: Dict
class InteractionMode(value)

Bases: str, Enum

Supported interaction modes between agents.

This enum defines the different ways agents can interact with each other.

HUMAN_TO_AGENT = 'human_to_agent'
AGENT_TO_AGENT = 'agent_to_agent'
class ModelProvider(value)

Bases: str, Enum

Supported AI model providers.

This enum defines the supported model providers for AI agents.

OPENAI = 'openai'
ANTHROPIC = 'anthropic'
GROQ = 'groq'
GOOGLE = 'google'
class ModelName(value)

Bases: str, Enum

Supported model names for each provider.

This enum defines the specific model names available for each provider.

classmethod get_default_for_provider(provider)

Get the default model for a given provider.

Parameters:

provider (ModelProvider) – The model provider to get the default model for

Return type:

ModelName

Returns:

The default model name for the provider

Raises:

ValueError – If no default model is defined for the provider

GPT4_5_PREVIEW = 'gpt-4.5-preview-2025-02-27'
GPT4_1 = 'gpt-4.1'
GPT4_1_MINI = 'gpt-4.1-mini'
GPT4O = 'gpt-4o'
GPT4O_MINI = 'gpt-4o-mini'
O1 = 'o1'
O1_MINI = 'o1-mini'
O3 = 'o3'
O3_MINI = 'o3-mini'
O4_MINI = 'o4-mini'
CLAUDE_3_7_SONNET = 'claude-3-7-sonnet-latest'
CLAUDE_3_5_SONNET = 'claude-3-5-sonnet-latest'
CLAUDE_3_5_HAIKU = 'claude-3-5-haiku-latest'
CLAUDE_3_OPUS = 'claude-3-opus-latest'
CLAUDE_3_SONNET = 'claude-3-sonnet-20240229'
CLAUDE_3_HAIKU = 'claude-3-haiku-20240307'
LLAMA33_70B_VTL = 'llama-3.3-70b-versatile'
LLAMA3_1_8B_INSTANT = 'llama-3.1-8b-instant'
LLAMA_GUARD3_8B = 'llama-guard-3-8b'
LLAMA3_70B = 'llama3-70b-8192'
LLAMA3_8B = 'llama3-8b-8192'
MIXTRAL = 'mixtral-8x7b-32768'
GEMMA2_90B = 'gemma2-9b-it'
GEMINI2_5_PRO = 'gemini-2.5-pro'
GEMINI2_5_FLASH = 'gemini-2.5-flash'
GEMINI2_5_FLASH_LITE = 'gemini-2.5-flash-lite'
GEMINI2_FLASH = 'gemini-2.0-flash'
GEMINI2_FLASH_LITE = 'gemini-2.0-flash-lite'
GEMINI2_PRO_EXP = 'gemini-2.0-pro-exp-02-05'
GEMINI2_FLASH_THINKING_EXP = 'gemini-2.0-flash-thinking-exp-01-21'
class AgentProfile(**data)

Bases: BaseModel

Comprehensive profile for an agent.

This class provides a complete profile of an agent, including its capabilities, skills, and other metadata needed for discovery and interaction.

Parameters:
agent_id

Unique identifier for the agent

agent_type

Type of agent (human, AI)

name

Name of the agent

summary

Brief summary of the agent’s purpose

description

Detailed description of the agent

version

Version of the agent

documentation_url

URL to the agent’s documentation

organization

Organization or entity providing the agent (e.g., ‘Acme Corp’, ‘did:org:123’). Using a verifiable ID is recommended for robustness.

developer

Individual or team that developed the agent (e.g., ‘Alice’, ‘did:person:abc’). Using a verifiable ID is recommended.

url

Endpoint URL for the agent

auth_schemes

List of supported authentication schemes

default_input_modes

List of supported input modes

default_output_modes

List of supported output modes

capabilities

List of capabilities the agent provides

skills

List of skills the agent possesses

examples

Example inputs/outputs or use cases

tags

Keywords for filtering

payment_address

Agent’s primary wallet address for receiving payments

custom_metadata

Additional custom metadata about the agent

reputation_score

Optional reputation score (excluded from serialization)

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

agent_id: str
agent_type: AgentType
name: Optional[str]
summary: Optional[str]
description: Optional[str]
version: Optional[str]
documentation_url: Optional[str]
organization: Optional[str]
developer: Optional[str]
url: Optional[str]
auth_schemes: List[str]
default_input_modes: List[str]
default_output_modes: List[str]
capabilities: List[Capability]
skills: List[Skill]
examples: List[str]
tags: List[str]
payment_address: Optional[str]
custom_metadata: Dict[str, Any]
reputation_score: Optional[float]
class Skill(**data)

Bases: BaseModel

Skill model for agents.

This class defines a skill that an agent can possess, including its name and description.

Parameters:

  • name (str)

  • description (str | None)

name

Name of the skill

description

Optional description of what the skill entails

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str
description: Optional[str]
class AgentRegistry(vector_search_config=None)

Bases: object

Central registry for agent registration and discovery.

This class provides methods for registering agents, discovering agents by capability, and verifying agent identities.

Parameters:

vector_search_config (VectorSearchSettings | Dict[str, Any] | None)

async ensure_initialized()

Wait until the core registry initialization is complete.

async get_agent_type(agent_id)

Get the type of an agent.

Parameters:

agent_id (str) – ID of the agent

Return type:

AgentType

Returns:

Type of the agent

Raises:

KeyError – If the agent is not found

async get_all_agents()

Get a list of all agents registered in the system.

Return type:

List[AgentRegistration]

Returns:

List of all agent registrations

async get_all_capabilities()

Get a list of all unique capability names registered in the system.

Return type:

List[str]

Returns:

List of all capability names

async get_by_capability(capability_name, limit=10, similarity_threshold=0.1)

Find agents by capability name.

Parameters:

  • capability_name (str) – Name of the capability to search for

  • limit (int) – Maximum number of results to return (default: 10)

  • similarity_threshold (float) – Minimum similarity score for semantic fallback search (default: 0.1)

Return type:

List[AgentRegistration]

Returns:

List of agent registrations with the specified capability

async get_by_capability_semantic(capability_description, limit=10, similarity_threshold=0.1, filters=None)

Find agents by capability description using semantic search.

Parameters:

  • capability_description (str) – Description of the capability to search for

  • limit (int) – Maximum number of results to return (default: 10)

  • similarity_threshold (float) – Minimum similarity score to include in results (default: 0.1)

  • filters (Optional[Dict[str, List[str]]]) – Optional dictionary for filtering. Keys can include “tags”, “organization”, “developer”, “default_input_modes”, “default_output_modes”, “auth_schemes”. Values are lists of strings to match for the respective key.

Return type:

List[Tuple[AgentRegistration, float]]

Returns:

List of tuples containing agent registrations and similarity scores

async get_by_interaction_mode(mode)

Find agents by interaction mode.

Parameters:

mode (InteractionMode) – Interaction mode to search for

Return type:

List[AgentRegistration]

Returns:

List of agent registrations with the specified interaction mode

async get_by_organization(organization)

Find agents by organization.

Parameters:

organization (str) – ID/name of the organization

Return type:

List[AgentRegistration]

Returns:

List of agent registrations in the specified organization

async get_by_owner(owner_id)

Find agents by owner.

Parameters:

owner_id (str) – ID of the owner (now using developer field)

Return type:

List[AgentRegistration]

Returns:

List of agent registrations owned by the specified owner

async get_registration(agent_id)

Get agent registration details.

Parameters:

agent_id (str) – ID of the agent

Return type:

Optional[AgentRegistration]

Returns:

Agent registration if found, None otherwise

async get_verified_agents()

Get all verified agents.

Return type:

List[AgentRegistration]

Returns:

List of verified agent registrations

async register(registration)

Register a new agent with verification. Waits for initialization first.

Parameters:

registration (AgentRegistration) – Registration information for the agent

Return type:

bool

Returns:

True if registration was successful, False otherwise

async unregister(agent_id)

Remove agent from registry.

Parameters:

agent_id (str) – ID of the agent to unregister

Return type:

bool

Returns:

True if unregistration was successful, False otherwise

async update_registration(agent_id, updates)

Update agent registration details.

Parameters:

  • agent_id (str) – ID of the agent to update

  • updates (Dict) – Dictionary of updates to apply

Return type:

Optional[AgentRegistration]

Returns:

Updated agent registration if successful, None otherwise

property vector_search_settings: VectorSearchSettings

Get the vector search settings as a Pydantic model.

async verify_agent(agent_id)

Verify an agent’s identity.

Parameters:

agent_id (str) – ID of the agent to verify

Return type:

bool

Returns:

True if verification was successful, False otherwise

async verify_owner(agent_id, owner_id)

Verify if a user owns an agent.

Parameters:

  • agent_id (str) – ID of the agent

  • owner_id (str) – ID of the owner (now using developer field)

Return type:

bool

Returns:

True if the user owns the agent, False otherwise

class BaseAgent(agent_id, identity, interaction_modes, profile, enable_payments=False, wallet_data_dir=None)

Bases: ABC

Abstract base class for all agents in the system.

This class defines the core functionality that all agents must implement, including identity verification, message handling, and conversation management.

Parameters:
agent_id

Unique identifier for the agent

identity

Agent’s decentralized identity

profile

Comprehensive profile for the agent

capabilities

List of agent capabilities

message_queue

Queue for incoming messages

message_history

History of messages sent and received

is_running

Whether the agent is currently running

registry

Reference to the agent registry

hub

Reference to the communication hub

active_conversations

Dictionary of active conversations

cooldown_until

Timestamp when cooldown ends

pending_requests

Dictionary of pending requests

enable_payments

Whether payment capabilities are enabled

wallet_provider

Wallet provider for blockchain transactions

agent_kit

AgentKit instance for blockchain actions

async can_receive_message(sender_id)

Check if the agent can receive a message from the sender.

Parameters:

sender_id (str) – ID of the sending agent

Return type:

bool

Returns:

True if the agent can receive a message, False otherwise

async can_send_message(receiver_id)

Check if agent can send message.

Parameters:

receiver_id (str) – ID of the receiving agent

Return type:

bool

Returns:

True if the agent can send a message, False otherwise

end_conversation(other_agent_id)

End conversation with another agent.

Parameters:

other_agent_id (str) – ID of the other agent in the conversation

Return type:

None

is_in_cooldown()

Check if agent is in cooldown.

Return type:

bool

Returns:

True if the agent is in cooldown, False otherwise

async join_network(network)

Join an agent network for agent-to-agent communication.

Note: Join_network is not required for MVP The registry handles all agent discovery and communication We keep it for future network functionality

Parameters:

network – The network to join

Returns:

True if successfully joined, False otherwise

property payments_enabled: bool

Check if payment capabilities are enabled and available.

Returns:

True if payment capabilities are enabled and available, False otherwise

abstractmethod async process_message(message)

Process incoming message - must be implemented by subclasses.

This method processes an incoming message and generates a response. It must be implemented by subclasses to provide agent-specific message processing logic.

Parameters:

message (Message) – The message to process

Return type:

Optional[Message]

Returns:

Optional response message

async receive_message(message)

Receive and queue a message.

Parameters:

message (Message) – The message to receive

reset_cooldown()

Reset the cooldown state of the agent.

This method resets the agent’s cooldown state, allowing it to send and receive messages immediately.

Return type:

None

async run()

Start the agent’s message processing loop.

This method starts the agent’s main processing loop, which continuously processes messages from the message queue until the agent is stopped.

async send_message(receiver_id, content, message_type=MessageType.TEXT, metadata=None)

Create and send a message through the hub.

Parameters:

  • receiver_id (str) – ID of the receiving agent

  • content (str) – Message content

  • message_type (MessageType) – Type of message being sent

  • metadata (Optional[Dict]) – Additional information about the message

Return type:

Message

Returns:

The sent message

Raises:
set_cooldown(duration)

Set a cooldown period for the agent.

Parameters:

duration (int) – Cooldown duration in seconds

Return type:

None

async stop()

Stop the agent and cleanup resources.

This method stops the agent’s processing loop, ends all active conversations, and cleans up resources such as wallet providers and message queues.

Return type:

None

Returns:

None

async verify_identity()

Verify agent’s DID and update verification status.

This method verifies the agent’s decentralized identifier and updates the verification status accordingly.

Return type:

bool

Returns:

True if the identity is verified, False otherwise

Raises:

SecurityError – If identity verification fails

Subpackages

Submodules

On this page
Edit on GitHub