{"_id":"@a2a-lib/registry-client-ts","_rev":"3-c9fa46af2eb3267c2335a49bc72755f4","name":"@a2a-lib/registry-client-ts","dist-tags":{"latest":"0.3.0"},"versions":{"0.2.0":{"name":"@a2a-lib/registry-client-ts","version":"0.2.0","keywords":["a2a","a2a-lib","a2a-registry-server","a2a-registry-client","typescript","client","agent","agent2agent","agent-registry","service-discovery"],"license":"Apache-2.0","_id":"@a2a-lib/registry-client-ts@0.2.0","maintainers":[{"name":"tsangwailam","email":"tsangwailam@gmail.com"}],"homepage":"https://github.com/a2a-lib/a2a-registry-client-ts#readme","bugs":{"url":"https://github.com/a2a-lib/a2a-registry-client-ts/issues"},"dist":{"shasum":"6303c5439c49ecfa6dd95166fb501d5db41fa203","tarball":"https://registry.npmjs.org/@a2a-lib/registry-client-ts/-/registry-client-ts-0.2.0.tgz","fileCount":23,"integrity":"sha512-/VCqnxzCJ56ZzmOsHW+QdlNiIx7l9D5df0sAR7o3hxVG0puEW2MscgZBwnJgEeo4vv2YCb6nW6G+G3apNVEPsw==","signatures":[{"sig":"MEUCIADe2KAZ9hz70o8bgF1V5w8A0vwE3sXqPq6L82YHOa89AiEAsK8LEMXVPlKxeWQlZ42uJhbq/d+aTJMRPFokdSeR0f0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":56740},"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":"4660e70d969e2d29f5edf7d642f4a8d1ad982448","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":"tsangwailam@gmail.com"},"repository":{"url":"git+https://github.com/a2a-lib/a2a-registry-client-ts.git","type":"git"},"_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-ts_0.2.0_1787237533802_0.7870136607707561","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"name":"@a2a-lib/registry-client-ts","version":"0.2.1","keywords":["a2a","a2a-lib","a2a-registry-server","a2a-registry-client","typescript","client","agent","agent2agent","agent-registry","service-discovery"],"license":"Apache-2.0","_id":"@a2a-lib/registry-client-ts@0.2.1","maintainers":[{"name":"tsangwailam","email":"tsangwailam@gmail.com"}],"homepage":"https://github.com/a2a-lib/a2a-registry-client-ts#readme","bugs":{"url":"https://github.com/a2a-lib/a2a-registry-client-ts/issues"},"dist":{"shasum":"b96198a9fec5aafd6f8ef28d01a1a357f82f80b5","tarball":"https://registry.npmjs.org/@a2a-lib/registry-client-ts/-/registry-client-ts-0.2.1.tgz","fileCount":23,"integrity":"sha512-7Ft15Etv+aIMzuFz0RJSKII61CSQXj4I9A66mVS5Q/KCtSu7kv+bi0/8VttzCCfJWqY/vgdn73b4O2fZkRbLhg==","signatures":[{"sig":"MEUCIE3Z46pUnCA2i9hv7Cf+PS4PkNwAvSSI0zlcGR9NWEB3AiEA32eNACILFqBW2WY+OhI7gURnXwGZVikUdRLvQyIZj4A=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":59293},"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":"db7c2e4cbbf458801f32334bf4d5e8d3e52c15b6","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":"tsangwailam@gmail.com"},"repository":{"url":"git+https://github.com/a2a-lib/a2a-registry-client-ts.git","type":"git"},"_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-ts_0.2.1_1787337598800_0.7466123273006224","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@a2a-lib/registry-client-ts","version":"0.3.0","description":"TypeScript client and lease manager for the A2A Registry Server","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"engines":{"node":">=22"},"scripts":{"build":"tsc -p tsconfig.json","check":"tsc -p tsconfig.json --noEmit","test":"node --import tsx --test test/*.test.ts","test:watch":"node --import tsx --test --watch test/*.test.ts"},"keywords":["a2a","a2a-lib","a2a-registry-server","a2a-registry-client","typescript","client","agent","agent2agent","agent-registry","service-discovery"],"license":"Apache-2.0","dependencies":{"@a2a-js/sdk":"^1.0.1"},"devDependencies":{"@types/node":"^24.0.0","tsx":"^4.20.3","typescript":"^5.9.2"},"repository":{"type":"git","url":"git+https://github.com/a2a-lib/a2a-registry-client-ts.git"},"publishConfig":{"access":"public"},"gitHead":"cfbb223d90ca4fc65101fc559944f65c1ba2a32d","_id":"@a2a-lib/registry-client-ts@0.3.0","bugs":{"url":"https://github.com/a2a-lib/a2a-registry-client-ts/issues"},"homepage":"https://github.com/a2a-lib/a2a-registry-client-ts#readme","_nodeVersion":"26.5.0","_npmVersion":"11.17.0","dist":{"integrity":"sha512-P/MurHt5JjNsKI0wB71vu4lH5Hyvp3FpdVdFC4qTZKrK1Bpd/ZFw03ui2nHBj/8v0/xyPbp+RHbPt//Leq0ZeA==","shasum":"bf8e319c618256da71f85a530d5595cc06352149","tarball":"https://registry.npmjs.org/@a2a-lib/registry-client-ts/-/registry-client-ts-0.3.0.tgz","fileCount":23,"unpackedSize":66141,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDzaJpvXF6Tk5H8NbzQLhbb5dyrm70zzWhRumPOt/a9RAIgBe+kL2/BnJ5RxUbIpkaQXuc9YsMz53VFkOWAu6t93Q4="}]},"_npmUser":{"name":"tsangwailam","email":"tsangwailam@gmail.com"},"directories":{},"maintainers":[{"name":"tsangwailam","email":"tsangwailam@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/registry-client-ts_0.3.0_1787937344435_0.019712308976676196"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-20T14:52:13.598Z","modified":"2026-08-28T17:15:44.768Z","0.2.0":"2026-08-20T14:52:13.930Z","0.2.1":"2026-08-21T18:39:58.969Z","0.3.0":"2026-08-28T17:15:44.560Z"},"bugs":{"url":"https://github.com/a2a-lib/a2a-registry-client-ts/issues"},"license":"Apache-2.0","homepage":"https://github.com/a2a-lib/a2a-registry-client-ts#readme","keywords":["a2a","a2a-lib","a2a-registry-server","a2a-registry-client","typescript","client","agent","agent2agent","agent-registry","service-discovery"],"repository":{"type":"git","url":"git+https://github.com/a2a-lib/a2a-registry-client-ts.git"},"description":"TypeScript client and lease manager for the A2A Registry Server","maintainers":[{"name":"tsangwailam","email":"tsangwailam@gmail.com"}],"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-lib/registry-client-ts\n```\n\nNode.js 22 or newer is required.\n\n## Server information\n\nUse `getServerInfo()` to inspect the connected server without making a\nregistry mutation. It returns the server version, API version, readiness\nstatus, backing store, documentation URL, and advertised endpoint paths.\n\n```ts\nconst info = await registry.getServerInfo();\nconsole.log(info.version, info.apiVersion, info.status, info.store);\n```\n\n## Discover agents\n\n```ts\nimport { RegistryClient } from \"@a2a-lib/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\nRegistrations may include an optional server-side HTTP or TCP `healthCheck`;\nprobe results are returned as `instance.health` without extending the TTL\nlease. Use `client.watch({ after })` to consume revisioned SSE snapshots.\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-lib/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"}