> ## Documentation Index
> Fetch the complete documentation index at: https://qitor.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 配置与组合

> QitOS public API: composition

先加载 canonical config；加载不读取 credentials、不创建 Docker。组合时显式解析 CredentialRef 或注入教学 provider。用 context manager 管理环境、store 和 scheduler。Session 方法返回公共 Session facade。ephemeral 不能 restore/fork；配置无效、缺少扩展或 composition 已关闭都不能继续执行。

[完整可运行教程 / Complete tutorial](/zh/quickstart) · [API index](/zh/reference/api)

以下签名和字段由固定源码提取；签名是参考，不是可直接运行的程序。每个条目的源码链接绑定同一 runtime baseline。类型中的 Any 不代表任意对象均受支持，应结合上述行为契约和教程使用。

<span id="qitos-config-fakecredentialresolver" />

## FakeCredentialResolver

```python theme={null}
from qitos.config import FakeCredentialResolver
```

[Source @ d000a42](https://github.com/WhitzardAgent/WhitzardOS/blob/d000a42aff30b87c812850ac1019ca197f420c09/qitos/config/credentials.py#L195)

[用法与可执行示例](/zh/quickstart)

用法片段：接续上方完整教程中的对象，不是独立程序。

```python theme={null}
resolver = FakeCredentialResolver()  # offline fixtures only
```

```text theme={null}
Deterministic resolver for tests and offline qualification.
```

```text theme={null}
FakeCredentialResolver(values: Mapping[str, str] | None=None) -> None
```

| Parameter | Type                        | Default |
| --------- | --------------------------- | ------- |
| `values`  | `Mapping[str, str] \| None` | `None`  |

<span id="qitos-config-agentcomposition" />

## AgentComposition

```python theme={null}
from qitos.config import AgentComposition
```

[Source @ d000a42](https://github.com/WhitzardAgent/WhitzardOS/blob/d000a42aff30b87c812850ac1019ca197f420c09/qitos/config/builder.py#L134)

[用法与可执行示例](/zh/quickstart)

用法片段：接续上方完整教程中的对象，不是独立程序。

```python theme={null}
# After loading config and creating the explicit provider:
with build_agent_composition(config, model_override=provider) as composition:
    session = composition.session("Index the notes")
    result = session.run()
```

```text theme={null}
Resource-owning composition root for the existing Engine and Session.
```

| Field                | Type                         | Default                       |
| -------------------- | ---------------------------- | ----------------------------- |
| `config`             | `AgentConfig`                | `required`                    |
| `model`              | `Any`                        | `required`                    |
| `tool_registry`      | `ToolRegistry`               | `required`                    |
| `env`                | `Any`                        | `required`                    |
| `runtime`            | `RuntimeComposition`         | `required`                    |
| `agent`              | `AgentModule[Any, Any, Any]` | `required`                    |
| `engine`             | `Engine[Any, Any, Any]`      | `required`                    |
| `credential_receipt` | `Dict[str, Any]`             | `required`                    |
| `sandbox_backend`    | `Any`                        | `None`                        |
| `sandbox_receipt`    | `Dict[str, Any]`             | `field(default_factory=dict)` |
| `trajectory_path`    | `Optional[Path]`             | `None`                        |

<span id="qitos-config-agentcomposition-session" />

### AgentComposition.session

```text theme={null}
session(task: Optional[str]=None, *, session_id: Any=None) -> Any
```

| Parameter    | Type            | Default |
| ------------ | --------------- | ------- |
| `task`       | `Optional[str]` | `None`  |
| `session_id` | `Any`           | `None`  |

```text theme={null}
Create the existing durable Session from this composition.
```

[Source](https://github.com/WhitzardAgent/WhitzardOS/blob/d000a42aff30b87c812850ac1019ca197f420c09/qitos/config/builder.py#L172)

<span id="qitos-config-agentcomposition-restore" />

### AgentComposition.restore

```text theme={null}
restore(session_id: Any=None) -> Any
```

| Parameter    | Type  | Default |
| ------------ | ----- | ------- |
| `session_id` | `Any` | `None`  |

```text theme={null}
Restore with this composition's resolver registry and canonical Engine.
```

[Source](https://github.com/WhitzardAgent/WhitzardOS/blob/d000a42aff30b87c812850ac1019ca197f420c09/qitos/config/builder.py#L188)

<span id="qitos-config-agentcomposition-fork" />

### AgentComposition.fork

```text theme={null}
fork(session_id: Any, snapshot: Any=None, *, operation_id: Optional[str]=None) -> Any
```

| Parameter      | Type            | Default    |
| -------------- | --------------- | ---------- |
| `session_id`   | `Any`           | `required` |
| `snapshot`     | `Any`           | `None`     |
| `operation_id` | `Optional[str]` | `None`     |

```text theme={null}
Fork immutable persisted state without claiming the source owner.
```

[Source](https://github.com/WhitzardAgent/WhitzardOS/blob/d000a42aff30b87c812850ac1019ca197f420c09/qitos/config/builder.py#L211)

<span id="qitos-config-agentcomposition-close" />

### AgentComposition.close

```text theme={null}
close() -> Dict[str, Any]
```

```text theme={null}
Close every framework-owned resource once and return a stable receipt.
```

[Source](https://github.com/WhitzardAgent/WhitzardOS/blob/d000a42aff30b87c812850ac1019ca197f420c09/qitos/config/builder.py#L222)

<span id="qitos-config-build_agent_composition" />

## build\_agent\_composition

```python theme={null}
from qitos.config import build_agent_composition
```

[Source @ d000a42](https://github.com/WhitzardAgent/WhitzardOS/blob/d000a42aff30b87c812850ac1019ca197f420c09/qitos/config/builder.py#L659)

[用法与可执行示例](/zh/quickstart)

用法片段：接续上方完整教程中的对象，不是独立程序。

```python theme={null}
composition = build_agent_composition(config, model_override=provider)
try:
    result = composition.session("Index the notes").run()
finally:
    composition.close()
```

```text theme={null}
Compose the existing model/tools/Env/runtime/AgentModule/Engine stack.

``agent_factory`` is called once with keyword arguments ``config``, ``model``,
``tool_registry``, ``protocol`` (a resolved protocol), and ``parser``. It
returns an AgentModule bound to those resources; it must not replace them.
The factory may register application tools. Composition retains ownership
of resources it created. Recreate the factory in the restoring process;
no callable is serialized in Session snapshots.
```

```text theme={null}
build_agent_composition(config: AgentConfig, *, credential_resolver: Optional[CredentialResolver]=None, model_override: Any=None, env_override: Any=None, extensions: Optional[Mapping[str, Any]]=None, agent_factory: Optional[Callable[..., AgentModule[Any, Any, Any]]]=None) -> AgentComposition
```

| Parameter             | Type                                                  | Default    |
| --------------------- | ----------------------------------------------------- | ---------- |
| `config`              | `AgentConfig`                                         | `required` |
| `credential_resolver` | `Optional[CredentialResolver]`                        | `None`     |
| `model_override`      | `Any`                                                 | `None`     |
| `env_override`        | `Any`                                                 | `None`     |
| `extensions`          | `Optional[Mapping[str, Any]]`                         | `None`     |
| `agent_factory`       | `Optional[Callable[..., AgentModule[Any, Any, Any]]]` | `None`     |

<span id="qitos-config-load_agent_config" />

## load\_agent\_config

```python theme={null}
from qitos.config import load_agent_config
```

[Source @ d000a42](https://github.com/WhitzardAgent/WhitzardOS/blob/d000a42aff30b87c812850ac1019ca197f420c09/qitos/config/loader.py#L503)

[用法与可执行示例](/zh/quickstart)

用法片段：接续上方完整教程中的对象，不是独立程序。

```python theme={null}
config = load_agent_config("agent.yaml")
print(config.digest())
```

```text theme={null}
Load one strict canonical configuration from YAML.
```

```text theme={null}
load_agent_config(path: str | Path, *, compatibility: bool=False, environment_interpolation: bool=False) -> AgentConfig
```

| Parameter                   | Type          | Default    |
| --------------------------- | ------------- | ---------- |
| `path`                      | `str \| Path` | `required` |
| `compatibility`             | `bool`        | `False`    |
| `environment_interpolation` | `bool`        | `False`    |

<span id="qitos-config-agentconfig" />

## AgentConfig

```python theme={null}
from qitos.config import AgentConfig
```

[Source @ d000a42](https://github.com/WhitzardAgent/WhitzardOS/blob/d000a42aff30b87c812850ac1019ca197f420c09/qitos/config/loader.py#L235)

[用法与可执行示例](/zh/quickstart)

用法片段：接续上方完整教程中的对象，不是独立程序。

```python theme={null}
config = load_agent_config("agent.yaml")
assert config.runtime.session.store == "sqlite"
print(config.to_dict()["model"]["credential"])
```

```text theme={null}
The one canonical declarative agent launch configuration.
```

| Field             | Type                          | Default                                |
| ----------------- | ----------------------------- | -------------------------------------- |
| `name`            | `str`                         | `'agent'`                              |
| `max_steps`       | `int`                         | `10`                                   |
| `model`           | `ModelConfig`                 | `field(default_factory=ModelConfig)`   |
| `dataset`         | `Sequence[DatasetItem]`       | `field(default_factory=tuple)`         |
| `tools`           | `Sequence[str]`               | `field(default_factory=tuple)`         |
| `tool_preset`     | `str`                         | `'none'`                               |
| `tool_options`    | `Mapping[str, Any]`           | `field(default_factory=dict)`          |
| `tool_use_policy` | `str`                         | `'auto'`                               |
| `protocol`        | `str`                         | `'auto'`                               |
| `parser`          | `str`                         | `'auto'`                               |
| `environment`     | `Mapping[str, Any]`           | `field(default_factory=dict)`          |
| `seed`            | `int`                         | `0`                                    |
| `metadata`        | `Mapping[str, Any]`           | `field(default_factory=dict)`          |
| `context`         | `Mapping[str, Any]`           | `field(default_factory=dict)`          |
| `memory`          | `Mapping[str, Any]`           | `field(default_factory=dict)`          |
| `compaction`      | `Mapping[str, Any]`           | `field(default_factory=dict)`          |
| `lifecycle`       | `Mapping[str, Any]`           | `field(default_factory=dict)`          |
| `failure_policy`  | `Mapping[str, Any]`           | `field(default_factory=dict)`          |
| `runtime`         | `RuntimeConfig`               | `field(default_factory=RuntimeConfig)` |
| `budgets`         | `Optional[BudgetConfig]`      | `None`                                 |
| `schema`          | `str`                         | `CANONICAL_SCHEMA`                     |
| `source`          | `Mapping[str, Any]`           | `field(default_factory=dict)`          |
| `compatibility`   | `Sequence[Mapping[str, Any]]` | `field(default_factory=tuple)`         |
| `loss`            | `Sequence[Mapping[str, Any]]` | `field(default_factory=tuple)`         |

<span id="qitos-config-agentconfig-to-dict" />

### AgentConfig.to\_dict

```text theme={null}
to_dict() -> Dict[str, Any]
```

```text theme={null}
Return deterministic JSON/YAML-safe canonical launch data.
```

[Source](https://github.com/WhitzardAgent/WhitzardOS/blob/d000a42aff30b87c812850ac1019ca197f420c09/qitos/config/loader.py#L297)

<span id="qitos-config-agentconfig-digest" />

### AgentConfig.digest

```text theme={null}
digest() -> str
```

[Source](https://github.com/WhitzardAgent/WhitzardOS/blob/d000a42aff30b87c812850ac1019ca197f420c09/qitos/config/loader.py#L341)

<span id="qitos-config-credentialref" />

## CredentialRef

```python theme={null}
from qitos.config import CredentialRef
```

[Source @ d000a42](https://github.com/WhitzardAgent/WhitzardOS/blob/d000a42aff30b87c812850ac1019ca197f420c09/qitos/config/credentials.py#L25)

[用法与可执行示例](/zh/quickstart)

用法片段：接续上方完整教程中的对象，不是独立程序。

```python theme={null}
reference = CredentialRef("notes-provider")
print(reference)
```

```text theme={null}
Serializable logical identity of one credential.
```

| Field | Type  | Default    |
| ----- | ----- | ---------- |
| `ref` | `str` | `required` |

<span id="qitos-config-localcredentialfileresolver" />

## LocalCredentialFileResolver

```python theme={null}
from qitos.config import LocalCredentialFileResolver
```

[Source @ d000a42](https://github.com/WhitzardAgent/WhitzardOS/blob/d000a42aff30b87c812850ac1019ca197f420c09/qitos/config/credentials.py#L113)

[用法与可执行示例](/zh/quickstart)

用法片段：接续上方完整教程中的对象，不是独立程序。

```python theme={null}
from pathlib import Path
resolver = LocalCredentialFileResolver(
    Path.home() / ".config/qitos/credentials.yaml",
    repository_root=Path.cwd(),
)
# Pass resolver as credential_resolver to build_agent_composition.
```

```text theme={null}
Resolve one logical credential from a hardened local YAML file.
```

```text theme={null}
LocalCredentialFileResolver(path: str | Path, *, repository_root: str | Path) -> None
```

| Parameter         | Type          | Default    |
| ----------------- | ------------- | ---------- |
| `path`            | `str \| Path` | `required` |
| `repository_root` | `str \| Path` | `required` |

<span id="qitos-config-localcredentialfileresolver-resolve" />

### LocalCredentialFileResolver.resolve

```text theme={null}
resolve(ref: CredentialRef) -> CredentialResolution
```

| Parameter | Type            | Default    |
| --------- | --------------- | ---------- |
| `ref`     | `CredentialRef` | `required` |

[Source](https://github.com/WhitzardAgent/WhitzardOS/blob/d000a42aff30b87c812850ac1019ca197f420c09/qitos/config/credentials.py#L155)

<span id="qitos-config-budgetconfig" />

## BudgetConfig

```python theme={null}
from qitos.config import BudgetConfig
```

[Source @ d000a42](https://github.com/WhitzardAgent/WhitzardOS/blob/d000a42aff30b87c812850ac1019ca197f420c09/qitos/config/loader.py#L221)

[用法与可执行示例](/zh/quickstart)

用法片段：接续上方完整教程中的对象，不是独立程序。

```python theme={null}
budget = BudgetConfig(max_steps=6, max_requests=6, max_runtime_seconds=30)
```

| Field                 | Type    | Default |
| --------------------- | ------- | ------- |
| `max_steps`           | `int`   | `10`    |
| `max_runtime_seconds` | `float` | `600.0` |
| `max_requests`        | `int`   | `12`    |

<span id="qitos-config-environmentconfig" />

## EnvironmentConfig

```python theme={null}
from qitos.config import EnvironmentConfig
```

[Source @ d000a42](https://github.com/WhitzardAgent/WhitzardOS/blob/d000a42aff30b87c812850ac1019ca197f420c09/qitos/config/loader.py#L112)

[用法与可执行示例](/zh/quickstart)

用法片段：接续上方完整教程中的对象，不是独立程序。

```python theme={null}
environment = EnvironmentConfig(workspace="./source", image="python:3.12-slim")
```

| Field                 | Type              | Default              |
| --------------------- | ----------------- | -------------------- |
| `type`                | `str`             | `'docker'`           |
| `image`               | `str`             | `'python:3.12-slim'` |
| `workspace`           | `str`             | `'.'`                |
| `container_workspace` | `str`             | `'/workspace'`       |
| `network`             | `str`             | `'none'`             |
| `read_only_root`      | `bool`            | `True`               |
| `cap_drop`            | `bool`            | `True`               |
| `no_new_privileges`   | `bool`            | `True`               |
| `pids_limit`          | `Optional[int]`   | `256`                |
| `memory_mb`           | `Optional[int]`   | `2048`               |
| `cpus`                | `Optional[float]` | `2.0`                |
| `cleanup_required`    | `bool`            | `True`               |

<span id="qitos-config-modelconfig" />

## ModelConfig

```python theme={null}
from qitos.config import ModelConfig
```

[Source @ d000a42](https://github.com/WhitzardAgent/WhitzardOS/blob/d000a42aff30b87c812850ac1019ca197f420c09/qitos/config/loader.py#L60)

[用法与可执行示例](/zh/quickstart)

用法片段：接续上方完整教程中的对象，不是独立程序。

```python theme={null}
model = ModelConfig(provider="openai_compatible", model="notes-fake")
```

| Field            | Type                      | Default                                        |
| ---------------- | ------------------------- | ---------------------------------------------- |
| `provider`       | `str`                     | `'openai'`                                     |
| `model`          | `str`                     | `''`                                           |
| `model_name`     | `str`                     | `''`                                           |
| `credential`     | `Optional[CredentialRef]` | `None`                                         |
| `base_url`       | `str`                     | `''`                                           |
| `context_window` | `Optional[int]`           | `None`                                         |
| `api_mode`       | `str`                     | `'chat_completions'`                           |
| `request`        | `ModelRequestConfig`      | `field(default_factory=ModelRequestConfig)`    |
| `api_key`        | `str`                     | `field(default='', repr=False, compare=False)` |
| `temperature`    | `Optional[float]`         | `None`                                         |
| `max_tokens`     | `Optional[int]`           | `None`                                         |

<span id="qitos-config-runtimeconfig" />

## RuntimeConfig

```python theme={null}
from qitos.config import RuntimeConfig
```

[Source @ d000a42](https://github.com/WhitzardAgent/WhitzardOS/blob/d000a42aff30b87c812850ac1019ca197f420c09/qitos/config/loader.py#L205)

[用法与可执行示例](/zh/quickstart)

用法片段：接续上方完整教程中的对象，不是独立程序。

```python theme={null}
runtime = RuntimeConfig(environment=EnvironmentConfig(workspace="./source"))
```

| Field         | Type                | Default                                    |
| ------------- | ------------------- | ------------------------------------------ |
| `environment` | `EnvironmentConfig` | `field(default_factory=EnvironmentConfig)` |
| `session`     | `SessionConfig`     | `field(default_factory=SessionConfig)`     |
| `trajectory`  | `TrajectoryConfig`  | `field(default_factory=TrajectoryConfig)`  |
| `data_root`   | `str`               | `''`                                       |

<span id="qitos-config-trajectoryconfig" />

## TrajectoryConfig

```python theme={null}
from qitos.config import TrajectoryConfig
```

[Source @ d000a42](https://github.com/WhitzardAgent/WhitzardOS/blob/d000a42aff30b87c812850ac1019ca197f420c09/qitos/config/loader.py#L189)

[用法与可执行示例](/zh/quickstart)

用法片段：接续上方完整教程中的对象，不是独立程序。

```python theme={null}
trajectory = TrajectoryConfig(output="./notes-run/trajectory.journal")
```

| Field            | Type   | Default      |
| ---------------- | ------ | ------------ |
| `enabled`        | `bool` | `True`       |
| `output`         | `str`  | `''`         |
| `privacy`        | `str`  | `'private'`  |
| `failure_policy` | `str`  | `'required'` |