{"_id":"@a2a-labs/registry-client","_rev":"2-815a5f9adc6620d5f71eb2b0ac44c0f6","name":"@a2a-labs/registry-client","dist-tags":{"latest":"0.2.0"},"versions":{"0.2.0":{"name":"@a2a-labs/registry-client","version":"0.2.0","keywords":["a2a","a2a-labs","a2a-registry-server","a2a-registry-client","typescript","client","agent","agent2agent","agent-registry","service-discovery"],"license":"Apache-2.0","_id":"@a2a-labs/registry-client@0.2.0","maintainers":[{"name":"tsangwailam","email":"info@digicrafts.com.hk"}],"dist":{"shasum":"70a02a06091ff14853c4732e8ac600864e710597","tarball":"https://registry.npmjs.org/@a2a-labs/registry-client/-/registry-client-0.2.0.tgz","fileCount":23,"integrity":"sha512-kux+bze6awCRQBKlZ25z+eN5NT2pDSw7wgaK2oCNSsJB3Q5uinY2xpIOWDAwUnRzFXL8eXJpbQUUS+r6mzQOLA==","signatures":[{"sig":"MEYCIQDZvOJjBOnIycpq8S0uEac17eYbKRlsJqDGWkKAoDw9ZAIhAMlQnUZbUQz+SH40nVi7Vqm0LFTosd+K+8rvtWqzewTZ","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":56611},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=22"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"9875c805b1f20ed2e9ede121450c87065b2e75e1","scripts":{"test":"node --import tsx --test test/*.test.ts","build":"tsc -p tsconfig.json","check":"tsc -p tsconfig.json --noEmit","test:watch":"node --import tsx --test --watch test/*.test.ts"},"_npmUser":{"name":"tsangwailam","email":"info@digicrafts.com.hk"},"_npmVersion":"11.17.0","description":"TypeScript client and lease manager for the A2A Registry Server","directories":{},"_nodeVersion":"26.5.0","dependencies":{"@a2a-js/sdk":"^1.0.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.20.3","typescript":"^5.9.2","@types/node":"^24.0.0"},"_npmOperationalInternal":{"tmp":"tmp/registry-client_0.2.0_1786799396722_0.07238777896313509","host":"s3://npm-registry-packages-npm-production"},"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."}},"time":{"created":"2026-08-15T13:09:56.524Z","modified":"2026-08-20T13:32:02.415Z","0.2.0":"2026-08-15T13:09:56.872Z"},"license":"Apache-2.0","keywords":["a2a","a2a-labs","a2a-registry-server","a2a-registry-client","typescript","client","agent","agent2agent","agent-registry","service-discovery"],"description":"TypeScript client and lease manager for the A2A Registry Server","maintainers":[{"name":"tsangwailam","email":"info@digicrafts.com.hk"}],"readme":"# A2A Registry TypeScript Client\n\nTyped client and managed lease helper for `a2a-registry-server` 0.2 and later.\nIt discovers logical agents with multiple independently leased runtime instances,\nusing the standard Fetch API and the official `@a2a-js/sdk` Agent Card type.\n\n## Install\n\n```bash\nnpm install a2a-registry-client-ts\n```\n\nNode.js 22 or newer is required.\n\n## Discover agents\n\n```ts\nimport { RegistryClient } from \"a2a-registry-client-ts\";\n\nconst registry = new RegistryClient(\"http://localhost:3003\");\nconst page = await registry.listAgents({\n  skill: \"weather\",\n  capability: \"streaming\",\n  limit: 25,\n});\n\nfor (const agent of page.agents) {\n  console.log(agent.id, agent.instanceCount);\n  for (const instance of agent.instances) {\n    console.log(instance.instanceId, instance.endpoint, instance.metadata);\n  }\n}\n```\n\nFor the common single-match case, use `findAgentBySkill(\"weather\")`. The\ntop-level `agent.endpoint` and lease fields remain compatibility projections;\nnew code should select an active entry from `agent.instances`.\n\n## Maintain an agent registration\n\n`maintainA2ARegistryRegistration` is based on the helper previously kept in\n`website/agents/shared/a2a-registry.ts`. It registers immediately, renews the\nlease every one-third of its TTL, re-registers after expiry, and unregisters on\nshutdown.\n\n```ts\nimport type { AgentCard } from \"@a2a-js/sdk\";\nimport { maintainA2ARegistryRegistration } from \"a2a-registry-client-ts\";\n\nconst card: AgentCard = createAgentCard();\nconst lease = maintainA2ARegistryRegistration({\n  id: \"weather-agent\",\n  instanceId: \"eu-west-1a\",\n  endpoint: \"http://localhost:3002/v1/tasks\",\n  agentCard: card,\n  ttlSeconds: 60,\n  metadata: { role: \"weather\" },\n  logPrefix: \"[Weather Agent]\",\n});\n\nawait lease.ready;\n\nprocess.once(\"SIGTERM\", () => {\n  void lease.stop().finally(() => process.exit(0));\n});\n```\n\nThe helper reads `A2A_REGISTRY_URL` (or `REGISTRY_URL`) and\n`A2A_REGISTRY_WRITE_TOKEN` (or `REGISTRY_WRITE_TOKEN`) when the corresponding\noptions are omitted. Pass an existing `leaseToken` when reclaiming a live\ninstance after a process restart. Omit `instanceId` to use the server's\nbackward-compatible `default` instance.\n\n## Multiple instances\n\nEvery instance under one logical agent ID must publish exactly the same Agent\nCard. Each instance has its own endpoint, metadata, TTL, lease token, heartbeat,\nand expiry:\n\n```ts\nconst first = await registry.registerAgentInstance(\"weather-agent\", {\n  instanceId: \"eu-west-1a\",\n  endpoint: \"https://weather-a.example/a2a\",\n  agentCard: card,\n  ttlSeconds: 60,\n  metadata: { zone: \"eu-west-1a\" },\n});\n\nconst second = await registry.registerAgentInstance(\"weather-agent\", {\n  instanceId: \"eu-west-1b\",\n  endpoint: \"https://weather-b.example/a2a\",\n  agentCard: card,\n  ttlSeconds: 60,\n  metadata: { zone: \"eu-west-1b\" },\n});\n\nconst { instances } = await registry.listAgentInstances(\"weather-agent\");\nconst instance = await registry.getAgentInstance(\"weather-agent\", \"eu-west-1b\");\n\nawait registry.heartbeatInstance(\"weather-agent\", \"eu-west-1b\", {\n  leaseToken: second.leaseToken,\n});\n\nawait registry.unregisterAgentInstance(\"weather-agent\", \"eu-west-1a\", {\n  leaseToken: first.leaseToken,\n});\n```\n\nUse `putAgentInstance(id, instanceId, input, options)` to update an existing\ninstance using its lease token. An Agent Card that differs from active sibling\ninstances is rejected by the server with `409 agent_card_mismatch`.\n\n## Direct lease operations\n\n```ts\nconst registry = new RegistryClient({\n  baseUrl: \"http://localhost:3003\",\n  writeToken: process.env.A2A_REGISTRY_WRITE_TOKEN,\n});\n\nconst registration = await registry.registerAgent({\n  id: \"weather-agent\",\n  endpoint: \"http://localhost:3002/v1/tasks\",\n  agentCard: card,\n  ttlSeconds: 60,\n});\n\nawait registry.heartbeat(\"weather-agent\", {\n  leaseToken: registration.leaseToken,\n});\n\nawait registry.unregisterAgent(\"weather-agent\", {\n  leaseToken: registration.leaseToken,\n});\n```\n\nThese methods operate on the compatibility `default` instance. Named instances\nuse `registerAgentInstance`, `putAgentInstance`, `heartbeatInstance`, and\n`unregisterAgentInstance`.\n","readmeFilename":"README.md"}