Parties subclient—groups of NPCs for multi-agent conversations. Create parties, manage threads, and coordinate multiple agents.

Parties Subclient

The client.parties subclient lets you manage parties—groups of NPCs that participate in multi-agent conversations. Create a party with multiple NPCs, manage chat threads where all members interact, and coordinate complex group dynamics.

Methods

Method	Signature	Description
`list`	`() => Promise<Party[]>`	List all your parties
`get`	`(id: string) => Promise<Party>`	Get a party by ID
`create`	`(params) => Promise<Party>`	Create a new party
`update`	`(id, params) => Promise<Party>`	Update party configuration
`delete`	`(id: string) => Promise<void>`	Delete a party
`listThreads`	`(id: string) => Promise<Thread[]>`	List chat threads for a party
`getThread`	`(id, threadId) => Promise<Messages>`	Get thread with messages
`createThread`	`(id, params?) => Promise<Thread>`	Create a new thread
`deleteThread`	`(id, threadId) => Promise<void>`	Delete a thread

list()

list(): Promise<Party[]>

Returns all parties for the authenticated user.

const parties = await client.parties.list();
parties.forEach(p => console.log(`${p.name} (${p.id})`));

get(id)

get(id: string): Promise<Party>

Fetches a single party by ID.

const party = await client.parties.get('party-uuid');
console.log(party.npcIds);

create(params)

create(params: {
  name: string;
  npcIds: string[];
}): Promise<Party>

Creates a new party with the given name and NPC IDs. All listed NPCs participate in the party's conversations.

Param	Type	Description
`name`	`string`	Display name for the party
`npcIds`	`string[]`	Array of NPC IDs to include

const party = await client.parties.create({
  name: 'Council of Elders',
  npcIds: ['npc-1-id', 'npc-2-id', 'npc-3-id'],
});

update(id, params)

update(id: string, params: Partial<{ name: string; npcIds: string[] }>): Promise<Party>

Updates party name or member list.

await client.parties.update(party.id, {
  name: 'Updated Council',
  npcIds: ['npc-1-id', 'npc-2-id', 'npc-3-id', 'npc-4-id'],
});

delete(id)

delete(id: string): Promise<void>

Deletes a party by ID.

await client.parties.delete('party-uuid');

Thread Management

Each party has multiple chat threads—isolated conversations where all party members can participate. Threads are shared across the party's NPCs.

listThreads(id)

listThreads(partyId: string): Promise<Thread[]>

Returns chat threads for a party.

const threads = await client.parties.listThreads(party.id);
threads.forEach(t => console.log(t.title, t.id));

getThread(id, threadId)

getThread(partyId: string, threadId: string): Promise<{ thread: Thread; messages: Message[] }>

Fetches a specific thread with its message history. Messages include role, content, and metadata for each participant.

const { thread, messages } = await client.parties.getThread(party.id, threadId);
messages.forEach(m => console.log(`${m.role}: ${m.content}`));

createThread(id, params?)

createThread(partyId: string, params?: { name?: string }): Promise<Thread>

Creates a new thread. Optionally set a name for the conversation.

const thread = await client.parties.createThread(party.id, { name: 'Strategy Discussion' });

deleteThread(id, threadId)

deleteThread(partyId: string, threadId: string): Promise<void>

Deletes a thread and its message history.

await client.parties.deleteThread(party.id, threadId);

Multi-Agent Coordination

Parties enable multi-agent conversations where several NPCs respond in turn or in parallel. Use cases:

Roleplay: A group of characters in a scene, each with distinct personality
Debates: Multiple NPCs arguing or discussing a topic
Support teams: Customer service + specialist + manager coordination
Game masters: Dungeon master + NPCs for collaborative storytelling

Use the PartyAiClient from the SDK exports for programmatic chat with a party. It orchestrates messages across all party members.

Code Examples

import { PUClient } from 'pu-client';

const client = new PUClient({ apiKey: process.env.PU_API_KEY! });

const party = await client.parties.create({
  name: 'Adventure Squad',
  npcIds: [npc1.id, npc2.id, npc3.id],
});

const thread = await client.parties.createThread(party.id, {
  name: 'Quest Planning',
});

console.log(`Party ${party.name} ready. Thread: ${thread.id}`);

import { PUClient } from 'pu-client';

const client = new PUClient({ apiKey: process.env.PU_API_KEY! });

const parties = await client.parties.list();
const party = parties[0];

const threads = await client.parties.listThreads(party.id);
const { messages } = await client.parties.getThread(party.id, threads[0].id);

console.log(`Party has ${threads.length} threads, first has ${messages.length} messages`);

Full Workflow

1. Create NPCs

Create the NPCs that will participate in the party (see NPCs).

const npc1 = await client.npcs.create({ name: 'Wizard', src: 'characterlive:...' });
const npc2 = await client.npcs.create({ name: 'Warrior', src: 'characterlive:...' });

2. Create a party

const party = await client.parties.create({
  name: 'Hero Party',
  npcIds: [npc1.id, npc2.id],
});

3. Create a thread

const thread = await client.parties.createThread(party.id, { name: 'First Quest' });