@three-ws/agent-protocol-sdk

@three-ws/agent-protocol-sdk

Record verifiable agent-to-agent skill invocations on Solana, via the agent_invocation Anchor program.

Install · Quick start · API · Requirements · three.ws

Thin, typed client for the agent_invocation Solana program. One agent calls a skill on another agent; the call is validated client-side, built as an Anchor instruction, and submitted on-chain, where it emits a SkillInvoked event that anyone can verify. Built for three.ws agent-to-agent (A2A) coordination.

Pending deployment. The agent_invocation program is not yet deployed to mainnet. The program id exported as AGENT_INVOCATION_PROGRAM_ID (Fg6PaFpoGXkYsidMpWTK6W2BeZ7FEfcYkg476zPFsLnS) is the Anchor placeholder id, not a live deployment. To use this SDK against a real cluster you must deploy the program yourself and pass your own programId to invokeSkill() / deriveAgentPda(). Until then, treat the defaults as devnet/local scaffolding.

Install

npm install @three-ws/agent-protocol-sdk @solana/web3.js @coral-xyz/anchor

@solana/web3.js (^1.98) and @coral-xyz/anchor (^0.32) are direct dependencies and are installed alongside the package.

Quick start

import { Connection, Keypair, PublicKey } from '@solana/web3.js';
import { invokeSkill } from '@three-ws/agent-protocol-sdk';

const connection = new Connection('https://api.devnet.solana.com', 'confirmed');
const invokerAuthority = Keypair.fromSecretKey(/* your secret key bytes */);
const targetAuthority = new PublicKey('<authority that owns the target agent>');

const signature = await invokeSkill({
  connection,
  invokerAuthority,                       // signs + pays
  targetAuthority,                        // target agent PDA is derived from this
  skillName: 'summarize',                 // 1–64 bytes
  parameters: JSON.stringify({ url: 'https://example.com' }), // ≤512 bytes
  programId: new PublicKey('<your deployed program id>'),     // required on a live cluster
});

console.log('invocation tx:', signature);

invokeSkill validates the inputs, derives both the invoker and target agent PDAs, builds the invoke_skill instruction, submits it, and returns the confirmed transaction signature.

API

invokeSkill(params): Promise<string>

Records a skill invocation from one agent to another and returns the confirmed transaction signature.

Param	Type	Description
connection	Connection	Live Solana connection used to build and send the tx.
invokerAuthority	Keypair	Owns the invoking agent. Signs and pays.
targetAuthority	PublicKey	Owns the target agent; its PDA is re-derived from this.
skillName	string	Skill identifier, 1–64 bytes (UTF-8).
parameters	string	Opaque parameter blob, ≤512 bytes (typically JSON).
programId	PublicKey (optional)	Override the program id. Required on any live cluster.

Throws if skillName is empty, skillName exceeds MAX_SKILL_NAME_LEN bytes, or parameters exceeds MAX_PARAMETERS_LEN bytes — so you get a clear local error instead of a failed on-chain simulation.

deriveAgentPda(authority, programId?): [PublicKey, number]

Derives an agent's program-derived address from the authority that owns it. Matches the program's seeds = [b"agent", authority]. Pass your deployed programId to derive against a live cluster; otherwise it uses AGENT_INVOCATION_PROGRAM_ID.

import { deriveAgentPda } from '@three-ws/agent-protocol-sdk';

const [agentPda, bump] = deriveAgentPda(authority, programId);

Constants & types

Export	Type	Value / meaning
MAX_SKILL_NAME_LEN	number	64 — max skillName length in bytes.
MAX_PARAMETERS_LEN	number	512 — max parameters length in bytes.
AGENT_INVOCATION_PROGRAM_ID	string	Declared program id (placeholder until deployed).
IDL	Anchor Idl	The agent_invocation IDL (Anchor 0.30+ format).
AgentInvocation	type	TypeScript type of IDL for new Program<AgentInvocation>(...).
InvokeSkillParams	interface	Parameter shape for invokeSkill.

On-chain shape

The program exposes one instruction, invoke_skill(skill_name, parameters), over four accounts (invoker_agent PDA, invoker_authority signer, target_authority, target_agent PDA) plus the system program. A successful call emits a SkillInvoked event with invoker_agent, target_agent, invoker_authority, skill_name, parameters, and a timestamp. The program's error codes (EmptySkillName, SkillNameTooLong, ParametersTooLong) mirror the client-side validation above.

Requirements

• Node >= 18.
• Peers / deps: @solana/web3.js@^1.98, @coral-xyz/anchor@^0.32.
• A deployed program. On any live cluster you must deploy agent_invocation and pass its id as programId. The default AGENT_INVOCATION_PROGRAM_ID is a placeholder.

Links

• Homepage: https://three.ws
• Changelog: https://three.ws/changelog
• Issues: https://github.com/nirholas/three.ws/issues
• License: MIT — see LICENSE

_{Part of the three.ws SDK suite — 3D AI agents, on-chain identity, and agent payments.
Website · Changelog · GitHub}