@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.

Live. The agent_invocation program is deployed and the SDK targets it by default. AGENT_INVOCATION_PROGRAM_ID is AgEntJDMi1A7UadCoYcx6Fm3gusNk8SHLCi7vSUa4Zfo — the same program id on mainnet-beta and devnet. Just point connection at the cluster you want; the programId param is optional and only needed to target a different deployment. Deploy addresses, signatures, and the upgrade authority are recorded in contracts/agent-invocation/DEPLOYMENT.md.

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';

// mainnet-beta by default; use 'https://api.devnet.solana.com' for devnet.
const connection = new Connection('https://api.mainnet-beta.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 is optional — defaults to the live AGENT_INVOCATION_PROGRAM_ID.
});

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	Live program id (AgEnt…Zfo), same on mainnet + devnet.
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 funded invoker. invokerAuthority signs and pays the transaction fee, so it needs a small SOL balance on the target cluster. The program itself is already deployed — AGENT_INVOCATION_PROGRAM_ID points at the live program on mainnet and devnet.

Links

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

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