> ## Documentation Index
> Fetch the complete documentation index at: https://docs.grantex.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents

> Register, retrieve, update, list, and delete AI agents using the Grantex Python SDK.

## Overview

The `agents` client manages AI agent registrations. Each agent has a unique ID, a DID (Decentralized Identifier), a set of scopes it can request, and a lifecycle status.

Access the agents client via `client.agents`.

## Register

Register a new agent with a name and set of scopes:

```python theme={null}
from grantex import Grantex

with Grantex(api_key="gx_live_...") as client:
    agent = client.agents.register(
        name="travel-assistant",
        scopes=["booking:read", "booking:write", "profile:read"],
        description="Books flights and hotels on behalf of users",
    )

    print(f"Agent ID: {agent.id}")
    print(f"Agent DID: {agent.did}")
    print(f"Scopes: {agent.scopes}")
```

### Parameters

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `name` | `str` | Yes | -- | Human-readable name for the agent. |
| `scopes` | `list[str]` | Yes | -- | The scopes this agent can request. |
| `description` | `str` | No | `""` | A description of what the agent does. |

All parameters are keyword-only.

### Returns

An `Agent` dataclass.

## Get

Retrieve a single agent by its ID:

```python theme={null}
agent = client.agents.get("agt_abc123")

print(f"Name: {agent.name}")
print(f"Status: {agent.status}")
print(f"Created: {agent.created_at}")
```

## List

List all agents registered under your developer account:

```python theme={null}
result = client.agents.list()

print(f"Total agents: {len(result.agents)}")
for agent in result.agents:
    print(f"  {agent.name} ({agent.id}) - {agent.status}")
```

### ListAgentsResponse

| Field | Type | Description |
| - | - | - |
| `agents` | `tuple[Agent, ...]` | The list of agents. |
| `total` | `int` | Total number of agents. |
| `page` | `int` | Current page number. |
| `page_size` | `int` | Number of agents per page. |

## Update

Update an agent's name, description, or scopes. Only fields you provide will be modified:

```python theme={null}
updated = client.agents.update(
    "agt_abc123",
    name="travel-assistant-v2",
    description="Updated description",
    scopes=["booking:read", "booking:write", "profile:read", "profile:write"],
)

print(f"Updated at: {updated.updated_at}")
```

### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `agent_id` | `str` | Yes | The ID of the agent to update (positional). |
| `name` | `str \| None` | No | New name for the agent. |
| `description` | `str \| None` | No | New description. |
| `scopes` | `list[str] \| None` | No | New set of scopes. |

## Delete

Delete an agent by its ID:

```python theme={null}
client.agents.delete("agt_abc123")
# Returns None on success
```

## Agent Type

The `Agent` frozen dataclass has the following fields:

| Field | Type | Description |
| - | - | - |
| `id` | `str` | Unique agent identifier. |
| `did` | `str` | Decentralized Identifier for the agent. |
| `name` | `str` | Human-readable agent name. |
| `description` | `str` | Agent description. |
| `scopes` | `tuple[str, ...]` | Scopes this agent can request. |
| `status` | `str` | Agent status (e.g. `"active"`). |
| `developer_id` | `str` | ID of the developer who owns this agent. |
| `created_at` | `str` | ISO 8601 creation timestamp. |
| `updated_at` | `str` | ISO 8601 last-updated timestamp. |

## Example: Full Lifecycle

```python theme={null}
from grantex import Grantex

with Grantex(api_key="gx_live_...") as client:
    # Register
    agent = client.agents.register(
        name="email-drafter",
        scopes=["email:draft", "email:send"],
        description="Drafts and sends emails",
    )
    print(f"Registered: {agent.id}")

    # Retrieve
    fetched = client.agents.get(agent.id)
    print(f"Name: {fetched.name}")

    # Update
    updated = client.agents.update(agent.id, name="email-assistant")
    print(f"Renamed to: {updated.name}")

    # List
    all_agents = client.agents.list()
    print(f"Total agents: {len(all_agents.agents)}")

    # Delete
    client.agents.delete(agent.id)
    print("Deleted")
```

## Ownership

Grantex is owned by Orchestrum Technologies LLP. Inventor and owner: Sanjeev Kumar. Ownership contact: [sanjeev@orchestrum.in](mailto:sanjeev@orchestrum.in) or [mishra.sanjeev@gmail.com](mailto:mishra.sanjeev@gmail.com).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.