agent0-sdk 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Marco De Rossi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,234 @@
+# Agent0 SDK
+
+Agent0 is the TypeScript SDK for agentic economies. It enables agents to register, advertise their capabilities and how to communicate with them, and give each other feedback and reputation signals. All this using blockchain infrastructure (ERC-8004) and decentralized storage, enabling permissionless discovery without relying on proprietary catalogues or intermediaries.
+
+## What Does Agent0 SDK Do?
+
+Agent0 SDK v0.21 enables you to:
+
+- **Create and manage agent identities** - Register your AI agent on-chain with a unique identity, configure presentation fields (name, description, image), set wallet addresses, and manage trust models with x402 support
+- **Advertise agent capabilities** - Publish MCP and A2A endpoints, with automated extraction of MCP tools and A2A skills from endpoints
+- **Enable permissionless discovery** - Make your agent discoverable by other agents and platforms using rich search by attributes, capabilities, skills, tools, tasks, and x402 support
+- **Build reputation** - Give and receive feedback, retrieve feedback history, and search agents by reputation with cryptographic authentication
+- **Cross-chain registration** - One-line registration with IPFS nodes, Pinata, Filecoin, or HTTP URIs
+- **Public indexing** - Subgraph indexing both on-chain and IPFS data for fast search and retrieval
+
+## ⚠️ Alpha Release
+
+Agent0 SDK v0.21 is in **alpha** with bugs and is not production ready. We're actively testing and improving it.
+
+**Bug reports & feedback:** GitHub: [Report issues](https://github.com/agent0lab/agent0-ts/issues) | Telegram: [@marcoderossi](https://t.me/marcoderossi) | Email: marco.derossi@consensys.net
+
+## Installation
+
+### Prerequisites
+
+- Node.js 18 or higher
+- npm or yarn package manager
+- Private key for signing transactions (or run in read-only mode)
+- Access to an Ethereum RPC endpoint (e.g., Alchemy, Infura)
+- (Optional) IPFS provider account (Pinata, Filecoin, or local IPFS node)
+
+### Install from npm
+
+```bash
+npm install agent0-sdk
+```
+
+### Install from Source
+
+```bash
+git clone https://github.com/agent0lab/agent0-ts.git
+cd agent0-ts
+npm install
+npm run build
+```
+
+## Quick Start
+
+### 1. Initialize SDK
+
+```typescript
+import { SDK } from 'agent0-sdk';
+
+// Initialize SDK with IPFS and subgraph
+const sdk = new SDK({
+  chainId: 11155111, // Ethereum Sepolia testnet
+  rpcUrl: process.env.RPC_URL!,
+  signer: process.env.PRIVATE_KEY, // Optional: for write operations
+  ipfs: 'pinata', // Options: 'pinata', 'filecoinPin', 'node'
+  pinataJwt: process.env.PINATA_JWT // For Pinata
+  // Subgraph URL auto-defaults from DEFAULT_SUBGRAPH_URLS
+});
+```
+
+### 2. Create and Register Agent
+
+```typescript
+// Create agent
+const agent = sdk.createAgent(
+  'My AI Agent',
+  'An intelligent assistant for various tasks. Skills: data analysis, code generation.',
+  'https://example.com/agent-image.png'
+);
+
+// Configure endpoints (automatically extracts capabilities)
+await agent.setMCP('https://mcp.example.com/'); // Extracts tools, prompts, resources
+await agent.setA2A('https://a2a.example.com/agent-card.json'); // Extracts skills
+agent.setENS('myagent.eth');
+
+// Configure wallet and trust
+agent.setAgentWallet('0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb', 11155111);
+agent.setTrust(true, true, false); // reputation, cryptoEconomic, teeAttestation
+
+// Add metadata and set status
+agent.setMetadata({ version: '1.0.0', category: 'ai-assistant' });
+agent.setActive(true);
+
+// Register on-chain with IPFS
+const registrationFile = await agent.registerIPFS();
+console.log(`Agent registered: ${registrationFile.agentId}`); // e.g., "11155111:123"
+console.log(`Agent URI: ${registrationFile.agentURI}`); // e.g., "ipfs://Qm..."
+```
+
+### 3. Load and Edit Agent
+
+```typescript
+// Load existing agent for editing
+const agent = await sdk.loadAgent('11155111:123'); // Format: "chainId:agentId"
+
+// Edit agent properties
+agent.updateInfo(undefined, 'Updated description with new capabilities', undefined);
+await agent.setMCP('https://new-mcp.example.com/');
+
+// Re-register to update on-chain
+await agent.registerIPFS();
+console.log(`Updated: ${agent.agentURI}`);
+```
+
+### 4. Search Agents
+
+```typescript
+// Search by name, capabilities, or attributes
+const results = await sdk.searchAgents({
+  name: 'AI', // Substring search
+  mcpTools: ['code_generation'], // Specific MCP tools
+  a2aSkills: ['python'], // Specific A2A skills
+  active: true, // Only active agents
+  x402support: true // Payment support
+});
+
+for (const agent of results.items) {
+  console.log(`${agent.name}: ${agent.description}`);
+  console.log(`  Tools: ${agent.mcpTools?.join(', ')}`);
+  console.log(`  Skills: ${agent.a2aSkills?.join(', ')}`);
+}
+
+// Get single agent (read-only, faster)
+const agentSummary = await sdk.getAgent('11155111:123');
+```
+
+### 5. Give and Retrieve Feedback
+
+```typescript
+// Prepare feedback (only score is mandatory)
+const feedbackFile = sdk.prepareFeedback(
+  '11155111:123',
+  85, // 0-100 (mandatory)
+  ['data_analyst', 'finance'], // Optional: tags
+  undefined, // Optional: text
+  'tools', // Optional: capability (MCP capability)
+  'code_generation', // Optional: name (MCP tool name)
+  'python' // Optional: skill (A2A skill)
+);
+
+// Give feedback
+const feedback = await sdk.giveFeedback('11155111:123', feedbackFile);
+
+// Search feedback
+const feedbackResults = await sdk.searchFeedback(
+  '11155111:123',
+  undefined, // tags
+  ['tools'], // capabilities
+  undefined, // skills
+  80, // minScore
+  100 // maxScore
+);
+
+// Get reputation summary
+const summary = await sdk.getReputationSummary('11155111:123');
+console.log(`Average score: ${summary.averageScore}`);
+```
+
+## IPFS Configuration Options
+
+```typescript
+// Option 1: Filecoin Pin (free for ERC-8004 agents)
+const sdk = new SDK({
+  chainId: 11155111,
+  rpcUrl: '...',
+  signer: privateKey,
+  ipfs: 'filecoinPin',
+  filecoinPrivateKey: 'your-filecoin-private-key'
+});
+
+// Option 2: IPFS Node
+const sdk = new SDK({
+  chainId: 11155111,
+  rpcUrl: '...',
+  signer: privateKey,
+  ipfs: 'node',
+  ipfsNodeUrl: 'https://ipfs.infura.io:5001'
+});
+
+// Option 3: Pinata (free for ERC-8004 agents)
+const sdk = new SDK({
+  chainId: 11155111,
+  rpcUrl: '...',
+  signer: privateKey,
+  ipfs: 'pinata',
+  pinataJwt: 'your-pinata-jwt-token'
+});
+
+// Option 4: HTTP registration (no IPFS)
+const sdk = new SDK({ chainId: 11155111, rpcUrl: '...', signer: privateKey });
+await agent.registerHTTP('https://example.com/agent-registration.json');
+```
+
+## 🚀 Coming Soon
+
+- More chains (currently Ethereum Sepolia only)
+- Support for validations
+- Multi-chain agents search
+- Enhanced x402 payments
+- Semantic/Vectorial search
+- Advanced reputation aggregation
+- Import/Export to centralized catalogues
+
+## Examples
+
+Complete working examples are available in the `examples/` directory:
+
+- `quick-start.ts` - Basic agent creation and registration
+- `agent-update.ts` - Agent registration with IPFS
+- `feedback-usage.ts` - Complete feedback flow with IPFS storage
+- `search-agents.ts` - Agent search and discovery
+- `transfer-agent.ts` - Agent ownership transfer
+
+## Documentation
+
+Full documentation is available at [sdk.ag0.xyz](https://sdk.ag0.xyz), including:
+
+- [Installation Guide](https://sdk.ag0.xyz/2-usage/2-1-install/)
+- [Agent Configuration](https://sdk.ag0.xyz/2-usage/2-2-configure-agents/)
+- [Registration](https://sdk.ag0.xyz/2-usage/2-3-registration-ipfs/)
+- [Search](https://sdk.ag0.xyz/2-usage/2-5-search/)
+- [Feedback](https://sdk.ag0.xyz/2-usage/2-6-use-feedback/)
+- [Key Concepts](https://sdk.ag0.xyz/1-welcome/1-2-key-concepts/)
+- [API Reference](https://sdk.ag0.xyz/5-reference/5-1-sdk/)
+
+## License
+
+Agent0 SDK is MIT-licensed public good brought to you by Marco De Rossi in collaboration with Consensys, 🦊 MetaMask and Agent0, Inc. We are looking for co-maintainers. Please reach out if you want to help.
+
+Thanks also to Edge & Node (The Graph), Protocol Labs and Pinata for their support.

package/dist/core/agent.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Agent class for managing individual agents
+ */
+import type { RegistrationFile } from '../models/interfaces';
+import type { AgentId, Address, URI } from '../models/types';
+import type { SDK } from './sdk';
+/**
+ * Agent class for managing individual agents
+ */
+export declare class Agent {
+    private sdk;
+    private registrationFile;
+    private _endpointCrawler;
+    private _dirtyMetadata;
+    private _lastRegisteredWallet?;
+    private _lastRegisteredEns?;
+    constructor(sdk: SDK, registrationFile: RegistrationFile);
+    get agentId(): AgentId | undefined;
+    get agentURI(): URI | undefined;
+    get name(): string;
+    get description(): string;
+    get image(): URI | undefined;
+    get mcpEndpoint(): string | undefined;
+    get a2aEndpoint(): string | undefined;
+    get ensEndpoint(): string | undefined;
+    get walletAddress(): Address | undefined;
+    get mcpTools(): string[] | undefined;
+    get mcpPrompts(): string[] | undefined;
+    get mcpResources(): string[] | undefined;
+    get a2aSkills(): string[] | undefined;
+    setMCP(endpoint: string, version?: string, autoFetch?: boolean): Promise<this>;
+    setA2A(agentcard: string, version?: string, autoFetch?: boolean): Promise<this>;
+    setENS(name: string, version?: string): this;
+    setAgentWallet(address: Address, chainId: number): this;
+    setActive(active: boolean): this;
+    setX402Support(x402Support: boolean): this;
+    setTrust(reputation?: boolean, cryptoEconomic?: boolean, teeAttestation?: boolean): this;
+    setMetadata(kv: Record<string, unknown>): this;
+    getMetadata(): Record<string, unknown>;
+    delMetadata(key: string): this;
+    getRegistrationFile(): RegistrationFile;
+    /**
+     * Update basic agent information
+     */
+    updateInfo(name?: string, description?: string, image?: URI): this;
+    /**
+     * Register agent on-chain with IPFS flow
+     */
+    registerIPFS(): Promise<RegistrationFile>;
+    /**
+     * Register agent on-chain with HTTP URI
+     */
+    registerHTTP(agentUri: string): Promise<RegistrationFile>;
+    /**
+     * Set agent URI (for updates)
+     */
+    setAgentUri(agentUri: string): Promise<void>;
+    /**
+     * Transfer agent ownership
+     */
+    transfer(newOwner: Address): Promise<{
+        txHash: string;
+        from: Address;
+        to: Address;
+        agentId: AgentId;
+    }>;
+    /**
+     * Private helper methods
+     */
+    private _registerWithoutUri;
+    private _registerWithUri;
+    private _updateMetadataOnChain;
+    private _collectMetadataForRegistration;
+    private _extractAgentIdFromReceipt;
+}
+//# sourceMappingURL=agent.d.ts.map

package/dist/core/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/core/agent.ts"],"names":[],"mappings":"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"}