DashScope AgenticX
Enterprise AI experts, built to act.
AgenticX 1.0 is a Python Agent Runtime for building and running domain experts. It connects models, tools, Skills, permissions, and persistent sessions through one runtime, with a terminal interface and APIs for embedded applications.
Use it directly as a local assistant, embed it in a Python application, or package a domain expert as a versioned App Bundle. DashScope SDK Expert and Bailian Expert are bundled Expert templates illustrating this application layer.
What AgenticX Provides
| Layer | Capability |
|---|---|
| Runtime | Instance-owned tool, Skill, hook, and session state; shared construction through RuntimeBuilder |
| Agent execution | Model invocation, tool coordination, run guards, and session persistence |
| Events | Typed AgentEventEnvelope events for messages, tools, permissions, usage, and artifacts |
| Applications | Versioned App manifests, Runtime compatibility, permission diffs, and checksum verification |
| Interfaces | CLI, Textual TUI, Python SDK, embedded entry points, and a token-authenticated localhost Server |
| Model access | Tongyi/DashScope, plus optional provider SDKs and declarative provider configuration |
| Extension points | System prompts, Skills, HTTP/Shell tools, MCP services, and governed hooks |
Voice, camera, browser, web search, scheduler, and experimental features are optional. They are not prerequisites for the core Runtime. AgenticX is not a hosted service, a hardened OS sandbox, or a complete workflow platform.
Installation
Python 3.10+ is required. Pillow-backed vision and media extras require
Python 3.11+; all omits Pillow on Python 3.10.
CI includes Python 3.10–3.13 tests and
Ubuntu/macOS/Windows smoke checks; those checks are not a guarantee that every
optional device or sandbox backend works on every OS.
Install the Python Package
Package installation requires a published distribution. For a source-only release or an unpublished checkout, use Install from Source below.
python -m pip install "dashscope-agenticx[tui]"
agenticx --version
For a minimal, non-TUI installation, use
python -m pip install dashscope-agenticx and start with agenticx --cli.
Install from Source
For development, run these commands in your repository checkout:
python -m venv .venv
# macOS / Linux
source .venv/bin/activate
# Windows PowerShell: .venv\Scripts\Activate.ps1
python -m pip install -e ".[tui]"
agenticx --version
The Python distribution is dashscope-agenticx, the import namespace is
dashscope_agenticx, and the only official command is agenticx.
The bare agenticx PyPI distribution is a different project. See the
release process for binary builds and release requirements.
Optional Dependencies
Choose only what you need; for a source checkout, use the equivalent extras
with python -m pip install -e ".[<extras>]".
| Extra | Install | Purpose |
|---|---|---|
| TUI | python -m pip install "dashscope-agenticx[tui]" |
Fixed input panel and rich terminal output |
| Provider SDKs | python -m pip install "dashscope-agenticx[provider-openai,provider-anthropic]" |
Provider-specific SDK routes |
| Web / browser | python -m pip install "dashscope-agenticx[web,browser]" |
Search and browser tools; browser runtime setup is separate |
| Media | python -m pip install "dashscope-agenticx[voice,camera,vision]" |
Audio, camera, and image dependencies |
| Development | python -m pip install -e ".[dev,all]" |
Test/build tooling and optional feature dependencies |
See the user guide for backend setup and capability configuration. Installing dependencies does not grant an App permissions.
Quick Start
For the default Tongyi/DashScope provider, supply an API key through your process environment:
export DASHSCOPE_API_KEY="<your-api-key>"
# Windows PowerShell: $env:DASHSCOPE_API_KEY="<your-api-key>"
agenticx
Use /setup to configure your workspace, or /provider to select a model.
Do not paste real API keys into tracked configuration or example files.
agenticx --cli # Inline REPL with terminal scrollback
agenticx --tui # Textual interface (requires the TUI extra)
agenticx -c "List the files in this directory and summarize the project"
Inside an interactive session:
agenticx> Summarize this project's structure before making any edits
agenticx> /help
agenticx> /copy
agenticx> /session
One-shot runs can execute tools, not just generate text. Start in a suitable workspace and choose permissions appropriate to the task.
Terminal Output
- Responses render as Markdown, with numbered turns and completion status.
- Tool details collapse by default; failures remain expanded. Click the
summary or use
Ctrl+Oto toggle retained details. Ctrl+Gexpands token, API, tool, and prompt-composition statistics. Prompt sizes are characters, not exact model-token counts; cached tokens are included in input usage, not an additional chargeable token total.- Selection copying uses
Cmd+Con macOS andCtrl+Con Windows/Linux. The bottom Copy button copies the captured selection without relying on terminal key forwarding. Selecting and successful copying show no toast. - On macOS,
Ctrl+Cclears/cancels/quits; it does not copy a selection. /copycopies the latest response source. For native terminal scrollback and selection, choose--clirather than the alternate-screen TUI.
Python API
The convenience API runs a complete turn, including tool calls:
from dashscope_agenticx import run_once_sync
reply = run_once_sync("Inspect this project's structure without changing files")
print(reply)
For application integration, consume structured events instead of parsing terminal output:
import asyncio
from dashscope_agenticx import run_events
async def main():
async for event in run_events("Summarize the project"):
print(event.type.value, event.payload)
asyncio.run(main())
create_agent supports explicit configuration, a system prompt, and a
session ID. Use run_interactive for embedding the interactive experience.
Lower-level integrations can construct a Runtime with RuntimeBuilder;
see the API reference.
Configuration and Apps
Workspace configuration lives under .agenticx/. Global configuration uses
the platform-standard AgenticX directory; AGENTICX_HOME overrides it.
| File | Purpose |
|---|---|
config.toml |
Models, capabilities, and interaction settings |
system-prompt.md |
Domain role and behavioral instructions |
skills/ |
Markdown Skills and directory-based Skill packages |
custom-extensions.toml |
Declarative providers and HTTP/Shell tools |
permissions.toml |
Tool and command allow/deny/confirm policies |
hooks.toml |
Event hooks subject to trust and permission controls |
session/ |
Persistent conversations and run records |
A production App Bundle combines a versioned app.toml manifest, an
.agenticx/ profile, and optional eval/acceptance files. Manage local Apps
with:
agenticx app list
agenticx app install ./path/to/app-bundle
agenticx app info <app-name>
agenticx app verify <app-name>
agenticx app update <app-name>
For example, install and verify DashScope SDK Expert from the official App Catalog:
python -m pip install "dashscope-agenticx>=1.0.1,<2"
git clone https://github.com/dashscope/dashscope-agenticx-experts.git
cd dashscope-agenticx-experts
agenticx app install ./apps/dashscope-sdk-expert
agenticx app info dashscope-sdk-expert
agenticx app verify dashscope-sdk-expert
app install only installs and registers the versioned App under the current
workspace's .agenticx/apps/; it does not activate the App profile. After the
cd above, the cloned repository is that workspace. To run DashScope SDK Expert,
merge its profile into the workspace and start AgenticX:
export DASHSCOPE_API_KEY="<your-api-key>"
agenticx expert download dashscope-sdk-expert
agenticx
Expert downloads are not registered as Apps and cannot be managed with app list or app update. app update reinstalls from the recorded source, so run
git pull in the clone before updating a locally cloned App.
The source tree includes dashscope-sdk-expert and bailian-expert bundles.
Inspect the manifest and requested permissions before installation. A checksum
proves content identity, not publisher authenticity; a local trust flag is not
a verified digital signature. /expert manages role templates, not a substitute
for the versioned App installation contract.
Security and Compatibility
- Store new credentials through the OS keyring or supply environment variables.
Do not treat legacy
ENC:values as secure encryption. - Trust and permission checks govern App code, shell hooks, and tool execution. Do not label an unknown bundle verified merely to bypass those checks.
- Default
confirm_mode = "all"requires approval for write/confirm tools. Explicit policy denies also apply to AUTO tools andauto_approveruns. - Expert downloads contain role/configuration data, not executable Python, Shell tools, or run hooks. App installation previews new permissions before writing files; granting trust is not an OS sandbox or a network allowlist.
- OS sandbox support is defense in depth. Availability and limitations depend on the backend; review the reported execution boundary before automation.
- The localhost Server requires a bearer token and does not accept remote permission approvals; it denies actions requiring approval even when the local CLI configuration enables automatic execution. It is not an Internet-facing deployment contract.
- Legacy directory migration is one-way; existing destinations are not merged or overwritten. Imports and environment variables need an explicit update.
Read the security policy and 1.0 migration guide before upgrading or installing third-party applications.
Development
python -m pip install -e ".[dev,all]"
python -m pip install pre-commit
python -m pytest tests/ -q
python scripts/release_check.py
pre-commit run --all-files
The release contract checks package identity, version, imports, CLI, and bundled Apps. Coverage gates, cross-platform CI, App validation, and supply-chain checks are separate release requirements; passing local unit tests alone does not publish or certify a final 1.0 release.
Documentation
| Document | Contents |
|---|---|
| User guide / 中文手册 | Full commands, configuration, tools, modules, and development reference |
| Migration | Legacy naming, directories, credentials, and compatibility |
| Changelog | 1.0 release notes, upcoming changes, and archived release history |
| Contributing | Development conventions and contribution requirements |
| Security | Security boundaries and private reporting |
| Release process | Packaging, checksums, SBOM, and publication gates |
License
MIT, as declared in pyproject.toml.
Metadata
Release files for dashscope-agenticx 1.0.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| dashscope_agenticx-1.0.1.tar.gz | 513.9 kB | With provenance | Details for dashscope_agenticx-1.0.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| dashscope_agenticx-1.0.1-py3-none-any.whl | Python 3 | none | any | Details for dashscope_agenticx-1.0.1-py3-none-any.whl |
Total release size: 991.6 kB
Release files / dashscope_agenticx-1.0.1.tar.gz
| Download URL | dashscope_agenticx-1.0.1.tar.gz |
|---|---|
| Size | 513.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
37da5b38a818c4dd8a8b355871cfa7f4b3258efae4a58d12fccebdd3a30d7553
|
|
BLAKE2b-256 checksum How to use checksums |
0f23f5b7826c02c42c0a24f9450cbda96dc8854463586fc3bd2a95932f80791a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.
Transparency logRelease files / dashscope_agenticx-1.0.1-py3-none-any.whl
| Download URL | dashscope_agenticx-1.0.1-py3-none-any.whl |
|---|---|
| Size | 477.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7a0aa31fb4c67fc1c99b07cddb0f2b36509a3aefdd50a3edf831d8d9a77db951
|
|
BLAKE2b-256 checksum How to use checksums |
cad3d04ac40dac7c5d53ed7b446dfcd1e372522c24884e439244ba28417791f8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.
Transparency logSecurity for dashscope-agenticx 1.0.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for dashscope_agenticx-1.0.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.