Skip to content

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.

6.2 KB
Raw Blame

agent_invocation: verifiable agent-to-agent skill invocations (Solana / Anchor)

When one three.ws agent calls a skill on another agent, this program records that call on-chain as a verifiable event. Anyone can replay the transaction log and prove who invoked what, on whom, with which parameters, and when, without trusting our database or either agent's own claims.

agent A (signer) --> invoke_skill("summarize", params) --> SkillInvoked event
                          |
                          +-- invoker_agent PDA  ["agent", A]  (proves A is A)
                          +-- target_agent  PDA  ["agent", B]  (proves B exists)

The program is intentionally non-trust-bearing: it moves no funds and grants no capability. Its single job is identity-checked event emission, which makes it the audit rail under three.ws agent-to-agent (A2A) coordination. This is the "On-chain agent invocation" surface in STRUCTURE.md; the published client is @three-ws/agent-protocol-sdk.

Program id (same on every cluster, baked into declare_id!): AgEntJDMi1A7UadCoYcx6Fm3gusNk8SHLCi7vSUa4Zfo

Agent identity: PDAs, not registrations

An agent's on-chain identity is a program-derived address, computed from the wallet that controls it:

Account Seeds Notes
invoker_agent ["agent", invoker_authority] Re-derived and verified by Anchor seeds/bump constraints. The authority must sign, so a caller can only ever act as their own agent.
target_agent ["agent", target_authority] Same derivation for the target. The target authority does not sign; only its pubkey is needed to re-derive the PDA.

Because both agent accounts are constrained PDAs rather than raw AccountInfo, an attacker cannot substitute an arbitrary account and have downstream consumers trust it. There is no registration instruction and no rent: the PDA derivation itself is the identity scheme. The SDK mirrors it in deriveAgentPda.

Instructions

Instruction Signer Effect
invoke_skill(skill_name, parameters) invoker_authority Validates lengths, verifies both agent PDAs, and emits a SkillInvoked event. No state is written.

Limits enforced on-chain (and re-checked client-side by the SDK): skill_name is 1 to 64 bytes, parameters is at most 512 bytes (typically a JSON blob). Violations fail with EmptySkillName, SkillNameTooLong, or ParametersTooLong from the program's InvocationError enum.

The SkillInvoked event

Emitted via Anchor emit!, decodable with anchor.EventParser and the IDL:

Field Type Meaning
invoker_agent Pubkey PDA of the calling agent
target_agent Pubkey PDA of the agent whose skill was invoked
invoker_authority Pubkey Wallet that signed the invocation
skill_name String Skill identifier (max 64 bytes)
parameters String Opaque parameter blob (max 512 bytes)
timestamp i64 Cluster unix time at emission

The hand-maintained IDL lives at ../idl/agent_invocation.json, kept in sync with src/lib.rs and shipped inside the SDK as its IDL export.

Usage

Most callers should not build instructions by hand; use the SDK:

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

This example is the core of the devnet smoke test (scripts/agent-invocation-smoke.mjs), which runs it end-to-end against the live program and asserts every event field:

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

const connection = new Connection('https://api.devnet.solana.com', 'confirmed');

const invokerAuthority = Keypair.generate(); // must hold SOL; it signs and pays the fee
const targetAuthority = Keypair.generate().publicKey; // wallet owning the target agent

// The PDAs that will appear in the emitted event.
const [invokerAgent] = deriveAgentPda(invokerAuthority.publicKey);
const [targetAgent] = deriveAgentPda(targetAuthority);

const signature = await invokeSkill({
  connection,
  invokerAuthority,
  targetAuthority,
  skillName: 'summarize',
  parameters: JSON.stringify({ url: 'https://three.ws', lang: 'en' }),
});

console.log(`SkillInvoked: ${invokerAgent} -> ${targetAgent}`);
console.log(`https://explorer.solana.com/tx/${signature}?cluster=devnet`);

invokeSkill validates the length limits locally, derives both PDAs, builds the invoke_skill instruction, and returns the confirmed signature. Pass programId only when targeting a deployment other than the default id above.

Build, test, deploy

The crate is a self-contained Cargo workspace (see Cargo.toml), so builds here never walk up into an unrelated parent workspace:

anchor build                              # compile + verify against the IDL
anchor deploy --provider.cluster devnet   # program keypair = declare_id
anchor run smoke                          # devnet smoke test (defined in Anchor.toml)

The smoke test funds a fresh synthetic invoker (devnet airdrop, or a SMOKE_FUNDER_KEYPAIR payer on other clusters), submits a real invoke_skill, then parses the transaction logs and asserts each SkillInvoked field matches what was sent. It exits non-zero on any mismatch. Cluster config, program ids per cluster, and the deploy wallet path are in Anchor.toml; the deploy authority keypair is kept out of the repo (Secret Manager: AGENT_INVOCATION_DEPLOY_AUTHORITY).

Related surfaces

  • agent-protocol-sdk/: the npm client (invokeSkill, deriveAgentPda, IDL, AGENT_INVOCATION_PROGRAM_ID, MAX_SKILL_NAME_LEN, MAX_PARAMETERS_LEN).
  • ../skill-license/: sibling Anchor program minting on-chain skill-ownership NFTs; it follows this program's IDL convention.
  • ../README.md: the EVM contracts that share this contracts/ directory.