deepseek-harness/website/zh-CN/api/harness/agents.md

ctx.agents

AgentRegistry — provided by @deepseek-ai/dsh-agent.

Agent registry (ctx.agents): tracks live agents so UI, hook, and orchestrator plugins can find them without depending on the concrete loop package. Agent creation is provided by whichever plugin implements the AgentFactory (@deepseek-ai/dsh-agent-loop), registered via setFactory.

Source

ctx.agents.setFactory(factory)

setFactory(factory: AgentFactory): () => void

Register the effect-scoped creation factory, rejecting a duplicate. Service factories are retraced through each create/resume caller for ownership.

• factory — the loop-owned factory create/resume delegate to.

Returns the exact Cordis effect disposer.

Source

ctx.agents.create(options)

async create(options: CreateAgentOptions): Promise<AgentHandle>

Create and publish an owned agent and session through the active factory. Rejects if no factory is registered or creation, setup, or publication fails.

• options — agent id, session id/seed/metadata, and agent options.

Returns the handle after setup, rollback-covered publication, and loop start complete.

Source

ctx.agents.resume(options)

async resume(options: ResumeAgentOptions): Promise<AgentHandle>

Load a persisted session and resume an agent on it through the registered factory. Rejects if no factory is registered; the factory rejects if session persistence is not configured or persistence/setup fails.

• options — persisted identity, configuration, and optional setup.

Returns the handle after setup, rollback-covered publication, and loop start complete.

Source

ctx.agents.register(agent)

register(agent: Agent): () => void

Register a live agent in the calling effect scope, with scope-filtered creation and disposal events. Duplicate ids throw.

• agent — the already-constructed agent to record in the store.

Returns the exact Cordis effect disposer for nested teardown ordering.

Source

ctx.agents.enter(agent)

enter(agent: Agent): () => void

Insert an unpublished agent for an ordered factory transaction.

• agent — the prepared, unpublished agent.

Returns an idempotent closure that removes this exact entry and emits the paired disposal edge; detachment during creation dispatch is deferred.

Source

ctx.agents.announce(agent)

announce(agent: Agent): void

Announce an agent previously inserted with enter.

• agent — the live inserted agent to announce.

Source

ctx.agents.get(id)

get(id: AgentId): Agent | undefined

Look up a live agent.

• id — the agent id to look up.

Returns the agent, or undefined when no live agent has that id.

Source

ctx.agents.list()

list(): Agent[]

All live agents, in registration order.

Returns a fresh array; mutating it does not affect the registry.

Source