# API 概览

各接口的 CP-SAT、HiGHS 限制见[求解器支持矩阵](solver-support.md)；方法详情中的标签区分支持、条件支持和不支持。

从 `optagent` 导入公开模型与求解入口。按使用目的查阅接口：

| 目的 | 接口 | 参考 |
| --- | --- | --- |
| 创建模型、变量与约束 | `OptModel` | [建模接口](modeling.md) |
| 保存模型，读取 protobuf / MPS / LP 文件 | `model.save`、`read_model` | [模型文件](modeling.md) |
| 组合并读取表达式 | `Expression`、`IntervalExpression` | [建模接口](modeling.md) |
| 注册外部计算 | `ExternalFunction` | [建模接口](modeling.md) |
| 混合求解、独立启发式求解或精确求解 | `solve`、`solve_heuristic`、`solve_optx` | [求解与配置](solve.md) |
| 暂停、改解与续跑 | `interactive_solve`、`SolveSession` | [交互式求解](solve.md) |
| 读取返回结果 | `Solution` | [结果与诊断](../guide/results.md) |

三个入口都可写为模型方法或模块函数，例如 `model.solve_optx(config=...)` 与 `solve_optx(model, config=...)`。
`solve` 和 `solve_heuristic` 的通用参数直接按名称传入；`solve_optx` 通过 `HighsConfig` 或 `CpSatConfig` 选择内置后端。旧接口的替换方式见[迁移说明](../guide/migration.md)。

## 类型与算子

`OptType` 描述表达式值类型，`Operator` 标识表达式操作，`OptValue` 表达带类型的值。通常直接使用模型工厂方法和 Python 运算符创建表达式，无需手动构造底层表示。

<!-- public-api: optagent.OptType -->
<!-- public-api: optagent.OptValue -->
<!-- public-api: optagent.Operator -->

## 异常

| 异常 | 含义与处理 |
| --- | --- |
| `OptxUnsupportedError` | OptX 无法编译模型；读取 `.issues` 定位不兼容表达式 |
| `OptxCompatibilityIssue` | 问题包含 `code`、`expression_id`、`operator`、`root_kind`、`root_name`、`message`、`requirement`、`expression_path`、`backend` |
| `HeuristicUnsupportedError` | 选定的 GA 搜索方案不适用于当前模型；查看 `.search_definition` 和 `.diagnostics` |
| `LicenseError` | 许可证校验失败；检查许可证状态 |
| `ValueError` | 变量范围、配置或调用方式无效 |
| `RuntimeError` | 求解组件不可用、执行失败，或表达式没有可读取的值 |

<!-- public-api: optagent.OptxCompatibilityIssue -->
<!-- public-api: optagent.OptxUnsupportedError -->
<!-- public-api: optagent.HeuristicUnsupportedError -->
<!-- public-api: optagent.LicenseError -->