Embedding the SDK¶
AgenticX exposes a small public SDK in dashscope_agenticx.sdk. Every entry
point runs a complete agent turn — model invocation plus tool execution —
not a bare chat completion.
from dashscope_agenticx.sdk import (
load_config,
create_agent,
run_once,
run_once_sync,
run_stream,
run_events,
run_interactive,
)
One-shot turns¶
run_once_sync is the easiest entry point for scripts and CI: it streams the
full turn, executes any tool calls, and returns the final assistant text.
from dashscope_agenticx.sdk import run_once_sync
reply = run_once_sync("Inspect this project's structure without changing files")
print(reply)
The async equivalent is run_once. Both enable one-shot guards and
acceptance behavior internally; tool execution still respects your
permission policy (default confirm_mode = "all" — see
Security).
Configuration overrides¶
load_config reads the normal layered configuration (global → workspace →
environment); explicit arguments only fill in missing values, they do not
override what configuration or environment already set:
from dashscope_agenticx.sdk import load_config, run_once_sync
config = load_config(provider="tongyi", model="qwen-plus")
reply = run_once_sync("Summarize this directory", config=config)
To force a provider/model regardless of configuration, set
AGENTICX_PROVIDER / AGENTICX_MODEL in the environment. See
Configuration.
Streaming text¶
run_stream yields response text chunks as an async iterator. Tool display
text is interleaved with model output, exactly as the terminal shows it:
import asyncio
from dashscope_agenticx.sdk import run_stream
async def main():
async for chunk in run_stream("Write a haiku about the sea"):
print(chunk, end="", flush=True)
asyncio.run(main())
If you stop consuming early, close the generator so the agent's runtime is released:
import contextlib
async with contextlib.aclosing(run_stream("Long task")) as chunks:
async for chunk in chunks:
if "STOP" in chunk:
break
The convenience wrappers (run_once, run_stream, run_events) create and
close their own agent. When you manage an agent yourself, use async with
or call await agent.aclose().
Typed events¶
run_events is the canonical execution API. It yields
AgentEventEnvelope objects (alias AgentEvent) with a type, a payload
dict, and correlation fields (session_id, run_id, turn_id, sequence,
event_id, timestamp). Consume events instead of parsing terminal output:
import asyncio
from dashscope_agenticx.sdk import run_events, AgentEventType
async def main():
async for event in run_events("Summarize the project"):
if event.type == AgentEventType.MESSAGE_DELTA:
print(event.payload["text"], end="", flush=True)
elif event.type == AgentEventType.TOOL_STARTED:
print(f"\n[tool] {event.payload.get('name', '')}")
elif event.type == AgentEventType.TURN_FINISHED:
print("\n[done]")
asyncio.run(main())
Notes on the event contract:
MESSAGE_DELTApayloads carrytext; tool display deltas additionally carrykind="tool",tool_call_id, andname. Filter onkindif you want model text only.TURN_FINISHEDcarries the finaloutputtext and thetoolsused.- Failures emit an
ERRORevent (error_type,message) and then re-raise the exception — handle both if you need graceful degradation. There is no unified exception tree; catch standard exceptions around the iterator. - An
Agentruns one event stream at a time; a second concurrentrun_eventson the same agent raisesRuntimeError.
The full 15-event table is in the Agent & Events reference.
Sessions and custom agents¶
create_agent gives you an explicit Agent with a system prompt override
and optional persistent session:
import asyncio
from dashscope_agenticx.sdk import create_agent
async def main():
async with create_agent(
system_prompt="You are a careful code reviewer.",
session_id="review-2026-11",
) as agent:
async for chunk in agent.run_stream("Review src/app.py"):
print(chunk, end="")
# A second turn continues the same conversation history.
async for chunk in agent.run_stream("Now suggest fixes."):
print(chunk, end="")
asyncio.run(main())
With session_id, history persists under
.agenticx/session/<id>/history.json and survives process restarts. Without
it, the conversation lives only in memory.
Embedding the interactive loop¶
run_interactive launches the full AgenticX interactive experience (REPL or
TUI) under your own product identity — this is how the DashScope SDK Expert
is packaged:
from dashscope_agenticx.sdk import run_interactive
run_interactive(
system_prompt="You are an expert on myproduct.",
app_name="MyProduct Expert",
prompt_symbol="myproduct> ",
command="myproduct",
)
It accepts provider/model defaults, api_key/base_url, an sdk_index
for documentation lookup, and tui=True/False to force the interface.
Lower-level integration¶
For full control, construct a Runtime directly with RuntimeBuilder and
create agents from it; see the
Agent, Runtime & Events reference. The localhost
Server exposes the same event
stream over HTTP for non-Python clients.