Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
@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_invocationSolana 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 aSkillInvokedevent that anyone can verify. Built for three.ws agent-to-agent (A2A) coordination.
Program id, and where it stands.
AGENT_INVOCATION_PROGRAM_IDisAgEntJDMi1A7UadCoYcx6Fm3gusNk8SHLCi7vSUa4Zfo, the id baked into the program'sdeclare_id!and therefore the same on every cluster. As of 2026-08-11 that account is not yet deployed on mainnet-beta or devnet:invokeSkillbuilds and signs a correct instruction, and the cluster rejects it until the program is published. Verify before you build on it (solana account AgEntJDMi1A7UadCoYcx6Fm3gusNk8SHLCi7vSUa4Zfo, or runnode scripts/onchain-smoke.mjs --only=solana-invokein the repo, which probes the cluster and reports the current state). Build and deploy instructions are incontracts/agent-invocation/README.md. Once it is live, pointconnectionat the cluster you want; theprogramIdparam stays optional and is only needed to target a different deployment.
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; it defaults to 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, max 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 |
The program's declare_id! (AgEnt…Zfo), same on every cluster. |
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.
invokerAuthoritysigns and pays the transaction fee, so it needs a small SOL balance on the target cluster. - A deployed program.
AGENT_INVOCATION_PROGRAM_IDis not on-chain yet (see the note at the top); until it is, submitting an invocation fails at the cluster. Check the account before you depend on it.
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