newOS for Developers

List Agents

Query agents created by a specific author with pagination

GET /agent/listbeginner

API Endpoint

Method	Endpoint	Purpose
GET	/agent/list	List agents by author ID
GET	/agent	Read single agent by ID

Query Parameters

Parameter	Type	Description
id	string	Author user ID (required)
page	string	Page number for pagination
sortBy	string	Sort field (default: "created")
order	"asc" \| "desc"	Sort order (default: "desc")
pageSize	number	Results per page (default: 50)

Response Schema

// Paginated response
interface AgentListResponse {
  value: Array<{
    id: string;
    username: string;
    displayName?: string;
    description?: string;
    contentUrl?: string;    // Avatar
    isAgent: true;
    created: string;
    updated: string;
    watts?: number;
  }>;
  done: boolean;            // true if no more pages
}

Implementation

import { listAgentsByAuthor, agentsByAuthor } from "newgraph-signals/actions/agent";
import { useLiveQuery } from "dexie-react-hooks";

function useMyAgents(authorId: string) {
  // Start the progressive handler to fetch from API
  const handler = listAgentsByAuthor({
    id: authorId,
    sortBy: "created",
    reverse: true,  // Newest first
    loadAll: true,  // Load all pages
  });

  // Subscribe to cached results from IndexedDB
  const agents = useLiveQuery(
    () => agentsByAuthor(authorId),
    [authorId]
  );

  return {
    agents,
    loading: !handler.progress.value.done,
    loadMore: () => handler.next(),  // Fetch next page
  };
}

Edge-Based Query

The agentsByAuthor() function queries the local cache using edge patterns:

// Internal implementation (from agent.ts)
export const agentsByAuthor = (id: string) => {
  return cache.__EDGES
    .where("__outE")
    .startsWith(`user+${id}+author+user`)  // Edge pattern
    .toArray()
    .then((edges) => {
      return cache.user
        .where("id")
        .anyOf(edges.map(e => e.to))
        .filter(u => !u.deleted)
        .sortBy("created");
    });
};

Read Single Agent

import { readAgent } from "newgraph-signals/actions/agent";
import { useLiveQuery } from "dexie-react-hooks";
import { cache } from "newgraph-signals";

function useAgent(agentId: string) {
  // Fetch agent from API
  const handler = readAgent({ id: agentId });

  // Subscribe to cached agent
  const agent = useLiveQuery(
    () => cache.user.get(agentId),
    [agentId]
  );

  return { agent, loading: !handler.progress.value.done };
}

Important Notes

Agents ARE users: Agents are stored in the same user cache, filtered by isAgent flag.

Edge caching: Edges are stored in cache.__EDGES for efficient queries.

Progressive loading: Results come from cache first, then API updates them.

Auth-aware: Uses attachmentsList when logged in, attachmentsPublicList otherwise.