SDK 与配置¶
可嵌入 SDK 位于 dashscope_agenticx.sdk — 在 Agent 运行时之上提供
稳定、带类型的接口,供脚本、CI 流水线、IDE 插件及其他 Python 程序
使用。面向任务的演练参见嵌入式 SDK;配置文件与
环境变量参见配置。
from dashscope_agenticx.sdk import run_once_sync
print(run_once_sync("Summarize README.md"))
导入路径
请从 dashscope_agenticx.sdk 导入。顶层包重新导出了最常用的辅助
函数,但 sdk 模块才是文档化的完整接口。
配置解析¶
Config.load() 按优先级从低到高合并三层:
- 全局配置:
~/.config/AgenticX/config.toml - 工作区配置:
./.agenticx/config.toml - 环境变量填补剩余空缺(
DASHSCOPE_API_KEY、ANTHROPIC_API_KEY、OPENAI_API_KEY、AGENTICX_WORKSPACE、AGENTICX_REGION、AGENTICX_MAAS_API_KEY、…)
AGENTICX_PROVIDER、AGENTICX_MODEL、AGENTICX_OPENAI_BASE_URL 与
AGENTICX_MCP_SERVERS 强制覆盖解析结果。SDK 中的 load_config()
仅在解析后的配置仍有空缺时应用调用方提供的参数。
Config.api_key 是一个属性,根据 Config.provider 路由到对应
Provider 的密钥字段(tongyi_api_key、anthropic_api_key、
openai_api_key)。
SDK 入口¶
sdk
¶
Lightweight programmatic SDK for embedding agenticx in other applications.
This module exposes a stable, typed API surface on top of the lower-level
Agent, Executor, and ProviderChain internals. It is intended for
scripts, CI pipelines, IDE plugins, and other Python programs that want to
reuse agenticx's agent stack without invoking the full interactive CLI.
Example::
import asyncio
from dashscope_agenticx.sdk import run_once
result = asyncio.run(run_once("Summarize README.md"))
print(result)
load_config
¶
load_config(
provider: Optional[str] = None,
model: Optional[str] = None,
api_key: Optional[str] = None,
base_url: Optional[str] = None,
) -> Config
Load agenticx configuration with caller-supplied overrides.
Workspace/global config and environment variables still take their normal priority; explicit arguments only fill in missing defaults.
Source code in src/dashscope_agenticx/sdk.py
42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 | |
create_agent
¶
create_agent(
config: Optional[Config] = None,
system_prompt: Optional[str] = None,
session_id: Optional[str] = None,
*,
oneshot: bool = False
) -> Agent
Create an Agent instance ready for programmatic use.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
config
|
Optional[Config]
|
agenticx configuration. If None, loads default config. |
None
|
system_prompt
|
Optional[str]
|
Optional system prompt override. |
None
|
session_id
|
Optional[str]
|
Optional safe topic identifier. If provided, conversation
history is persisted under
|
None
|
oneshot
|
bool
|
Enable autonomous one-shot guards and acceptance behavior. |
False
|
Source code in src/dashscope_agenticx/sdk.py
64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 | |
run_events
async
¶
run_events(
prompt: str,
config: Optional[Config] = None,
system_prompt: Optional[str] = None,
session_id: Optional[str] = None,
) -> AsyncIterator[AgentEvent]
Run one turn as typed events for TUI, Client, IDE, or automation.
Source code in src/dashscope_agenticx/sdk.py
103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 | |
run_stream
async
¶
run_stream(
prompt: str,
config: Optional[Config] = None,
system_prompt: Optional[str] = None,
session_id: Optional[str] = None,
) -> AsyncIterator[str]
Stream the agent's response for prompt as an async iterator.
Source code in src/dashscope_agenticx/sdk.py
124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 | |
run_once
async
¶
run_once(
prompt: str,
config: Optional[Config] = None,
system_prompt: Optional[str] = None,
session_id: Optional[str] = None,
) -> str
Run one non-interactive turn and return the full response text.
This is the easiest entry point for scripts and CI: it streams the full agent turn, executes any tool calls, and returns the final assistant text.
Source code in src/dashscope_agenticx/sdk.py
145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 | |
run_once_sync
¶
run_once_sync(
prompt: str,
config: Optional[Config] = None,
system_prompt: Optional[str] = None,
session_id: Optional[str] = None,
) -> str
Synchronous wrapper around :func:run_once.
Source code in src/dashscope_agenticx/sdk.py
173 174 175 176 177 178 179 180 | |
run_interactive
¶
run_interactive(
system_prompt: Optional[str] = None,
app_name: str = "Agent",
default_model: str = DEFAULT_MODEL,
default_provider: str = "tongyi",
api_key: Optional[str] = None,
base_url: Optional[str] = None,
command: Optional[str] = None,
prompt_symbol: str = "You> ",
sdk_index: Optional[list[str]] = None,
tui: Optional[bool] = None,
module: str = "",
guide_url: str = "",
) -> None
Run the full agenticx interactive loop with a custom identity.
This is a thin SDK wrapper around the existing embedded mode; see
dashscope_agenticx.ui.embedded.run for details.
Source code in src/dashscope_agenticx/sdk.py
183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 | |
配置(Config)¶
Config
dataclass
¶
Config(
provider: str = "tongyi",
model: str = DEFAULT_MODEL,
thinking_provider: str = "",
thinking_model: str = "",
loop_mode: str = "auto",
tongyi_api_key: str = "",
anthropic_api_key: str = "",
openai_api_key: str = "",
base_url: str = "",
workspace: str = "",
region: str = "",
maas_api_key: str = "",
auto_approve: bool = False,
confirm_mode: str = "all",
max_turns: int = 50,
timeout: int = 30,
mcp_servers: list[MCPServerConfig] = list(),
memory_enabled: bool = True,
memory_user_id: str = "",
memory_library_id: str = "",
platform: str = "bailian",
user_name: str = "",
enabled_capabilities: list[str] | None = None,
custom_models: list[str] = list(),
user_directives: list[str] = list(),
session_persist: bool = True,
asr_model: str = "paraformer-realtime-v2",
voice_silence_duration: float = 2.0,
voice_max_seconds: int = 60,
voice_silence_threshold: int = 500,
tts_enabled: bool = False,
tts_model: str = "cosyvoice-v2",
tts_voice: str = "longxiaochun_v2",
tts_speed: float = 1.0,
subagents: dict[str, SubagentConfig] = dict(),
delegation: DelegationConfig = DelegationConfig(),
theme: dict[str, str] = (
lambda: {
"background": "#ffffff",
"text": "#1e1e1e",
"border": "ansi_blue",
"border_style": "solid",
"accent": "#007acc",
"muted": "#595959",
"panel_border": "blue",
}
)(),
protocol: str = "openai",
tui: bool = True,
tui_mouse: bool = True,
privacy_mode: bool = False,
debug: bool = False,
sandbox: bool = False,
skill_registry: str = "",
fallback_providers: list[str] = list(),
expert_repo: str = "",
expert_branch: str = "main",
)
mcp_servers
class-attribute
instance-attribute
¶
mcp_servers: list[MCPServerConfig] = field(
default_factory=list
)
enabled_capabilities
class-attribute
instance-attribute
¶
enabled_capabilities: list[str] | None = None
custom_models
class-attribute
instance-attribute
¶
custom_models: list[str] = field(default_factory=list)
user_directives
class-attribute
instance-attribute
¶
user_directives: list[str] = field(default_factory=list)
subagents
class-attribute
instance-attribute
¶
subagents: dict[str, SubagentConfig] = field(
default_factory=dict
)
delegation
class-attribute
instance-attribute
¶
delegation: DelegationConfig = field(
default_factory=DelegationConfig
)
theme
class-attribute
instance-attribute
¶
theme: dict[str, str] = field(
default_factory=lambda: {
"background": "#ffffff",
"text": "#1e1e1e",
"border": "ansi_blue",
"border_style": "solid",
"accent": "#007acc",
"muted": "#595959",
"panel_border": "blue",
}
)
fallback_providers
class-attribute
instance-attribute
¶
fallback_providers: list[str] = field(default_factory=list)
load
classmethod
¶
load(
default_provider: str = "tongyi",
default_model: str = DEFAULT_MODEL,
) -> Config
Source code in src/dashscope_agenticx/config.py
555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 | |
save
¶
save()
Source code in src/dashscope_agenticx/config.py
934 935 936 937 938 939 940 941 942 943 944 945 946 | |
save_global
¶
save_global()
Source code in src/dashscope_agenticx/config.py
948 949 950 | |
save_workspace
¶
save_workspace()
Source code in src/dashscope_agenticx/config.py
997 998 999 1000 1001 1002 | |
关键默认值:max_turns=50、timeout=30(每次模型请求的秒数)、
platform="bailian"、memory_enabled=True、session_persist=True。
嵌套配置类型¶
MCPServerConfig
dataclass
¶
MCPServerConfig(
service: str,
url: str = "",
transport: str = "sse",
command: str = "",
args: list[str] = list(),
)
SubagentConfig
dataclass
¶
SubagentConfig(
model: str = "",
temperature: float = 0.0,
max_turns: int = 0,
)
Per-subagent overrides. Only max_turns is applied.
model and temperature are accepted, validated and persisted by
/subagents config, but a subagent shares the parent's provider,
whose model and sampling parameters are fixed when it is constructed.
Nothing reads them.
to_dict
¶
to_dict() -> dict
Source code in src/dashscope_agenticx/config.py
394 395 396 397 398 399 400 401 402 | |
from_dict
classmethod
¶
from_dict(d: dict) -> SubagentConfig
Source code in src/dashscope_agenticx/config.py
404 405 406 407 408 409 410 | |
DelegationConfig
dataclass
¶
DelegationConfig(
max_concurrent: int = 5,
default_timeout: int = 120,
allow_nested: bool = False,
)
Configuration for the delegate tool.
to_dict
¶
to_dict() -> dict
Source code in src/dashscope_agenticx/config.py
421 422 423 424 425 426 | |
from_dict
classmethod
¶
from_dict(d: dict) -> DelegationConfig
Source code in src/dashscope_agenticx/config.py
428 429 430 431 432 433 434 435 | |
模型辅助函数¶
context_window_for_model
¶
context_window_for_model(model: str) -> int
Return the context window (tokens) for a model name.
Prefix-matched against MODEL_CONTEXT_WINDOWS (longest prefix first) so versioned aliases (qwen-turbo-2025-04-28, gpt-4o-2024-...) resolve; unknown models get the conservative default.
Source code in src/dashscope_agenticx/config.py
256 257 258 259 260 261 262 263 264 265 266 | |
normalize_model_name
¶
normalize_model_name(model: str) -> str
Strip surrounding whitespace and normalize model names to lowercase.
Source code in src/dashscope_agenticx/config.py
269 270 271 | |
register_custom_model
¶
register_custom_model(
config: "Config",
provider: str,
model: str,
*,
persist: bool = True
) -> str
Register a custom model: normalize, merge into PROVIDER_MODELS, persist to workspace.
Source code in src/dashscope_agenticx/config.py
274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 | |
is_vision_model
¶
is_vision_model(model: str) -> bool
True if the model name starts with any registered vision-model prefix.
Source code in src/dashscope_agenticx/config.py
312 313 314 315 | |
is_audio_model
¶
is_audio_model(model: str) -> bool
True if the model name starts with any registered audio-model prefix.
Source code in src/dashscope_agenticx/config.py
318 319 320 | |