Skip to main content

​
Overview

The agents sub-client manages the lifecycle of AI agents in your Grantex organization. Each agent receives a unique decentralized identifier (DID) and can request scoped grants from users. 
const agent = await grantex.agents.register({
  name: 'travel-booker',
  description: 'Books flights and hotels on behalf of users',
  scopes: ['calendar:read', 'payments:initiate:max_500'],
});

​
agents.register()

Register a new agent with the Grantex service. 
const agent = await grantex.agents.register({
  name: 'travel-booker',
  description: 'Books flights and hotels on behalf of users',
  scopes: ['calendar:read', 'payments:initiate:max_500', 'email:send'],
});

console.log(agent.id);     // 'ag_01HXYZ...'
console.log(agent.did);    // 'did:grantex:ag_01HXYZ...'
console.log(agent.status); // 'active'

​
Parameters

​
name
string
required
Human-readable name for the agent.
​
description
string
required
A description of what the agent does.
​
scopes
string[]
required
The maximum set of scopes this agent can request. Authorization requests must use a subset of these scopes.

​
Response: Agent

​
id
string
Unique agent identifier.
​
did
string
Decentralized identifier (DID) for the agent.
​
name
string
The agent’s display name.
​
description
string
The agent’s description.
​
scopes
string[]
The agent’s registered scopes.
​
status
string
Agent status: 'active', 'suspended', or 'revoked'.
​
developerId
string
The developer organization that owns this agent.
​
createdAt
string
ISO 8601 creation timestamp.
​
updatedAt
string
ISO 8601 last-updated timestamp.

​
agents.get()

Retrieve a single agent by its ID. 
const agent = await grantex.agents.get('ag_01HXYZ...');

console.log(agent.name);   // 'travel-booker'
console.log(agent.scopes); // ['calendar:read', 'payments:initiate:max_500', 'email:send']

​
Parameters

​
agentId
string
required
The agent ID to retrieve.

​
Response

Returns an Agent object.

​
agents.list()

List all agents in your organization. 
const result = await grantex.agents.list();

console.log(result.total);  // 3
for (const agent of result.agents) {
  console.log(`${agent.name} (${agent.status})`);
}

​
Response: ListAgentsResponse

​
agents
Agent[]
Array of agent objects.
​
total
number
Total number of agents.
​
page
number
Current page number.
​
pageSize
number
Number of agents per page.

​
agents.update()

Update an existing agent’s name, description, or scopes. 
const updated = await grantex.agents.update('ag_01HXYZ...', {
  name: 'travel-booker-v2',
  scopes: ['calendar:read', 'calendar:write', 'payments:initiate:max_1000'],
});

console.log(updated.name);   // 'travel-booker-v2'
console.log(updated.scopes); // ['calendar:read', 'calendar:write', 'payments:initiate:max_1000']

​
Parameters

​
agentId
string
required
The agent ID to update.
​
name
string
New display name.
​
description
string
New description.
​
scopes
string[]
New set of registered scopes.

​
Response

Returns the updated Agent object.

​
agents.delete()

Delete an agent. This revokes the agent’s DID and all active grants. 
await grantex.agents.delete('ag_01HXYZ...');
// Returns void -- the agent is permanently removed

​
Parameters

​
agentId
string
required
The agent ID to delete.

​
Response

Returns void.