SDK API

Complete reference for the SDK class.

For detailed ID format documentation, see Models Reference.

Initialization

Python

sdk = SDK(
    chainId: ChainId,
    rpcUrl: str,
    signer: Optional[Any] = None,
    registryOverrides: Optional[Dict] = None,
    indexingStore: Optional[Any] = None,
    embeddings: Optional[Any] = None,
    ipfs: Optional[str] = None,
    ipfsNodeUrl: Optional[str] = None,
    filecoinPrivateKey: Optional[str] = None,
    pinataJwt: Optional[str] = None,
    subgraphUrl: Optional[str] = None,
    subgraphOverrides: Optional[Dict[ChainId, str]] = None
)

TypeScript

import { SDK, type SDKConfig } from 'agent0-sdk';

const sdk = new SDK({
  chainId: number,
  rpcUrl: string,
  signer?: string, // Private key (optional for read-only operations)
  registryOverrides?: Record<number, Record<string, string>>,
  ipfs?: 'node' | 'filecoinPin' | 'pinata',
  ipfsNodeUrl?: string,
  filecoinPrivateKey?: string,
  pinataJwt?: string,
  subgraphUrl?: string,
  subgraphOverrides?: Record<number, string>
});

Agent Methods

createAgent

Create a new agent.

Python

agent = sdk.createAgent(
    name: str,
    description: str,
    image: Optional[str] = None
) -> Agent

TypeScript

import { SDK, Agent } from 'agent0-sdk';

const agent: Agent = sdk.createAgent(
  name: string,
  description: string,
  image?: string
);

loadAgent

Load an existing agent by ID.

Python

agent = sdk.loadAgent(agentId: str) -> Agent

TypeScript

import { SDK, Agent } from 'agent0-sdk';
import type { AgentId } from 'agent0-sdk';

const agent: Agent = await sdk.loadAgent(agentId: AgentId);

Discovery Methods

searchAgents

Search for agents with filters.

Python

results = sdk.searchAgents(
    params: Union[SearchParams, Dict, None] = None,
    sort: List[str] = None,
    page_size: int = 50,
    cursor: Optional[str] = None,
    **kwargs
) -> Dict[str, Any]

TypeScript

import { SDK } from 'agent0-sdk';
import type { SearchParams, AgentSummary } from 'agent0-sdk';

const results: { items: AgentSummary[]; nextCursor?: string } = await sdk.searchAgents(
  params?: SearchParams,
  sort?: string[],
  pageSize?: number,
  cursor?: string
);

getAgent

Get a single agent summary.

Python

agent = sdk.getAgent(agentId: str) -> AgentSummary

TypeScript

import { SDK } from 'agent0-sdk';
import type { AgentId, AgentSummary } from 'agent0-sdk';

const agent: AgentSummary | null = await sdk.getAgent(agentId: AgentId);

Feedback Methods

signFeedbackAuth

Sign feedback authorization for a client.

Python

auth = sdk.signFeedbackAuth(
    agentId: str,
    clientAddress: str,
    indexLimit: Optional[int] = None,
    expiryHours: int = 24
) -> bytes

TypeScript

import { SDK } from 'agent0-sdk';
import type { AgentId, Address } from 'agent0-sdk';

const auth: string = await sdk.signFeedbackAuth(
  agentId: AgentId,
  clientAddress: Address,
  indexLimit?: number,
  expiryHours?: number
);

prepareFeedback

Prepare a feedback file.

Python

feedback = sdk.prepareFeedback(
    agentId: str,
    score: Optional[int] = None,
    tags: List[str] = None,
    text: Optional[str] = None,
    capability: Optional[str] = None,
    name: Optional[str] = None,
    skill: Optional[str] = None,
    task: Optional[str] = None,
    context: Optional[Dict] = None,
    proofOfPayment: Optional[Dict] = None,
    extra: Optional[Dict] = None
) -> Dict

TypeScript

import { SDK } from 'agent0-sdk';
import type { AgentId } from 'agent0-sdk';

const feedbackFile: Record<string, unknown> = sdk.prepareFeedback(
  agentId: AgentId,
  score?: number,
  tags?: string[],
  text?: string,
  capability?: string,
  name?: string,
  skill?: string,
  task?: string,
  context?: Record<string, unknown>,
  proofOfPayment?: Record<string, unknown>,
  extra?: Record<string, unknown>
);

giveFeedback

Give feedback on-chain.

Python

feedback = sdk.giveFeedback(
    agentId: str,
    feedbackFile: Dict,
    idem: Optional[str] = None,
    feedbackAuth: Optional[bytes] = None
) -> Feedback

TypeScript

import { SDK } from 'agent0-sdk';
import type { AgentId, Feedback } from 'agent0-sdk';

const feedback: Feedback = await sdk.giveFeedback(
  agentId: AgentId,
  feedbackFile: Record<string, unknown>,
  feedbackAuth?: string
);

getFeedback

Get single feedback.

Python

feedback = sdk.getFeedback(feedbackId: str) -> Feedback

TypeScript

import { SDK } from 'agent0-sdk';
import type { AgentId, Address, Feedback } from 'agent0-sdk';

const feedback: Feedback = await sdk.getFeedback(
  agentId: AgentId,
  clientAddress: Address,
  feedbackIndex: number
);

Note: feedbackIndex in the feedback ID is 1-based (first feedback = 1, second = 2, etc.)

TypeScript Note: TypeScript SDK takes separate parameters instead of a single feedbackId string.

searchFeedback

Search feedback with filters.

Python

results = sdk.searchFeedback(
    agentId: str,
    tags: Optional[List[str]] = None,
    capabilities: Optional[List[str]] = None,
    skills: Optional[List[str]] = None,
    minScore: Optional[int] = None,
    maxScore: Optional[int] = None,
    first: int = 100,
    skip: int = 0
) -> List[Feedback]

TypeScript

import { SDK } from 'agent0-sdk';
import type { AgentId, Feedback } from 'agent0-sdk';

const results: Feedback[] = await sdk.searchFeedback(
  agentId: AgentId,
  tags?: string[],
  capabilities?: string[],
  skills?: string[],
  minScore?: number,
  maxScore?: number
);

searchAgentsByReputation

Find agents by reputation.

Python

results = sdk.searchAgentsByReputation(
    tags: Optional[List[str]] = None,
    capabilities: Optional[List[str]] = None,
    skills: Optional[List[str]] = None,
    minAverageScore: Optional[float] = None
) -> Dict

TypeScript

import { SDK } from 'agent0-sdk';
import type { AgentId, AgentSummary, Address } from 'agent0-sdk';

const results: { items: AgentSummary[]; nextCursor?: string } = await sdk.searchAgentsByReputation(
  agents?: AgentId[],
  tags?: string[],
  reviewers?: Address[],
  capabilities?: string[],
  skills?: string[],
  tasks?: string[],
  names?: string[],
  minAverageScore?: number,
  includeRevoked?: boolean,
  pageSize?: number,
  cursor?: string,
  sort?: string[]
);

revokeFeedback

Revoke feedback.

Python

result = sdk.revokeFeedback(
    agentId: str,
    feedbackIndex: int
) -> Feedback

TypeScript

import { SDK } from 'agent0-sdk';
import type { AgentId } from 'agent0-sdk';

const txHash: string = await sdk.revokeFeedback(
  agentId: AgentId,
  feedbackIndex: number
);

TypeScript Note: Returns transaction hash string, not Feedback object.

appendResponse

Append response to feedback.

Python

feedback = sdk.appendResponse(
    agentId: str,
    clientAddress: str,
    feedbackIndex: int,
    response: Dict
) -> Feedback

TypeScript

import { SDK } from 'agent0-sdk';
import type { AgentId, Address, URI } from 'agent0-sdk';

const txHash: string = await sdk.appendResponse(
  agentId: AgentId,
  clientAddress: Address,
  feedbackIndex: number,
  response: { uri: URI; hash: string }
);

TypeScript Note: Returns transaction hash string, not Feedback object. Response parameter is an object with uri and hash properties.

getReputationSummary

Get reputation summary for an agent.

Python

summary = sdk.getReputationSummary(
    agentId: str
) -> Dict

TypeScript

import { SDK } from 'agent0-sdk';
import type { AgentId } from 'agent0-sdk';

const summary: { count: number; averageScore: number } = await sdk.getReputationSummary(
  agentId: AgentId,
  tag1?: string,
  tag2?: string
);

Transfer Methods

transferAgent

Transfer agent ownership to a new address.

Python

result = sdk.transferAgent(
    agentId: str,
    newOwnerAddress: str
) -> Dict[str, Any]

TypeScript

import { SDK } from 'agent0-sdk';
import type { AgentId, Address } from 'agent0-sdk';

const result: {
  txHash: string;
  from: Address;
  to: Address;
  agentId: AgentId;
} = await sdk.transferAgent(
  agentId: AgentId,
  newOwner: Address
);

Parameters:

• agentId (str / AgentId): The agent ID to transfer
• newOwnerAddress / newOwner (str / Address): Ethereum address of the new owner

Returns:

• Python: Dict[str, Any] containing:
  • txHash (str): Transaction hash
  • from (str): Previous owner address
  • to (str): New owner address
  • agentId (str): Agent ID that was transferred
• TypeScript: Object with typed fields { txHash: string; from: Address; to: Address; agentId: AgentId }

Raises/Throws:

• Python: ValueError: If agent not found or transfer not allowed
• TypeScript: Error: If agent not found or transfer not allowed

Example:

Python

# Transfer agent using SDK method
result = sdk.transferAgent(
    agentId="11155111:123",
    newOwnerAddress="0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6"
)

print(f"Transfer successful: {result['txHash']}")
print(f"New owner: {result['to']}")

TypeScript

// Transfer agent using SDK method
const result = await sdk.transferAgent(
  "11155111:123",
  "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6"
);

console.log(`Transfer successful: ${result.txHash}`);
console.log(`New owner: ${result.to}`);

Comparison with Agent.transfer():

• sdk.transferAgent() is a convenience method that loads the agent first
• agent.transfer() works directly on an existing agent instance
• Both methods perform the same validation and transfer logic
• Use sdk.transferAgent() when you only have the agent ID
• Use agent.transfer() when you already have an agent instance

Important Notes:

• Only the current owner can transfer the agent
• Agent URI, metadata, and all other data remain unchanged
• Transfer is irreversible - ensure the new owner is correct
• Invalid addresses and self-transfers are automatically rejected
• Address validation includes checksum format verification

Owner Utility Methods

getAgentOwner

Get the current owner of an agent.

Python

owner = sdk.getAgentOwner(agentId: str) -> str

TypeScript

import { SDK } from 'agent0-sdk';
import type { AgentId, Address } from 'agent0-sdk';

const owner: Address = await sdk.getAgentOwner(agentId: AgentId);

Parameters:

• agentId (str / AgentId): The agent ID to check

Returns:

• Python: str - The current owner’s Ethereum address
• TypeScript: Address - The current owner’s Ethereum address

Raises/Throws:

• Python: ValueError: If agent ID is invalid or agent doesn’t exist
• TypeScript: Error: If agent ID is invalid or agent doesn’t exist

Example:

Python

owner = sdk.getAgentOwner("11155111:123")
print(f"Current owner: {owner}")

TypeScript

const owner = await sdk.getAgentOwner("11155111:123");
console.log(`Current owner: ${owner}`);

isAgentOwner

Check if an address is the owner of an agent.

Python

is_owner = sdk.isAgentOwner(
    agentId: str,
    address: Optional[str] = None
) -> bool

TypeScript

import { SDK } from 'agent0-sdk';
import type { AgentId, Address } from 'agent0-sdk';

const isOwner: boolean = await sdk.isAgentOwner(
  agentId: AgentId,
  address: Address
);

Parameters:

• agentId (str / AgentId): The agent ID to check
• address (str / Address, optional in Python, required in TypeScript): Address to check (Python defaults to SDK’s signer address)

Returns:

• bool: True if the address is the owner, False otherwise

Raises/Throws:

• Python: ValueError: If agent ID is invalid or agent doesn’t exist
• TypeScript: Error: If agent ID is invalid or agent doesn’t exist

Example:

Python

# Check if current signer is owner
is_owner = sdk.isAgentOwner("11155111:123")

# Check if specific address is owner
is_owner = sdk.isAgentOwner("11155111:123", "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6")

TypeScript

// Check if specific address is owner (address is required in TypeScript)
const isOwner = await sdk.isAgentOwner(
  "11155111:123",
  "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6"
);

canTransferAgent

Check if an address can transfer an agent (i.e., is the owner).

Python

can_transfer = sdk.canTransferAgent(
    agentId: str,
    address: Optional[str] = None
) -> bool

TypeScript

// Note: This method is not available in TypeScript SDK
// Use isAgentOwner instead, which serves the same purpose
const canTransfer = await sdk.isAgentOwner(agentId, address);

TypeScript Note: This method is not available in the TypeScript SDK. Use isAgentOwner() instead, which serves the same purpose.

Parameters:

• agentId (str): The agent ID to check
• address (str, optional): Address to check (defaults to SDK’s signer address)

Returns:

• bool: True if the address can transfer the agent, False otherwise

Example:

Python

# Check if current signer can transfer
can_transfer = sdk.canTransferAgent("11155111:123")

# Check if specific address can transfer
can_transfer = sdk.canTransferAgent("11155111:123", "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6")

TypeScript

// Use isAgentOwner as equivalent
const canTransfer = await sdk.isAgentOwner(
  "11155111:123",
  "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6"
);

Utility Methods

chain_id / chainId

Get current chain ID.

Python

chain_id = sdk.chain_id() -> int

TypeScript

import { SDK } from 'agent0-sdk';
import type { ChainId } from 'agent0-sdk';

const chainId: ChainId = await sdk.chainId();

TypeScript Note: Method is async and uses camelCase naming.

registries

Get registry addresses.

Python

registries = sdk.registries() -> Dict[str, str]

TypeScript

import { SDK } from 'agent0-sdk';
import type { Address } from 'agent0-sdk';

const registries: Record<string, Address> = sdk.registries();

set_chain

Switch to a different chain.

Python

sdk.set_chain(chain_id: int) -> None

TypeScript

// Note: This method is not available in TypeScript SDK
// Create a new SDK instance with the desired chainId instead
const sdk = new SDK({
  chainId: newChainId,
  rpcUrl: newRpcUrl,
  // ... other config
});

TypeScript Note: This method is not available in the TypeScript SDK. Create a new SDK instance with the desired chainId instead.

isReadOnly

Check if SDK is in read-only mode.

Python

is_readonly = sdk.isReadOnly -> bool

TypeScript

import { SDK } from 'agent0-sdk';

const isReadOnly: boolean = sdk.isReadOnly;

TypeScript Note: Property access (not a method), uses camelCase naming.