配置与组合 - QitOS

先加载 canonical config；加载不读取 credentials、不创建 Docker。组合时显式解析 CredentialRef 或注入教学 provider。用 context manager 管理环境、store 和 scheduler。Session 方法返回公共 Session facade。ephemeral 不能 restore/fork；配置无效、缺少扩展或 composition 已关闭都不能继续执行。完整可运行教程 / Complete tutorial · API index 以下签名和字段由固定源码提取；签名是参考，不是可直接运行的程序。每个条目的源码链接绑定同一 runtime baseline。类型中的 Any 不代表任意对象均受支持，应结合上述行为契约和教程使用。

FakeCredentialResolver

from qitos.config import FakeCredentialResolver

Source @ d000a42 用法与可执行示例用法片段：接续上方完整教程中的对象，不是独立程序。

resolver = FakeCredentialResolver()  # offline fixtures only

Deterministic resolver for tests and offline qualification.

FakeCredentialResolver(values: Mapping[str, str] | None=None) -> None

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

AgentComposition

from qitos.config import AgentComposition

Source @ d000a42 用法与可执行示例用法片段：接续上方完整教程中的对象，不是独立程序。

# 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()

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`

AgentComposition.session

session(task: Optional[str]=None, *, session_id: Any=None) -> Any

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

Create the existing durable Session from this composition.

Source

AgentComposition.restore

restore(session_id: Any=None) -> Any

Parameter	Type	Default
`session_id`	`Any`	`None`

Restore with this composition's resolver registry and canonical Engine.

Source

AgentComposition.fork

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`

Fork immutable persisted state without claiming the source owner.

Source

AgentComposition.close

close() -> Dict[str, Any]

Close every framework-owned resource once and return a stable receipt.

Source

build_agent_composition

from qitos.config import build_agent_composition

Source @ d000a42 用法与可执行示例用法片段：接续上方完整教程中的对象，不是独立程序。

composition = build_agent_composition(config, model_override=provider)
try:
    result = composition.session("Index the notes").run()
finally:
    composition.close()

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.

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`

load_agent_config

from qitos.config import load_agent_config

Source @ d000a42 用法与可执行示例用法片段：接续上方完整教程中的对象，不是独立程序。

config = load_agent_config("agent.yaml")
print(config.digest())

Load one strict canonical configuration from YAML.

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`

AgentConfig

from qitos.config import AgentConfig

Source @ d000a42 用法与可执行示例用法片段：接续上方完整教程中的对象，不是独立程序。

config = load_agent_config("agent.yaml")
assert config.runtime.session.store == "sqlite"
print(config.to_dict()["model"]["credential"])

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)`

AgentConfig.to_dict

to_dict() -> Dict[str, Any]

Return deterministic JSON/YAML-safe canonical launch data.

Source

AgentConfig.digest

digest() -> str

Source

CredentialRef

from qitos.config import CredentialRef

Source @ d000a42 用法与可执行示例用法片段：接续上方完整教程中的对象，不是独立程序。

reference = CredentialRef("notes-provider")
print(reference)

Serializable logical identity of one credential.

Field	Type	Default
`ref`	`str`	`required`

LocalCredentialFileResolver

from qitos.config import LocalCredentialFileResolver

Source @ d000a42 用法与可执行示例用法片段：接续上方完整教程中的对象，不是独立程序。

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.

Resolve one logical credential from a hardened local YAML file.

LocalCredentialFileResolver(path: str | Path, *, repository_root: str | Path) -> None

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

LocalCredentialFileResolver.resolve

resolve(ref: CredentialRef) -> CredentialResolution

Parameter	Type	Default
`ref`	`CredentialRef`	`required`

Source

BudgetConfig

from qitos.config import BudgetConfig

Source @ d000a42 用法与可执行示例用法片段：接续上方完整教程中的对象，不是独立程序。

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`

EnvironmentConfig

from qitos.config import EnvironmentConfig

Source @ d000a42 用法与可执行示例用法片段：接续上方完整教程中的对象，不是独立程序。

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`

ModelConfig

from qitos.config import ModelConfig

Source @ d000a42 用法与可执行示例用法片段：接续上方完整教程中的对象，不是独立程序。

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`

RuntimeConfig

from qitos.config import RuntimeConfig

Source @ d000a42 用法与可执行示例用法片段：接续上方完整教程中的对象，不是独立程序。

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`	`''`

TrajectoryConfig

from qitos.config import TrajectoryConfig

Source @ d000a42 用法与可执行示例用法片段：接续上方完整教程中的对象，不是独立程序。

trajectory = TrajectoryConfig(output="./notes-run/trajectory.journal")

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

​FakeCredentialResolver

​AgentComposition

​AgentComposition.session

​AgentComposition.restore

​AgentComposition.fork

​AgentComposition.close

​build_agent_composition

​load_agent_config

​AgentConfig

​AgentConfig.to_dict

​AgentConfig.digest

​CredentialRef

​LocalCredentialFileResolver

​LocalCredentialFileResolver.resolve

​BudgetConfig

​EnvironmentConfig

​ModelConfig

​RuntimeConfig

​TrajectoryConfig

FakeCredentialResolver

AgentComposition

AgentComposition.session

AgentComposition.restore

AgentComposition.fork

AgentComposition.close

build_agent_composition

load_agent_config

AgentConfig

AgentConfig.to_dict

AgentConfig.digest

CredentialRef

LocalCredentialFileResolver

LocalCredentialFileResolver.resolve

BudgetConfig

EnvironmentConfig

ModelConfig

RuntimeConfig

TrajectoryConfig