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