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

<!-- Generated by scripts/gen-website-api.ts — do not edit by hand. Run `pnpm run gen-website-api` to regenerate. -->

# 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](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L133)

### ctx.agents.setFactory(factory)

```ts website-api
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](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L152)

### ctx.agents.create(options)

```ts website-api
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](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L177)

### ctx.agents.resume(options)

```ts website-api
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](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L193)

### ctx.agents.register(agent)

```ts website-api
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](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L207)

### ctx.agents.enter(agent)

```ts website-api
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](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L222)

### ctx.agents.announce(agent)

```ts website-api
announce(agent: Agent): void
```

Announce an agent previously inserted with enter.

- `agent` — the live inserted agent to announce.

[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L290)

### ctx.agents.get(id)

```ts website-api
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](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L324)

### ctx.agents.list()

```ts website-api
list(): Agent[]
```

All live agents, in registration order.

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

[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L332)