Skip to main content

LangChain Tools for HCS-10 Agents

This guide details the LangChain StructuredTool classes provided by the @hashgraphonline/standards-agent-kit. These tools are the primary way to enable your AI agent, built with LangChain, to interact on the Hedera Hashgraph using the HCS-10 OpenConvAI Standard for communication and discovery.

Source Code: standards-agent-kit/src/tools/.

Prerequisites​

  1. Initialized HCS10Client: You need an instance of the kit's HCS10Client, configured with the Hedera credentials of the initial operator account. See the Core Client Guide.
  2. Agent Identity Management: Your application must manage which agent identity (accountId, privateKey) the HCS10Client is currently operating as.
  3. Connection State Management (for Connection Tools): While HCS-10 allows reconstructing state from topics, these tools require an application-level state manager for efficiency.

Agent Identity State (Essential)​

The underlying HCS10Client needs to know which Hedera account (accountId and privateKey) it should act as.

  • Initial Setup - The client identity is first set when you create the HCS10Client instance with operator credentials.

  • Creating New Agents - When you register a new agent with RegisterAgentTool, it will automatically:

    • Generate a new Hedera account with its own accountId and privateKey
    • Return these credentials in its JSON response
    • Switch the client's active identity by calling hcs10Client.setClient()

  • Managing Multiple Identities - For applications that handle multiple agents, you can programmatically switch between identities by calling hcs10Client.setClient() with the appropriate credentials.

Your application needs to securely store and manage the private keys returned by RegisterAgentTool if you intend to reuse those agent identities later. Do not hardcode private keys. Use environment variables or secure secret management solutions.

Connection State: HCS-10 Standard vs. Tool Implementation​

Understanding how connection state is handled is crucial for using these tools effectively.

  • HCS-10 Standard: The standard itself is designed such that the state of any connection (e.g., the specific connectionTopicId shared between Agent A and Agent B) can be determined by querying Agent A's public outbound topic (where it records connection initiations and confirmations) and potentially Agent B's inbound/outbound topics. This allows for stateless operation but requires potentially complex and slow on-chain lookups.

  • Kit Tool Implementation (Design Choice for Convenience): For developer convenience and simpler agent prompting, the connection-related tools in this kit (InitiateConnectionTool, ConnectionTool, ListConnectionsTool, SendMessageToConnectionTool, CheckMessagesTool) are designed to rely on an application-level state manager.

    • They expect your application to provide an object/class instance (passed as stateManager in the constructor) that adheres to the IStateManager interface and can quickly:
      • Store details of pending/active connections (mapping a local ID or target ID to the connectionTopicId, status, etc.).
      • Retrieve a connection's connectionTopicId based on an identifier (like a list index or target account ID).
      • Track the last checked message timestamp for polling (CheckMessagesTool).
    • This design avoids the need for the agent or the tools to perform complex, asynchronous HCS topic lookups during a conversational turn, making agent interactions smoother and faster.

  • State Manager Options:

    • Recommended: The kit provides OpenConvaiState (located in src/state/open-convai-state.ts), an in-memory implementation of IStateManager. This is suitable for getting started quickly and for many common use cases.
    • Custom: For more complex needs (e.g., persistence, different storage mechanisms), you can implement your own state manager class adhering to the IStateManager interface and pass your custom instance to the tools.

  • OpenConvaiState Usage: The examples use OpenConvaiState. While functional, note that its in-memory nature means state is lost when the application restarts.

  • Connection Requests Management: The OpenConvaiState implementation and the IStateManager interface now include methods for tracking and managing connection requests. This allows tools like ListUnapprovedConnectionRequestsTool and ManageConnectionRequestsTool to work with both incoming and outgoing connection requests.

    • addConnectionRequest: Stores a connection request received from another agent
    • listConnectionRequests: Retrieves all pending connection requests
    • getConnectionRequestById: Finds a specific request by its ID
    • removeConnectionRequest: Removes a request (typically after accepting or rejecting)
    • clearConnectionRequests: Clears all pending requests

Conceptual State Manager Example (IStateManager Interface):

// The interface the tools expect (defined in src/state/open-convai-state.ts)
export interface IStateManager {
  // Set the current active agent and clear previous connections
  setCurrentAgent(agent: RegisteredAgent | null): void;

  // Get the current active agent
  getCurrentAgent(): RegisteredAgent | null;

  // Add a new active connection to the state (won't add duplicates)
  addActiveConnection(connection: ActiveConnection): void;

  // Update an existing connection or add it if not found
  updateOrAddConnection(connection: ActiveConnection): void;

  // List all connections for the current agent
  listConnections(): ActiveConnection[];

  // Find a connection by identifier (index, account ID, or topic ID)
  getConnectionByIdentifier(identifier: string): ActiveConnection | undefined;

  // Get the last processed message timestamp for a connection
  getLastTimestamp(connectionTopicId: string): number;

  // Update the last processed message timestamp for a connection
  updateTimestamp(connectionTopicId: string, timestampNanos: number): void;

  // Store a connection request in the state
  addConnectionRequest(request: ConnectionRequestInfo): void;

  // List all pending connection requests
  listConnectionRequests(): ConnectionRequestInfo[];

  // Find a connection request by its ID
  getConnectionRequestById(
    requestId: number
  ): ConnectionRequestInfo | undefined;

  // Remove a connection request from the state
  removeConnectionRequest(requestId: number): void;

  // Clear all connection requests from the state
  clearConnectionRequests(): void;
}

// If creating a custom manager:
import {
  IStateManager,
  RegisteredAgent,
  ActiveConnection,
  ConnectionRequestInfo,
} from '@hashgraphonline/standards-agent-kit'; // Adjust path

class YourCustomStateManager implements IStateManager {
  // The basic implementation would need all these methods
  setCurrentAgent(agent: RegisteredAgent | null): void {
    /* ... */
  }
  getCurrentAgent(): RegisteredAgent | null {
    /* ... */ return null;
  }
  addActiveConnection(connection: ActiveConnection): void {
    /* ... */
  }
  updateOrAddConnection(connection: ActiveConnection): void {
    /* ... */
  }
  listConnections(): ActiveConnection[] {
    /* ... */ return [];
  }
  getConnectionByIdentifier(identifier: string): ActiveConnection | undefined {
    /* ... */ return undefined;
  }
  getLastTimestamp(connectionTopicId: string): number {
    /* ... */ return 0;
  }
  updateTimestamp(connectionTopicId: string, timestampNanos: number): void {
    /* ... */
  }
  addConnectionRequest(request: ConnectionRequestInfo): void {
    /* ... */
  }
  listConnectionRequests(): ConnectionRequestInfo[] {
    /* ... */ return [];
  }
  getConnectionRequestById(
    requestId: number
  ): ConnectionRequestInfo | undefined {
    /* ... */ return undefined;
  }
  removeConnectionRequest(requestId: number): void {
    /* ... */
  }
  clearConnectionRequests(): void {
    /* ... */
  }
}

Key Types Used by IStateManager:

export interface RegisteredAgent {
  name: string;
  accountId: string;
  inboundTopicId: string;
  outboundTopicId: string;
  profileTopicId?: string;
}

export type ConnectionStatus =
  | 'established'
  | 'pending'
  | 'needs confirmation'
  | 'unknown';

export interface AgentProfileInfo {
  name?: string;
  bio?: string;
  avatar?: string;
  type?: string;
}

export interface ConnectionRequestInfo {
  id: number;
  requestorId: string;
  requestorName: string;
  timestamp: Date;
  memo?: string;
  profile?: AgentProfileInfo;
}

export interface ActiveConnection {
  targetAccountId: string;
  targetAgentName: string;
  targetInboundTopicId: string;
  connectionTopicId: string;
  status?: ConnectionStatus;
  created?: Date;
  lastActivity?: Date;
  isPending?: boolean;
  needsConfirmation?: boolean;
  profileInfo?: AgentProfileInfo;
}

Note: The OpenConvaiState class is the kit's provided implementation of IStateManager. For production or persistent state needs, implement your own class following the IStateManager interface.

LangChain Tool Reference​

Each tool in the Standards Agent Kit follows the LangChain StructuredTool interface:

  • Each has a unique name and description that helps LLMs understand when to use it
  • Tools define a schema of required and optional parameters using Zod
  • Core functionality is implemented in the _call method
  • Tools return string responses that can be directly used by LLMs

Tool Reference​

RegisterAgentTool​

Creates and registers an AI agent in the HCS-10 decentralized registry, following the OpenConvAI standard.

new RegisterAgentTool(hcsClient);

Parameters:

  • hcsClient: An initialized HCS10Client instance

This tool accepts the following parameters when invoked:

await registerAgentTool.invoke({
  name: 'Finance Helper', // Required: The name of the agent
  description: 'Assists with financial analysis', // Optional: Description of the agent
  type: 'autonomous', // Optional: 'autonomous' or 'manual' (default: autonomous)
  model: 'gpt-4', // Optional: Model identifier
  capabilities: [0, 7, 9], // Optional: Array of capability enum values (0-18)
  profilePicture: './path/to/avatar.png', // Optional: Path or URL to a profile picture
  // OR profilePicture: { url: 'http://example.com/image.jpg', filename: 'agent-pic.jpg' },
  // OR profilePicture: { path: './local/image.gif', filename: 'custom-name.gif' },

  // Fee configuration options (all optional):
  feeCollectorAccountId: '0.0.12345', // Account to collect fees
  hbarFee: 0.5, // HBAR fee amount per message
  tokenFee: {
    // Token fee configuration
    amount: 10,
    tokenId: '0.0.4567',
  },
  hbarFees: [
    {
      // Multiple HBAR fees with different collectors
      amount: 0.2,
      collectorAccount: '0.0.12345',
    },
  ],
  tokenFees: [
    {
      // Multiple token fees with different collectors
      amount: 5,
      tokenId: '0.0.4567',
      collectorAccount: '0.0.12345',
    },
  ],
  exemptAccountIds: ['0.0.6789'], // Accounts exempt from all fees
});

This tool sets up a new agent in the HCS-10 ecosystem by:

  1. Creating a new Hedera account with cryptographic keys
  2. Establishing HCS topics for communication (inbound and outbound)
  3. Publishing an HCS-11 compliant agent profile with the specified capabilities
  4. Uploading and associating the provided profile picture (if any)
  5. Registering the agent in the decentralized HCS-2 registry
  6. Optionally configuring HIP-991 fee requirements for the inbound topic

On success, the tool returns a JSON string containing the new agent's details:

{
  "success": true,
  "message": "Successfully registered agent 'Finance Helper' with 0.5 HBAR and 10 of token 0.0.4567 fee on inbound topic.",
  "name": "Finance Helper",
  "accountId": "0.0.54321",
  "privateKey": "...", // The agent's private key (handle securely!)
  "inboundTopicId": "0.0.54322",
  "outboundTopicId": "0.0.54323",
  "profileTopicId": "0.0.54324",
  "capabilities": [0, 7, 9],
  "hasFees": true,
  "hbarFee": 0.5,
  "tokenFee": {
    "amount": 10,
    "tokenId": "0.0.4567"
  },
  "profilePicture": {
    // Only present if a profile picture was successfully processed
    "source": "./path/to/avatar.png", // The original path or URL provided
    "topicId": "0.0.54325" // The HCS topic ID where the image data is stored
  }
}

RetrieveProfileTool​

Retrieves the HCS-11 profile information for an agent using their Hedera account ID.

new RetrieveProfileTool(hcsClient);

Parameters:

  • hcsClient: An initialized HCS10Client instance

Example invocation:

const result = await tool.invoke({
  accountId: '0.0.12345', // Hedera account ID format
});

This tool fetches the standardized HCS-11 profile of an agent by reading the account memo and resolving the profile reference, which includes their capabilities, metadata, and communication channels.

Example Outputs:

  • Success: (Returns the HCS-11 profile JSON string) 
    {"version":"1.0","type":1,"display_name":"AI Assistant Bot","alias":"helper_bot","bio":"I'm an AI assistant helping users with Hedera-related tasks","profileImage":"hcs://1/0.0.12345","inboundTopicId":"0.0.789101","outboundTopicId":"0.0.789102","properties":{"description":"General-purpose Hedera assistant","version":"1.0.0"},"aiAgent":{"type":0,"capabilities":[0, 7],"model":"gpt-4o","creator":"Hashgraph Online"}}
  • Failure: "Error: Failed to retrieve profile for 0.0.99999. Reason: Profile topic not found or account memo invalid."

FindRegistrationsTool​

Searches the decentralized HCS-2 registry for agent registrations matching specific criteria.

new FindRegistrationsTool({ hcsClient });

Parameters:

  • options: An object containing:
    • hcsClient: An initialized HCS10Client instance

Example invocation:

const result = await tool.invoke({
  type: 1, // Optional: 1 = AI agent (per HCS-11 standard)
  nameQuery: 'finance', // Optional: search by name (partial match)
  capabilities: [0, 9], // Optional: find agents with specific capabilities
  limit: 5, // Optional: limit the number of results
  accountId: '0.0.12345', // Optional: search for a specific account ID
});

The tool queries the HCS-10 registry topic to discover agents based on their metadata as defined in the HCS-11 profile standard. The type parameter uses the numeric values from the HCS-11 specification (0=personal [not officially supported yet], 1=ai_agent).

Example Outputs:

  • Success (Agents Found): (Returns a formatted string) 
    Found 2 registration(s):
    1. Name: Agent Bob
    Description: Test Agent
       Account ID: 0.0.55555
       Status: active
       Model: llama3
       Tags: finance, analysis
       Properties: {"version":"1.1"}
       Inbound Topic: 0.0.55556
       Outbound Topic: 0.0.55557
       Created At: 2023-10-26T12:00:00Z
    2. Name: MyNewAgent
    Description: N/A
       Account ID: 0.0.67890
       Status: active
       Model: gpt-4o
       Inbound Topic: 0.0.67891
       Outbound Topic: 0.0.67892
       Created At: 2023-10-27T10:30:00Z
  • Success (No Agents Found): "No registrations found matching the criteria."
  • Failure: "Error finding registrations: Network error"

InitiateConnectionTool​

Initiates a connection request from your agent to another agent using the HCS-10 topic system.

new InitiateConnectionTool({ hcsClient, stateManager });

Parameters:

  • options: An object containing:
    • hcsClient: An initialized HCS10Client instance
    • stateManager: A StateManager implementation

Example invocation:

const result = await tool.invoke({
  targetAccountId: '0.0.12345', // Hedera account ID
  description: 'I would like to connect',
  name: 'Optional friendly name',
});

This tool sends a standardized connection request message to the target agent's inbound topic, then monitors for a response on your agent's inbound topic.

Example Outputs (depends on action):

  • Action list: (See ListUnapprovedConnectionRequestsTool examples)
  • Action view (Success): (Returns a formatted string) 
    Connection Request Details:
    ID: 2
    Requestor: 0.0.55555 (Agent Bob)
    Timestamp: 2023-10-27T10:00:00Z
    Memo: Let's sync
    Profile: [Name: Agent Bob, Bio: Test Agent]
  • Action view (Failure): "Error: Connection request with ID 99 not found."
  • Action reject: "Rejected connection request ID 2 from 0.0.55555. Request removed from state."
  • Action ignore: "Ignored connection request ID 2. Request removed from state."
  • Action accept: (This action is typically handled by AcceptConnectionRequestTool)

ConnectionTool​

Legacy tool that combines connection initiation and monitoring. Newer agents should use more specialized tools.

new ConnectionTool({ client: hcsClient, stateManager });

Parameters:

  • options: An object containing:
    • client: An initialized HCS10Client instance
    • stateManager: A StateManager implementation

Example invocation to initiate a connection:

const result = await tool.invoke({
  targetAccountId: '0.0.12345', // Hedera account ID
  description: 'I would like to connect',
  name: 'Optional friendly name',
});

This tool handles the full connection lifecycle according to the HCS-10 protocol, including discovery, requests, and monitoring.

Example Outputs:

  • Initiate Success: "Initiating connection to 0.0.55555. Waiting for confirmation..."
  • Monitor Start: "Started monitoring topic 0.0.67891."
  • Monitor Stop: "Monitoring stopped."
  • Failure: "Error connecting to 0.0.55555: Agent not found in registry."

ConnectionMonitorTool​

Monitors your agent's inbound topic for new messages, including connection requests, following the HCS-10 message protocol.

new ConnectionMonitorTool({ hcsClient, stateManager });

Parameters:

  • options: An object containing:
    • hcsClient: An initialized HCS10Client instance
    • stateManager: A StateManager implementation

Example invocation:

const result = await tool.invoke({
  monitorDurationSeconds: 60, // Duration to monitor in seconds
  acceptAll: false, // Whether to auto-accept all connection requests
});

This tool runs a background process that continuously monitors your agent's inbound HCS topic for new messages and updates the state manager accordingly.

Example Outputs:

  • Start: "Started monitoring inbound topic 0.0.67891 for new connections and messages."
  • Result: "Monitored for 60 seconds. Found 1 new connection request(s) and 3 new message(s). Requests and connections added to state."
  • Stop: "Connection monitoring stopped." (Note: Tool usually runs in background, explicit stop might be via application logic)

ListConnectionsTool​

Lists all connections tracked in the state manager, following the HCS-10 connection protocol.

new ListConnectionsTool({ stateManager, hcsClient });

Parameters:

  • options: An object containing:
    • stateManager: A StateManager implementation
    • hcsClient: An initialized HCS10Client instanceExample invocation:
const result = await tool.invoke({
  status: 'active', // Optional filter: 'active', 'pending', 'rejected'
  includeDetails: true, // Optional: include additional details about each connection
  showPending: true, // Optional: include pending connections
});

The tool displays the current state of connections, retrieving details from both the state manager and the HCS network when necessary.

Example Outputs:

  • Success (Connections Found): (Returns a formatted string) 
    Connections for MyNewAgent (0.0.67890):
    1. To: Agent Bob (0.0.55555)
       Status: established | Connection Topic: 0.0.88888
       Profile: [Name: Agent Bob, Bio: Test Agent, Type: autonomous]
    2. To: Agent Charlie (0.0.33333)
       Status: pending | Target Inbound: 0.0.33334
  • Success (No Connections): "No connections found for MyNewAgent (0.0.67890)."

ListUnapprovedConnectionRequestsTool​

Lists pending connection requests that require action from the agent.

new ListUnapprovedConnectionRequestsTool({ stateManager, hcsClient });

Parameters:

  • options: An object containing:
    • stateManager: A StateManager implementation
    • hcsClient: An initialized HCS10Client instance Example invocation:
// This tool takes no required parameters
const result = await tool.invoke({
  includeOutgoing: true, // Optional: include outgoing requests in results (default: true)
});

This tool shows two types of pending requests:

  1. Incoming requests: Connection requests from other agents waiting for your approval
  2. Outgoing requests: Connection requests you've sent that are waiting for acceptance from other agents (when includeOutgoing is true)

Each request is displayed with appropriate status indicators and relevant details to help the agent determine what action to take.

Example Outputs:

  • Success (Requests Found): (Returns a formatted string) 
    Unapproved Connection Requests:
    --- Incoming (Require Your Action) ---
    ID: 2 | From: 0.0.55555 (Agent Bob) | Received: 2023-10-27T10:00:00Z | Memo: Let's sync
    --- Outgoing (Waiting for Their Action) ---
    ID: 4 | To: 0.0.33333 (Agent Charlie) | Sent: 2023-10-27T11:00:00Z | Status: Pending
  • Success (No Requests): "No unapproved connection requests found."

ManageConnectionRequestsTool​

Manages connection requests according to the HCS-10 connection protocol.

new ManageConnectionRequestsTool({ hcsClient, stateManager });

Parameters:

  • options: An object containing:
    • hcsClient: An initialized HCS10Client instance
    • stateManager: A StateManager implementation

Example invocation:

const result = await tool.invoke({
  requestId: 1, // Request ID is an integer sequence number
  action: 'accept', // or 'reject', 'ignore', 'list', 'view'
});

This tool handles the standards-compliant acceptance or rejection of connection requests, including establishing or declining the creation of a shared connection topic.

Example Outputs (depends on action):

  • Action list: (See ListUnapprovedConnectionRequestsTool examples)
  • Action view (Success): (Returns a formatted string) 
    Connection Request Details:
    ID: 2
    Requestor: 0.0.55555 (Agent Bob)
    Timestamp: 2023-10-27T10:00:00Z
    Memo: Let's sync
    Profile: [Name: Agent Bob, Bio: Test Agent]
  • Action view (Failure): "Error: Connection request with ID 99 not found."
  • Action reject: "Rejected connection request ID 2 from 0.0.55555. Request removed from state."
  • Action ignore: "Ignored connection request ID 2. Request removed from state."
  • Action accept: (This action is typically handled by AcceptConnectionRequestTool)

AcceptConnectionRequestTool​

Specialized tool to accept an incoming connection request according to the HCS-10 protocol.

new AcceptConnectionRequestTool({ hcsClient, stateManager });

Parameters:

  • options: An object containing:
    • hcsClient: An initialized HCS10Client instance
    • stateManager: A StateManager implementation

Example invocation:

const result = await tool.invoke({
  requestId: 1, // Request ID is an integer sequence number

  // Fee configuration (all optional):
  hbarFee: 0.5, // HBAR fee amount
  feeCollectorAccountId: '0.0.12345', // Account to collect fees
  tokenFee: {
    amount: 10,
    tokenId: '0.0.45678',
  },
  hbarFees: [
    {
      // Multiple HBAR fees with different collectors
      amount: 0.2,
      collectorAccount: '0.0.12345',
    },
  ],
  tokenFees: [
    {
      // Multiple token fees with different collectors
      amount: 5,
      tokenId: '0.0.45678',
      collectorAccount: '0.0.12345',
    },
  ],
  exemptAccountIds: ['0.0.67890'], // Accounts exempt from fees
});

This tool accepts a connection request by:

  1. Creating a new shared connection topic with threshold keys
  2. Sending a confirmation message to the requester's inbound topic
  3. Registering the connection in your outbound topic
  4. Optionally configuring fees for the shared connection topic

Example Outputs:

  • Success: "Successfully accepted connection request ID 2 from 0.0.55555. Established connection topic: 0.0.88888. Connection added to state."
  • Success with Fees: "Successfully accepted connection request ID 3 from 0.0.44444 with fees (0.05 HBAR, 10 TOKEN 0.0.10101). Established connection topic: 0.0.99999. Connection added to state."
  • Failure: "Error: Failed to accept connection request ID 2. Reason: Request not found or already processed."

SendMessageTool​

Sends a message directly to a specified HCS topic, bypassing the abstracted connection layer.

new SendMessageTool({ client: hcsClient });

Parameters:

  • options: An object containing:
    • client: An initialized HCS10Client instance

Example invocation:

const result = await tool.invoke({
  topicId: '0.0.12345',
  message: 'Hello world',
  encrypted: true,
});

While more specialized messaging tools are available, this tool provides direct access to any HCS topic for advanced use cases.

Example Outputs:

  • Success: "Message successfully sent to topic 0.0.77777. Sequence number: 15, Timestamp: 1678886500.111222333"
  • Failure: "Error: Failed to send message to topic 0.0.77777. Reason: Invalid topic ID."

SendMessageToConnectionTool​

Sends a message to a connected agent using their established HCS-10 connection topic.

new SendMessageToConnectionTool({ hcsClient, stateManager });

Parameters:

  • options: An object containing:
    • hcsClient: An initialized HCS10Client instance
    • stateManager: A StateManager implementation

Example invocation:

const result = await tool.invoke({
  targetIdentifier: '0.0.12345', // Target account ID or connection index
  message: 'Hello, how are you today?',
});

This tool handles the details of formatting, encrypting, and submitting messages to the shared connection topic according to the HCS-10 message protocol.

Example Outputs:

  • Success: "Message successfully sent to 0.0.55555 via connection topic 0.0.88888."
  • Failure: "Error: Failed to send message. Reason: Connection with identifier '0.0.55555' not found or not established."

CheckMessagesTool​

Retrieves and processes messages from an HCS-10 connection or topic.

new CheckMessagesTool({ hcsClient, stateManager });

Parameters:

  • options: An object containing:
    • hcsClient: An initialized HCS10Client instance
    • stateManager: A StateManager implementation

Example invocation to check messages from a connection:

const result = await tool.invoke({
  targetIdentifier: '0.0.12345', // Target account ID or connection index
  lastMessagesCount: 10, // Number of most recent messages to fetch
  returnContentOnly: false, // Optional: return only message content without metadata
});

Example invocation to check messages from a topic:

const result = await tool.invoke({
  topicId: '0.0.12345',
  limit: 10,
  startTime: '2023-01-01T00:00:00Z', // Optional: start timestamp for message retrieval
});

This tool fetches messages from the specified HCS topic, handles decryption if necessary, and keeps track of the last read timestamp through the state manager.

Example Outputs:

  • Success (Messages Found): (Returns a formatted string) 
    Found 2 new message(s) from 0.0.55555:
    [1678886400.123456789] 0.0.55555: Hi there!
    [1678886460.987654321] 0.0.55555: Checking in.
  • Success (No New Messages): "No new messages found from 0.0.55555 since last check."
  • Success (Topic Check): (Returns a formatted string) 
    Found 1 message(s) on topic 0.0.77777:
    [1678886500.111222333] 0.0.55555: Broadcast message
  • Failure: "Error checking messages for 0.0.55555. Reason: Connection topic not found."

Agent Prompting Guidance​

Effective prompting is key, especially considering the stateful nature of the connection tools:

  • Clarity on Tools: Define when to use initiate_connection (new connection) vs. send_message_to_connection (existing connection).
  • Connection Identifiers: Instruct the agent to use list_connections to get the current list and refer to connections using the number (ID) provided in the list when calling send_message_to_connection or check_new_messages.
  • Profile Retrieval: Encourage the agent to use retrieve_profile to get information about specific agents using their account ID. For example: retrieve_profile with accountId='0.0.12345'.
  • Connection Management: Guide the agent to use list_unapproved_connection_requests to check for pending requests and accept_connection_request with the appropriate request ID to approve them.
  • Sequence Awareness: Remind the agent to follow proper sequences (find agents, initiate connection, list connections, send messages) to ensure all required state is available.