Agents

Register, list, update, and delete AI agents with the Grantex TypeScript SDK.

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.agents.length);  // 3 returned
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.