Agent API

Complete reference for the Agent class.

Properties

All properties are read-only. Use setter methods to modify values.

Python

# Identity
agent.agentId           # Optional[str]
agent.agentURI          # Optional[str]
agent.name              # str
agent.description       # str
agent.image             # Optional[str]

# Status
agent.active            # bool
agent.x402support       # bool
agent.updatedAt         # int

# Wallet
agent.walletAddress     # Optional[str]
agent.walletChainId     # Optional[int]

# Endpoints
agent.mcpEndpoint       # Optional[str]
agent.a2aEndpoint       # Optional[str]
agent.ensEndpoint       # Optional[str]

# Capabilities
agent.mcpTools          # Optional[List[str]]
agent.mcpPrompts        # Optional[List[str]]
agent.mcpResources      # Optional[List[str]]
agent.a2aSkills         # Optional[List[str]]

# Lists
agent.endpoints         # List[Endpoint]
agent.trustModels       # List[TrustModel]
agent.metadata          # Dict[str, Any]
agent.owners            # List[str]
agent.operators         # List[str]

TypeScript

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

// Identity
agent.agentId          // AgentId | undefined
agent.agentURI         // URI | undefined
agent.name             // string
agent.description      // string
agent.image            // URI | undefined

// Status
agent.active           // boolean
agent.x402support      // boolean
// Note: updatedAt is in registrationFile.updatedAt

// Wallet
agent.walletAddress    // Address | undefined
agent.walletChainId    // number | undefined

// Endpoints
agent.mcpEndpoint      // string | undefined
agent.a2aEndpoint       // string | undefined
agent.ensEndpoint      // string | undefined

// Capabilities
agent.mcpTools         // string[] | undefined
agent.mcpPrompts       // string[] | undefined
agent.mcpResources     // string[] | undefined
agent.a2aSkills        // string[] | undefined

// Access via getRegistrationFile()
const regFile = agent.getRegistrationFile();
regFile.endpoints      // Endpoint[]
regFile.trustModels    // (TrustModel | string)[]
regFile.metadata       // Record<string, unknown>
regFile.owners         // Address[]
regFile.operators      // Address[]

Endpoint Methods

setMCP

Set MCP endpoint.

Python

agent = agent.setMCP(
    endpoint: str,
    version: str = "2025-06-18",
    auto_fetch: bool = True
) -> Agent

TypeScript

import { Agent } from 'agent0-sdk';

const agent: Agent = await agent.setMCP(
  endpoint: string,
  version?: string,
  autoFetch?: boolean
);

TypeScript Note: Method is async and returns Promise<this> for chaining.

setA2A

Set A2A endpoint.

Python

agent = agent.setA2A(
    agentcard: str,
    version: str = "0.30",
    auto_fetch: bool = True
) -> Agent

TypeScript

import { Agent } from 'agent0-sdk';

const agent: Agent = await agent.setA2A(
  agentcard: string,
  version?: string,
  autoFetch?: boolean
);

TypeScript Note: Method is async and returns Promise<this> for chaining.

setENS

Set ENS endpoint.

Python

agent = agent.setENS(name: str, version: str = "1.0") -> Agent

TypeScript

import { Agent } from 'agent0-sdk';

const agent: Agent = agent.setENS(
  name: string,
  version?: string
);

TypeScript Note: Method is synchronous and returns this for chaining.

removeEndpoint

Remove endpoint(s).

Python

agent = agent.removeEndpoint(
    type: Optional[EndpointType] = None,
    value: Optional[str] = None
) -> Agent

TypeScript

// Note: This method is not available in TypeScript SDK
// Manually filter endpoints from registrationFile instead:
const regFile = agent.getRegistrationFile();
regFile.endpoints = regFile.endpoints.filter(
  ep => !(ep.type === endpointType && ep.value === value)
);

TypeScript Note: This method is not available in the TypeScript SDK. Manually filter endpoints from the registration file instead.

removeEndpoints

Remove all endpoints.

Python

agent = agent.removeEndpoints() -> Agent

TypeScript

// Note: This method is not available in TypeScript SDK
// Manually clear endpoints from registrationFile instead:
const regFile = agent.getRegistrationFile();
regFile.endpoints = [];

TypeScript Note: This method is not available in the TypeScript SDK. Manually clear endpoints from the registration file instead.

Trust Model Methods

setTrust

Set trust models using keywords.

Python

agent = agent.setTrust(
    reputation: bool = False,
    cryptoEconomic: bool = False,
    teeAttestation: bool = False
) -> Agent

TypeScript

import { Agent } from 'agent0-sdk';

const agent: Agent = agent.setTrust(
  reputation?: boolean,
  cryptoEconomic?: boolean,
  teeAttestation?: boolean
);

TypeScript Note: Method is synchronous and returns this for chaining.

trustModels

Set trust models directly.

Python

agent = agent.trustModels(
    models: List[Union[TrustModel, str]]
) -> Agent

TypeScript

// Note: This method is not available in TypeScript SDK
// Manually set trustModels on registrationFile instead:
import type { TrustModel } from 'agent0-sdk';

const regFile = agent.getRegistrationFile();
regFile.trustModels = models; // (TrustModel | string)[]

TypeScript Note: This method is not available in the TypeScript SDK. Manually set trustModels on the registration file instead.

Info Methods

updateInfo

Update basic agent information.

Python

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

TypeScript

import { Agent } from 'agent0-sdk';
import type { URI } from 'agent0-sdk';

const agent: Agent = agent.updateInfo(
  name?: string,
  description?: string,
  image?: URI
);

TypeScript Note: Method is synchronous and returns this for chaining.

setAgentWallet

Set agent wallet.

Python

agent = agent.setAgentWallet(
    addr: Optional[str],
    chainId: Optional[int] = None
) -> Agent

TypeScript

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

const agent: Agent = agent.setAgentWallet(
  address: Address,
  chainId: number
);

TypeScript Note: Method is synchronous, both parameters are required (not optional), and returns this for chaining.

setActive

Set active status.

Python

agent = agent.setActive(active: bool) -> Agent

TypeScript

import { Agent } from 'agent0-sdk';

const agent: Agent = agent.setActive(active: boolean);

TypeScript Note: Method is synchronous and returns this for chaining.

setX402Support

Set x402 support.

Python

agent = agent.setX402Support(x402Support: bool) -> Agent

TypeScript

import { Agent } from 'agent0-sdk';

const agent: Agent = agent.setX402Support(x402Support: boolean);

TypeScript Note: Method is synchronous and returns this for chaining.

Metadata Methods

setMetadata

Set metadata.

Python

agent = agent.setMetadata(kv: Dict[str, Any]) -> Agent

TypeScript

import { Agent } from 'agent0-sdk';

const agent: Agent = agent.setMetadata(
  kv: Record<string, unknown>
);

TypeScript Note: Method is synchronous and returns this for chaining.

getMetadata

Get metadata.

Python

metadata = agent.getMetadata() -> Dict[str, Any]

TypeScript

import { Agent } from 'agent0-sdk';

const metadata: Record<string, unknown> = agent.getMetadata();

delMetadata

Delete a metadata key.

Python

agent = agent.delMetadata(key: str) -> Agent

TypeScript

import { Agent } from 'agent0-sdk';

const agent: Agent = agent.delMetadata(key: string);

TypeScript Note: Method is synchronous and returns this for chaining.

Registration Methods

registerIPFS

Register with IPFS (recommended).

Python

reg_file = agent.registerIPFS() -> RegistrationFile

TypeScript

import { Agent } from 'agent0-sdk';
import type { RegistrationFile } from 'agent0-sdk';

const regFile: RegistrationFile = await agent.registerIPFS();

TypeScript Note: Method is async and returns Promise<RegistrationFile>.

register

Register with direct URI.

Python

reg_file = agent.register(agentUri: str) -> RegistrationFile

TypeScript

import { Agent } from 'agent0-sdk';
import type { RegistrationFile, URI } from 'agent0-sdk';

const regFile: RegistrationFile = await agent.registerHTTP(
  agentUri: URI
);

TypeScript Note: Method is named registerHTTP in TypeScript SDK and is async.

updateRegistration

Update registration after edits.

Python

reg_file = agent.updateRegistration(
    agentURI: Optional[str] = None,
    idem: Optional[str] = None
) -> RegistrationFile

TypeScript

// Note: This method is not available in TypeScript SDK
// Use registerIPFS() again to update existing registration:
const regFile = await agent.registerIPFS();
// Or use setAgentUri() to update URI:
await agent.setAgentUri(newUri);

TypeScript Note: This method is not available in the TypeScript SDK. Use registerIPFS() again to update an existing registration, or setAgentUri() to update the URI.

setAgentUri

Set agent URI locally.

Python

agent = agent.setAgentUri(uri: str) -> Agent

TypeScript

import { Agent } from 'agent0-sdk';
import type { URI } from 'agent0-sdk';

await agent.setAgentUri(uri: URI);

TypeScript Note: Method is async and updates the URI on-chain (not just locally).

Ownership Methods

transfer

Transfer ownership.

Python

result = agent.transfer(
    to: str,
    approve_operator: bool = False,
    idem: Optional[str] = None
) -> Dict

TypeScript

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

const result: {
  txHash: string;
  from: Address;
  to: Address;
  agentId: AgentId;
} = await agent.transfer(
  newOwner: Address
);

TypeScript Note: Method is async, only takes newOwner parameter (no approve_operator or idem), and returns typed object.

Parameters:

• to / 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 is not registered, address is invalid, or caller is not the owner
• TypeScript: Error: If agent is not registered, address is invalid, or caller is not the owner

Example:

Python

# Transfer agent to new owner
new_owner = "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6"
result = agent.transfer(new_owner)

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

TypeScript

// Transfer agent to new owner
const newOwner = "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6";
const result = await agent.transfer(newOwner);

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

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

addOperator

Add operator.

Python

result = agent.addOperator(
    operator: str,
    idem: Optional[str] = None
) -> Dict

TypeScript

// Note: This method is not available in TypeScript SDK
// Use SDK's web3Client to interact with Identity Registry directly

TypeScript Note: This method is not available in the TypeScript SDK. Use the SDK’s web3Client to interact with the Identity Registry directly.

removeOperator

Remove operator.

Python

result = agent.removeOperator(
    operator: str,
    idem: Optional[str] = None
) -> Dict

TypeScript

// Note: This method is not available in TypeScript SDK
// Use SDK's web3Client to interact with Identity Registry directly

TypeScript Note: This method is not available in the TypeScript SDK. Use the SDK’s web3Client to interact with the Identity Registry directly.

activate

Activate agent.

Python

reg_file = agent.activate(idem: Optional[str] = None) -> RegistrationFile

TypeScript

// Note: This method is not available in TypeScript SDK
// Use setActive(true) and registerIPFS() instead:
agent.setActive(true);
const regFile = await agent.registerIPFS();

TypeScript Note: This method is not available in the TypeScript SDK. Use setActive(true) and registerIPFS() instead.

deactivate

Deactivate agent.

Python

reg_file = agent.deactivate(idem: Optional[str] = None) -> RegistrationFile

TypeScript

// Note: This method is not available in TypeScript SDK
// Use setActive(false) and registerIPFS() instead:
agent.setActive(false);
const regFile = await agent.registerIPFS();

TypeScript Note: This method is not available in the TypeScript SDK. Use setActive(false) and registerIPFS() instead.

Utility Methods

getRegistrationFile

Get registration file.

Python

reg_file = agent.getRegistrationFile() -> RegistrationFile

TypeScript

import { Agent } from 'agent0-sdk';
import type { RegistrationFile } from 'agent0-sdk';

const regFile: RegistrationFile = agent.getRegistrationFile();

toJson

Convert to JSON.

Python

json_str = agent.toJson() -> str

TypeScript

// Note: This method is not available in TypeScript SDK
// Use JSON.stringify() on registrationFile instead:
const regFile = agent.getRegistrationFile();
const jsonStr = JSON.stringify(regFile, null, 2);

TypeScript Note: This method is not available in the TypeScript SDK. Use JSON.stringify() on the registration file instead.

saveToFile

Save to file.

Python

agent.saveToFile(filePath: str) -> None

TypeScript

// Note: This method is not available in TypeScript SDK
// Use Node.js fs module instead:
import * as fs from 'fs';
const regFile = agent.getRegistrationFile();
fs.writeFileSync(filePath, JSON.stringify(regFile, null, 2));

TypeScript Note: This method is not available in the TypeScript SDK. Use Node.js fs module to write the registration file to disk.