SDK & Config¶
The embeddable SDK lives in dashscope_agenticx.sdk — a stable, typed
surface on top of the agent runtime for scripts, CI pipelines, IDE
plugins, and other Python programs. For a task-oriented walkthrough see
Embedding the SDK; for config files and environment
variables see Configuration.
from dashscope_agenticx.sdk import run_once_sync
print(run_once_sync("Summarize README.md"))
Import path
Import from dashscope_agenticx.sdk. The top-level package re-exports
the most common helpers, but the sdk module is the documented,
complete surface.
Configuration resolution¶
Config.load() merges three layers, in increasing priority:
- Global config:
~/.config/AgenticX/config.toml - Workspace config:
./.agenticx/config.toml - Environment variables fill remaining gaps (
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 and
AGENTICX_MCP_SERVERS force-override the resolved values.
load_config() in the SDK applies caller-supplied arguments only where
the resolved config still has gaps.
Config.api_key is a property that routes to the per-provider key field
(tongyi_api_key, anthropic_api_key, openai_api_key) based on
Config.provider.
SDK entry points¶
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 | |
Key defaults: max_turns=50, timeout=30 (seconds per model request),
platform="bailian", memory_enabled=True, session_persist=True.
Nested config types¶
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 | |
Model helpers¶
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 | |