Skip to main content

Class: AgencyRegistry

Defined in: packages/agentos/src/agents/agency/AgencyRegistry.ts:67

Tracks the Agencies (multi-GMI collectives) active inside the AgentOS runtime.

Remarks​

The registry is intentionally ephemeral; durable state should be captured via workflow persistence. For shared memory, use AgencyMemoryManager.

Example​

const registry = new AgencyRegistry(logger);

// Create agency with shared memory enabled
const session = registry.upsertAgency({
  workflowId: 'workflow-123',
  conversationId: 'conv-456',
  memoryConfig: { enabled: true },
});

// Register GMI seats
registry.registerSeat({
  agencyId: session.agencyId,
  roleId: 'researcher',
  gmiInstanceId: 'gmi-789',
  personaId: 'research-persona',
});

Constructors​

Constructor​

new AgencyRegistry(logger?): AgencyRegistry

Defined in: packages/agentos/src/agents/agency/AgencyRegistry.ts:78

Creates a new AgencyRegistry instance.

Parameters​

logger?​

ILogger

Optional logger for diagnostics

Returns​

AgencyRegistry

Methods​

appendSeatHistory()​

appendSeatHistory(agencyId, roleId, entry, maxEntries?): AgencySeatState | undefined

Defined in: packages/agentos/src/agents/agency/AgencyRegistry.ts:227

Appends a history entry to the specified seat and returns the updated state.

Parameters​

agencyId​

string

roleId​

string

entry​

AgencySeatHistoryEntry

maxEntries?​

number = 20

Returns​

AgencySeatState | undefined

getAgency()​

getAgency(agencyId): AgencySession | undefined

Defined in: packages/agentos/src/agents/agency/AgencyRegistry.ts:147

Retrieves an agency session by identifier.

Parameters​

agencyId​

string

Target Agency identifier.

Returns​

AgencySession | undefined

The matching agency session or undefined when absent.

getAgencyByWorkflow()​

getAgencyByWorkflow(workflowId): AgencySession | undefined

Defined in: packages/agentos/src/agents/agency/AgencyRegistry.ts:156

Resolves the agency session associated with a workflow instance (if any).

Parameters​

workflowId​

string

Workflow instance identifier.

Returns​

AgencySession | undefined

The agency session mapped to the workflow, if present.

listAgencies()​

listAgencies(): AgencySession[]

Defined in: packages/agentos/src/agents/agency/AgencyRegistry.ts:170

Copies of the agency sessions running now, in the order they were created: workflow agencies, and the teams a GMI launched on the full runtime (launch_agency), whose metadata has kind: 'launched'. Each copy's seats, their histories, its metadata and its memory config are copied as far down as they hold arrays and plain objects, so a caller cannot change the registry through them; a value of another kind in a metadata record (a Date, a class instance) is the registry's own.

Returns​

AgencySession[]

The running sessions.

mergeSeatMetadata()​

mergeSeatMetadata(agencyId, roleId, metadata): AgencySeatState | undefined

Defined in: packages/agentos/src/agents/agency/AgencyRegistry.ts:245

Merges metadata onto a seat without altering other properties.

Parameters​

agencyId​

string

roleId​

string

metadata​

Record<string, unknown>

Returns​

AgencySeatState | undefined

registerSeat()​

registerSeat(args): AgencySession

Defined in: packages/agentos/src/agents/agency/AgencyRegistry.ts:180

Registers or updates a seat inside the agency.

Parameters​

args​

AgencySeatRegistrationArgs

Seat registration payload.

Returns​

AgencySession

Updated agency session after the seat registration.

Throws​

When attempting to register against an unknown agency.

removeAgency()​

removeAgency(agencyId): boolean

Defined in: packages/agentos/src/agents/agency/AgencyRegistry.ts:210

Removes an agency entirely (e.g., when the workflow reaches a terminal state).

Parameters​

agencyId​

string

Agency identifier to remove.

Returns​

boolean

true when the agency existed and was removed.

upsertAgency()​

upsertAgency(args): AgencySession

Defined in: packages/agentos/src/agents/agency/AgencyRegistry.ts:98

Creates or updates an agency session associated with a workflow.

Parameters​

args​

AgencyUpsertArgs

Upsert payload containing workflow linkage, memory config, and optional metadata.

Returns​

AgencySession

The upserted agency session.

Example​

const session = registry.upsertAgency({
  workflowId: 'workflow-123',
  conversationId: 'conv-456',
  memoryConfig: {
    enabled: true,
    autoIngestCommunications: true,
  },
});