def create_deep_agent(
    # ── 模型 ──
    model: str | BaseChatModel | None = None,

    # ── 工具 ──
    tools: Sequence[BaseTool | Callable | dict] | None = None,

    # ── 提示词 ──
    system_prompt: str | SystemMessage | None = None,

    # ── 中间件 ──
    middleware: Sequence[AgentMiddleware] = (),

    # ── 子代理 ──
    subagents: Sequence[SubAgent | CompiledSubAgent | AsyncSubAgent] | None = None,

    # ── 技能 ──
    skills: list[str] | None = None,

    # ── 记忆 ──
    memory: list[str] | None = None,

    # ── 权限 ──
    permissions: list[FilesystemPermission] | None = None,

    # ── 后端 ──
    backend: BackendProtocol | BackendFactory | None = None,

    # ── 人机协作 ──
    interrupt_on: dict[str, bool | InterruptOnConfig] | None = None,

    # ── 结构化输出 ──
    response_format: ResponseFormat | type | dict | None = None,

    # ── 上下文 ──
    context_schema: type[ContextT] | None = None,

    # ── 持久化 ──
    checkpointer: Checkpointer | None = None,
    store: BaseStore | None = None,

    # ── 其他 ──
    debug: bool = False,
    name: str | None = None,
    cache: BaseCache | None = None,
) -> CompiledStateGraph

class BackendProtocol(abc.ABC):
    def ls(path) -> LsResult
    def read(file_path, offset, limit) -> ReadResult
    def write(file_path, content) -> WriteResult
    def edit(file_path, old_string, new_string, replace_all) -> EditResult
    def glob(pattern, path) -> GlobResult
    def grep(pattern, path, glob) -> GrepResult
    def upload_files(files) -> list[FileUploadResponse]
    def download_files(paths) -> list[FileDownloadResponse]
    # 以上全部有 async 版本 (als, aread, awrite, ...)

class SandboxBackendProtocol(BackendProtocol):
    @property
    def id(self) -> str
    def execute(command, timeout) -> ExecuteResponse
    async def aexecute(command, timeout) -> ExecuteResponse

backend = CompositeBackend(
    default=FilesystemBackend(root_dir="/workspace"),
    routes={
        "/data": StoreBackend(store=my_store),
        "/sandbox": DaytonaSandbox(),
    },
)

@dataclass(frozen=True)
class ProviderProfile:
    init_kwargs: Mapping[str, Any]          # 传给 init_chat_model 的静态参数
    pre_init: Callable[[str], None] | None  # 初始化前的副作用
    init_kwargs_factory: Callable[[], dict] # 动态参数（运行时生成）

register_provider_profile("openai", ProviderProfile(init_kwargs={"use_responses_api": True}))
register_provider_profile("openai:gpt-5.4", ProviderProfile(init_kwargs={...}))

@dataclass(frozen=True)
class HarnessProfile:
    base_system_prompt: str | None = None           # 替换 SDK 默认 prompt
    system_prompt_suffix: str | None = None         # 追加到 prompt 末尾
    tool_description_overrides: Mapping[str, str]   # 按工具名覆盖描述
    excluded_tools: frozenset[str]                   # 排除的工具
    excluded_middleware: frozenset[type | str]       # 排除的中间件
    extra_middleware: Sequence | Callable            # 额外中间件
    general_purpose_subagent: GeneralPurposeSubagentProfile  # GP 子代理配置

@dataclass(frozen=True)
class GeneralPurposeSubagentProfile:
    enabled: bool | None = None       # None/True=启用, False=禁用
    description: str | None = None    # 覆盖 GP 子代理描述
    system_prompt: str | None = None  # 覆盖 GP 子代理系统提示词

@dataclass
class FilesystemPermission:
    operations: list[Literal["read", "write"]]  # 覆盖的操作类型
    paths: list[str]                            # Glob 模式（必须以 "/" 开头）
    mode: Literal["allow", "deny"] = "allow"    # 允许或拒绝

permissions=[
    # 只允许读取 /data 目录
    FilesystemPermission(operations=["read"], paths=["/data/*"], mode="allow"),
    # 禁止写入配置文件
    FilesystemPermission(operations=["write"], paths=["/etc/*"], mode="deny"),
    # 禁止读取密钥文件
    FilesystemPermission(operations=["read"], paths=["/secrets/*"], mode="deny"),
]

class SubAgent(TypedDict):
    name: str                          # 必需：唯一标识
    description: str                   # 必需：功能描述
    system_prompt: str                 # 必需：指令
    tools: NotRequired[Sequence[...]]  # 可选：默认继承主代理
    model: NotRequired[str | BaseChatModel]  # 可选：默认继承主代理
    middleware: NotRequired[list[...]] # 可选：额外中间件
    interrupt_on: NotRequired[dict]    # 可选：默认继承主代理
    skills: NotRequired[list[str]]     # 可选：技能路径
    permissions: NotRequired[list[...]]# 可选：默认继承主代理
    response_format: NotRequired[...]  # 可选：结构化输出

class CompiledSubAgent(TypedDict):
    name: str          # 必需
    description: str   # 必需
    runnable: Runnable  # 必需：预编译的 LangGraph 图（state 必须有 'messages'）

class AsyncSubAgent(TypedDict):
    name: str                      # 必需
    description: str               # 必需
    graph_id: str                  # 必需：远程图名/助手 ID
    url: NotRequired[str]          # 可选：Agent Protocol 服务器 URL
    headers: NotRequired[dict]     # 可选：额外请求头

# 支持三种输入
create_deep_agent(model="openai:gpt-4o")            # provider:model 字符串
create_deep_agent(model=ChatAnthropic(model="..."))  # 预初始化模型实例
create_deep_agent(model=None)                        # 默认模型（已弃用）