跳转至内容

模型提供者

Provider 将模型后端适配到统一协议(LLMProvider:chat、 chat_stream、aclose)。内置的 Tongyi Provider 直接通过 httpx 与 DashScope 通信;OpenAI 与 Anthropic Provider 是可选扩展。

Provider 安装 说明
tongyi(默认) 核心 通过 httpx 访问 DashScope 原生生成端点
openai pip install "dashscope-agenticx[provider-openai]" OpenAI 及兼容网关
anthropic pip install "dashscope-agenticx[provider-anthropic]" Anthropic Messages API

自定义 Provider 可在 .agenticx/custom-extensions.toml 中声明,无需 编写 Python — 参见 工具、技能与专家。

路由遵循 Config.fallback_providers、MaaS 网关设置(workspace、 region、maas_api_key)以及由配置构建的各 Provider 档案。瞬时故障 由加固封装层重试;provider.switched 事件报告路由变化。

协议与共享类型

LLMProvider

Bases: Protocol

aclose async

aclose() -> None
Source code in src/dashscope_agenticx/providers/base.py
57
58
async def aclose(self) -> None:
    ...

chat async

chat(
    messages: list[dict],
    tools: list[dict] | None = None,
    response_format: dict | None = None,
) -> LLMResponse
Source code in src/dashscope_agenticx/providers/base.py
60
61
62
63
64
65
66
async def chat(
    self,
    messages: list[dict],
    tools: list[dict] | None = None,
    response_format: dict | None = None,
) -> LLMResponse:
    ...

chat_stream

chat_stream(
    messages: list[dict],
    tools: list[dict] | None = None,
    response_format: dict | None = None,
) -> AsyncIterator[LLMChunk]
Source code in src/dashscope_agenticx/providers/base.py
68
69
70
71
72
73
74
def chat_stream(
    self,
    messages: list[dict],
    tools: list[dict] | None = None,
    response_format: dict | None = None,
) -> AsyncIterator[LLMChunk]:
    ...

ToolCall dataclass

ToolCall(
    id: str,
    name: str,
    arguments: dict,
    truncated: bool = False,
)

id instance-attribute

id: str

name instance-attribute

name: str

arguments instance-attribute

arguments: dict

truncated class-attribute instance-attribute

truncated: bool = False

LLMResponse dataclass

LLMResponse(
    content: str = "",
    tool_calls: list[ToolCall] = list(),
    reasoning_content: str = "",
    usage: dict | None = None,
)

content class-attribute instance-attribute

content: str = ''

tool_calls class-attribute instance-attribute

tool_calls: list[ToolCall] = field(default_factory=list)

reasoning_content class-attribute instance-attribute

reasoning_content: str = ''

usage class-attribute instance-attribute

usage: dict | None = None

LLMChunk dataclass

LLMChunk(
    delta_content: str = "",
    delta_reasoning_content: str = "",
    tool_calls: list[ToolCall] = list(),
    finish_reason: str | None = None,
    usage: dict | None = None,
)

delta_content class-attribute instance-attribute

delta_content: str = ''

delta_reasoning_content class-attribute instance-attribute

delta_reasoning_content: str = ''

tool_calls class-attribute instance-attribute

tool_calls: list[ToolCall] = field(default_factory=list)

finish_reason class-attribute instance-attribute

finish_reason: str | None = None

usage class-attribute instance-attribute

usage: dict | None = None

内置 Provider

TongyiProvider

TongyiProvider(
    model: str = DEFAULT_MODEL,
    api_key: str | None = None,
    request_timeout: int = 60,
    protocol: str = "openai",
    base_url: str | None = None,
    module: str = "app",
    max_output_tokens: int | None = None,
    thinking_budget: int | None = None,
)
Source code in src/dashscope_agenticx/providers/tongyi.py
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
def __init__(
    self,
    model: str = DEFAULT_MODEL,
    api_key: str | None = None,
    request_timeout: int = 60,
    protocol: str = "openai",
    base_url: str | None = None,
    module: str = "app",
    max_output_tokens: int | None = None,
    thinking_budget: int | None = None,
):
    self.model = normalize_model_name(model)
    self.api_key = api_key
    self.request_timeout = request_timeout
    self.protocol = protocol
    # Per-call output cap (reasoning tokens count against it). The
    # failure shape this exists for: a run of 15-minute, ~25K-token
    # monolithic generations that never lands a deliverable before the
    # wall-clock cap — with no cap the agent loop never regains control
    # between request boundaries, so every between-turn mechanism (time
    # budget, convergence, reflection) is unreachable. Truncation is
    # safe: the stream assembly repairs or empties a cut tool call, and
    # the agent treats finish_reason=length as "continue", not "done".
    # Env: AGENTICX_MAX_OUTPUT_TOKENS (0/unset disables).
    if max_output_tokens is None:
        try:
            max_output_tokens = int(
                os.environ.get("AGENTICX_MAX_OUTPUT_TOKENS", "0"),
            )
        except ValueError:
            max_output_tokens = 0
    self.max_output_tokens = max(0, max_output_tokens)
    # Reasoning-token budget. Probing qwen3.8-max on the native
    # multimodal-generation path showed max_tokens caps only the
    # visible text (100 → 284 output tokens incl. 180 reasoning), so
    # the monolithic-thinking shape sails past it untouched;
    # thinking_budget bounds the reasoning itself (200 → exactly 200).
    # When the budget runs out the server wraps up the turn with
    # finish_reason=stop, so the agent loop regains control without
    # needing the length-continuation branch. Env:
    # AGENTICX_THINKING_BUDGET (0/unset disables).
    if thinking_budget is None:
        try:
            thinking_budget = int(
                os.environ.get("AGENTICX_THINKING_BUDGET", "0"),
            )
        except ValueError:
            thinking_budget = 0
    self.thinking_budget = max(0, thinking_budget)
    base = (base_url or DASHSCOPE_BASE_URL).rstrip("/")
    for prefix in _LEGACY_PREFIXES:
        if base.endswith(prefix):
            base = base[: -len(prefix)]
            break
    self.base_url = base
    self.module = module
    self._generation_path = self._learned_paths().get(
        model,
        _GENERATION_PATHS[0],
    )

model instance-attribute

model = normalize_model_name(model)

api_key instance-attribute

api_key = api_key

request_timeout instance-attribute

request_timeout = request_timeout

protocol instance-attribute

protocol = protocol

max_output_tokens instance-attribute

max_output_tokens = max(0, max_output_tokens)

thinking_budget instance-attribute

thinking_budget = max(0, thinking_budget)

base_url instance-attribute

base_url = base

module instance-attribute

module = module

aclose async

aclose() -> None

Requests own their HTTP clients; no persistent transport is held.

Source code in src/dashscope_agenticx/providers/tongyi.py
328
329
async def aclose(self) -> None:
    """Requests own their HTTP clients; no persistent transport is held."""

chat async

chat(
    messages: list[dict],
    tools: list[dict] | None = None,
    response_format: dict | None = None,
) -> LLMResponse
Source code in src/dashscope_agenticx/providers/tongyi.py
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
async def chat(
    self,
    messages: list[dict],
    tools: list[dict] | None = None,
    response_format: dict | None = None,
) -> LLMResponse:
    # If protocol is anthropic, convert input from Anthropic to
    # OpenAI format
    if self.protocol == "anthropic":
        from dashscope_agenticx.providers.adapter import (
            anthropic_to_openai_request,
        )

        # Agent may send system as first message, extract it
        system_msg = None
        if messages and messages[0].get("role") == "system":
            system_msg = messages[0].get("content")
            messages = messages[1:]
        converted = anthropic_to_openai_request(
            messages,
            system=system_msg,
            tools=tools,
        )
        messages = converted["messages"]
        tools = converted["tools"]

    body = self._build_request_body(
        messages,
        tools,
        stream=False,
        response_format=response_format,
    )
    headers = self._get_headers()

    try:
        async with httpx.AsyncClient(
            timeout=self.request_timeout,
        ) as client:
            paths = self._candidate_paths()
            for i, path in enumerate(paths):
                response = await client.post(
                    f"{self.base_url}{path}",
                    json=body,
                    headers=headers,
                )
                if response.status_code == 200:
                    self._commit_path(path)
                    break
                if i + 1 < len(paths) and _is_url_error(
                    response.status_code,
                    response.text,
                ):
                    continue  # model lives on the other service path
                raise RuntimeError(
                    f"DashScope API error: {response.status_code} - "
                    f"{response.text}",
                )
    except httpx.TimeoutException as e:
        raise RuntimeError(
            "API request timed out; check network or retry later",
        ) from e
    except httpx.ConnectError as e:
        raise RuntimeError(
            "Cannot connect to API server; check network",
        ) from e

    raw = response.json()
    if raw.get("code"):
        raise RuntimeError(
            f"DashScope API error: {raw.get('code')} - "
            f"{raw.get('message')}",
        )
    data = _native_to_openai_response(raw)
    if not data["choices"]:
        raise RuntimeError(
            f"DashScope API error: unexpected response: {raw}",
        )

    # If protocol is anthropic, convert output from OpenAI to
    # Anthropic format
    if self.protocol == "anthropic":
        from dashscope_agenticx.providers.adapter import (
            anthropic_to_openai_response,
            openai_to_anthropic_response,
        )

        anthropic_resp = openai_to_anthropic_response(data)
        # Extract content and tool_calls from Anthropic format
        extracted = anthropic_to_openai_response(anthropic_resp)
        reasoning = ""  # Anthropic format doesn't have reasoning_content
        usage = anthropic_resp.get("usage", {})
        return LLMResponse(
            content=extracted["content"],
            tool_calls=self._parse_tool_calls(extracted["tool_calls"]),
            reasoning_content=reasoning,
            usage={
                "input_tokens": usage.get("input_tokens", 0),
                "output_tokens": usage.get("output_tokens", 0),
                "total_tokens": usage.get("input_tokens", 0)
                + usage.get("output_tokens", 0),
                "cached_tokens": usage.get("cache_read_input_tokens", 0)
                or 0,
            },
        )

    choice = data["choices"][0]
    msg = choice["message"]
    content = msg.get("content", "") or ""
    reasoning = msg.get("reasoning_content", "") or ""
    raw_calls = msg.get("tool_calls", []) or []
    usage = _extract_usage(data)

    return LLMResponse(
        content=content,
        tool_calls=self._parse_tool_calls(raw_calls),
        reasoning_content=reasoning,
        usage=usage,
    )

chat_stream async

chat_stream(
    messages: list[dict],
    tools: list[dict] | None = None,
    response_format: dict | None = None,
) -> AsyncIterator[LLMChunk]
Source code in src/dashscope_agenticx/providers/tongyi.py
552
553
554
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
async def chat_stream(
    self,
    messages: list[dict],
    tools: list[dict] | None = None,
    response_format: dict | None = None,
) -> AsyncIterator[LLMChunk]:
    # If protocol is anthropic, convert input from Anthropic to
    # OpenAI format
    if self.protocol == "anthropic":
        from dashscope_agenticx.providers.adapter import (
            anthropic_to_openai_request,
        )

        # Agent may send system as first message, extract it
        system_msg = None
        if messages and messages[0].get("role") == "system":
            system_msg = messages[0].get("content")
            messages = messages[1:]
        converted = anthropic_to_openai_request(
            messages,
            system=system_msg,
            tools=tools,
        )
        messages = converted["messages"]
        tools = converted["tools"]

    body = self._build_request_body(
        messages,
        tools,
        stream=True,
        response_format=response_format,
    )
    headers = self._get_headers(stream=True)

    try:
        async with httpx.AsyncClient(
            timeout=self.request_timeout,
        ) as client:
            paths = self._candidate_paths()
            for i, path in enumerate(paths):
                async with client.stream(
                    "POST",
                    f"{self.base_url}{path}",
                    json=body,
                    headers=headers,
                ) as response:
                    if response.status_code != 200:
                        error_body = await response.aread()
                        text = error_body.decode()
                        if i + 1 < len(paths) and _is_url_error(
                            response.status_code,
                            text,
                        ):
                            continue  # model on the other service path
                        raise RuntimeError(
                            f"DashScope API error: "
                            f"{response.status_code} - {text}",
                        )
                    # The url error also arrives as a 200 SSE error
                    # event, so commit to (and cache) this path only
                    # after the first real chunk; before that, trying
                    # the other path is still safe.
                    stream = self._iter_stream(response)
                    try:
                        first = await stream.__anext__()
                    except StopAsyncIteration:
                        self._commit_path(path)
                        return
                    except _StreamAPIError as e:
                        if i + 1 < len(paths) and _is_url_error_message(
                            e.message,
                        ):
                            continue
                        raise
                    self._commit_path(path)
                    yield first
                    async for chunk in stream:
                        yield chunk
                    return
    except httpx.TimeoutException as e:
        raise RuntimeError(
            "API request timed out; check network or retry later",
        ) from e
    except httpx.ConnectError as e:
        raise RuntimeError(
            "Cannot connect to API server; check network",
        ) from e

OpenAIProvider

OpenAIProvider(
    model: str = "gpt-4o",
    api_key: str | None = None,
    base_url: str | None = None,
    module: str = "app",
)
Source code in src/dashscope_agenticx/providers/openai.py
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
def __init__(
    self,
    model: str = "gpt-4o",
    api_key: str | None = None,
    base_url: str | None = None,
    module: str = "app",
):
    if AsyncOpenAI is None:
        raise ImportError(
            "openai package not installed. "
            "Run: pip install 'dashscope-agenticx[provider-openai]'",
        )
    from dashscope_agenticx.config import normalize_model_name

    self.model = normalize_model_name(model)
    self.client = AsyncOpenAI(
        api_key=api_key,
        base_url=base_url,
        default_headers=dashscope_sdk_headers(
            module,
            base_url=base_url or "",
        ),
    )

model instance-attribute

model = normalize_model_name(model)

client instance-attribute

client = AsyncOpenAI(
    api_key=api_key,
    base_url=base_url,
    default_headers=dashscope_sdk_headers(
        module, base_url=base_url or ""
    ),
)

aclose async

aclose() -> None
Source code in src/dashscope_agenticx/providers/openai.py
42
43
async def aclose(self) -> None:
    await self.client.close()

chat async

chat(
    messages: list[dict],
    tools: list[dict] | None = None,
    response_format: dict | None = None,
) -> LLMResponse
Source code in src/dashscope_agenticx/providers/openai.py
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
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
171
172
173
174
175
176
177
async def chat(
    self,
    messages: list[dict],
    tools: list[dict] | None = None,
    response_format: dict | None = None,
) -> LLMResponse:
    converted = self._convert_messages(messages)
    kwargs: dict = {
        "model": self.model,
        "messages": converted,
    }
    oai_tools = self._convert_tools(tools)
    if oai_tools:
        kwargs["tools"] = oai_tools
    if response_format:
        kwargs["response_format"] = response_format

    try:
        response = await self.client.chat.completions.create(**kwargs)
    except Exception as e:
        if getattr(e, "status_code", None) == 404:
            raise RuntimeError(
                "API endpoint not found (404): base_url may not match "
                "protocol; run /provider to check config",
            ) from e
        raise

    msg = response.choices[0].message
    content = msg.content or ""
    reasoning = getattr(msg, "reasoning_content", None) or ""
    tool_calls = []
    if msg.tool_calls:
        for tc in msg.tool_calls:
            args = tc.function.arguments
            if isinstance(args, str):
                try:
                    args = json.loads(args)
                except json.JSONDecodeError:
                    args = {}
            tool_calls.append(
                ToolCall(
                    id=tc.id,
                    name=tc.function.name,
                    arguments=args,
                ),
            )

    usage = None
    resp_usage = getattr(response, "usage", None)
    if resp_usage is not None:
        details = getattr(resp_usage, "prompt_tokens_details", None)
        usage = {
            "input_tokens": getattr(resp_usage, "prompt_tokens", 0) or 0,
            "output_tokens": getattr(resp_usage, "completion_tokens", 0)
            or 0,
            "total_tokens": getattr(resp_usage, "total_tokens", 0) or 0,
            "cached_tokens": (
                (getattr(details, "cached_tokens", 0) or 0)
                if details
                else 0
            ),
        }

    return LLMResponse(
        content=content,
        tool_calls=tool_calls,
        reasoning_content=reasoning,
        usage=usage,
    )

chat_stream async

chat_stream(
    messages: list[dict],
    tools: list[dict] | None = None,
    response_format: dict | None = None,
) -> AsyncIterator[LLMChunk]
Source code in src/dashscope_agenticx/providers/openai.py
179
180
181
182
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
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
async def chat_stream(
    self,
    messages: list[dict],
    tools: list[dict] | None = None,
    response_format: dict | None = None,
) -> AsyncIterator[LLMChunk]:
    converted = self._convert_messages(messages)
    kwargs: dict = {
        "model": self.model,
        "messages": converted,
        "stream": True,
    }
    oai_tools = self._convert_tools(tools)
    if oai_tools:
        kwargs["tools"] = oai_tools
    if response_format:
        kwargs["response_format"] = response_format
    # Ask for a terminal usage-only chunk (choices=[]) so /stats works
    # in streaming mode; backends that don't support it simply omit it.
    kwargs["stream_options"] = {"include_usage": True}

    # Track tool calls being assembled across chunks
    pending_tools: dict[int, dict] = {}
    stream_usage: dict | None = None
    pending_finish: str | None = None

    try:
        stream = await self.client.chat.completions.create(**kwargs)
    except Exception as e:
        if getattr(e, "status_code", None) == 404:
            raise RuntimeError(
                "API endpoint not found (404): base_url may not match "
                "protocol; run /provider to check config",
            ) from e
        raise
    async for chunk in stream:
        if not chunk.choices:
            # Terminal usage-only chunk (stream_options.include_usage).
            usage = getattr(chunk, "usage", None)
            if usage is not None:
                details = getattr(usage, "prompt_tokens_details", None)
                stream_usage = {
                    "input_tokens": getattr(usage, "prompt_tokens", 0)
                    or 0,
                    "output_tokens": getattr(usage, "completion_tokens", 0)
                    or 0,
                    "total_tokens": getattr(usage, "total_tokens", 0) or 0,
                    "cached_tokens": (
                        (getattr(details, "cached_tokens", 0) or 0)
                        if details
                        else 0
                    ),
                }
            continue

        delta = chunk.choices[0].delta
        if delta is None:
            continue
        finish_reason = chunk.choices[0].finish_reason

        if delta.content:
            yield LLMChunk(delta_content=delta.content)

        delta_reasoning = getattr(delta, "reasoning_content", None)
        if delta_reasoning:
            yield LLMChunk(delta_reasoning_content=delta_reasoning)

        if delta.tool_calls:
            for tc_delta in delta.tool_calls:
                idx = tc_delta.index
                if idx not in pending_tools:
                    pending_tools[idx] = {
                        "id": tc_delta.id or "",
                        "name": (
                            tc_delta.function.name or ""
                            if tc_delta.function
                            else ""
                        ),
                        "arguments": "",
                    }
                else:
                    if tc_delta.id:
                        pending_tools[idx]["id"] = tc_delta.id
                    if tc_delta.function and tc_delta.function.name:
                        pending_tools[idx]["name"] = tc_delta.function.name
                if tc_delta.function and tc_delta.function.arguments:
                    pending_tools[idx][
                        "arguments"
                    ] += tc_delta.function.arguments

        if finish_reason == "tool_calls":
            for tool_data in pending_tools.values():
                raw_args = tool_data["arguments"]
                truncated = False
                try:
                    args = json.loads(raw_args) if raw_args else {}
                except json.JSONDecodeError:
                    try:
                        args = json.loads(raw_args + '"}')
                    except json.JSONDecodeError:
                        args = {}
                        truncated = True
                yield LLMChunk(
                    tool_calls=[
                        ToolCall(
                            id=tool_data["id"],
                            name=tool_data["name"],
                            arguments=args,
                            truncated=truncated,
                        ),
                    ],
                )
            pending_tools.clear()
            pending_finish = finish_reason
        elif finish_reason:
            # "stop" / "length" / ... — hold until stream end so the
            # usage-only chunk (arriving after finish) can be attached.
            pending_finish = finish_reason

    if pending_finish:
        yield LLMChunk(finish_reason=pending_finish, usage=stream_usage)

AnthropicProvider

AnthropicProvider(
    model: str = "claude-sonnet-4-20250514",
    api_key: str | None = None,
    base_url: str | None = None,
    timeout: float = 120.0,
    module: str = "app",
)
Source code in src/dashscope_agenticx/providers/anthropic.py
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
def __init__(
    self,
    model: str = "claude-sonnet-4-20250514",
    api_key: str | None = None,
    base_url: str | None = None,
    timeout: float = 120.0,
    module: str = "app",
):
    if anthropic is None:
        raise ImportError(
            "The anthropic package is not installed. "
            "Run: pip install 'dashscope-agenticx[provider-anthropic]'",
        )
    from dashscope_agenticx.config import normalize_model_name

    self.model = normalize_model_name(model)
    self.client = anthropic.AsyncAnthropic(
        api_key=api_key,
        base_url=base_url,
        timeout=timeout,
        default_headers=dashscope_sdk_headers(
            module,
            base_url=base_url or "",
        ),
    )

default_max_tokens class-attribute instance-attribute

default_max_tokens = 4096

model instance-attribute

model = normalize_model_name(model)

client instance-attribute

client = anthropic.AsyncAnthropic(
    api_key=api_key,
    base_url=base_url,
    timeout=timeout,
    default_headers=dashscope_sdk_headers(
        module, base_url=base_url or ""
    ),
)

aclose async

aclose() -> None
Source code in src/dashscope_agenticx/providers/anthropic.py
81
82
async def aclose(self) -> None:
    await self.client.close()

chat async

chat(
    messages: list[dict],
    tools: list[dict] | None = None,
    response_format: dict | None = None,
) -> LLMResponse
Source code in src/dashscope_agenticx/providers/anthropic.py
171
172
173
174
175
176
177
178
179
180
181
182
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
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
async def chat(
    self,
    messages: list[dict],
    tools: list[dict] | None = None,
    response_format: dict | None = None,  # pylint: disable=unused-argument
) -> LLMResponse:
    system, converted = self._convert_messages(messages)
    kwargs: dict = {
        "model": self.model,
        "max_tokens": self.default_max_tokens,
        "messages": converted,
    }
    if system:
        kwargs["system"] = system
    claude_tools = self._convert_tools(tools)
    if claude_tools:
        kwargs["tools"] = claude_tools
    # Anthropic API does not support OpenAI-style response_format;
    # ignore it.

    try:
        response = await self.client.messages.create(**kwargs)
    except httpx.TimeoutException as e:
        raise RuntimeError(
            "API request timeout; check your network or retry later",
        ) from e
    except httpx.ConnectError as e:
        raise RuntimeError(
            "Unable to connect to the API server; check your network",
        ) from e
    except anthropic.NotFoundError as e:
        raise RuntimeError(
            "API endpoint not found (404): base_url and protocol may "
            "not match; run /provider to check the config",
        ) from e
    except anthropic.APIError as e:
        raise RuntimeError(f"API request failed: {e}") from e

    content = ""
    tool_calls = []
    for block in response.content:
        if block.type == "text":
            content += block.text
        elif block.type == "tool_use":
            tool_calls.append(
                ToolCall(
                    id=block.id,
                    name=block.name,
                    arguments=block.input,
                ),
            )

    usage = None
    resp_usage = getattr(response, "usage", None)
    if resp_usage is not None:
        input_tokens = getattr(resp_usage, "input_tokens", 0) or 0
        output_tokens = getattr(resp_usage, "output_tokens", 0) or 0
        usage = {
            "input_tokens": input_tokens,
            "output_tokens": output_tokens,
            "total_tokens": input_tokens + output_tokens,
            "cached_tokens": getattr(
                resp_usage,
                "cache_read_input_tokens",
                0,
            )
            or 0,
        }

    return LLMResponse(content=content, tool_calls=tool_calls, usage=usage)

chat_stream async

chat_stream(
    messages: list[dict],
    tools: list[dict] | None = None,
    response_format: dict | None = None,
) -> AsyncIterator[LLMChunk]
Source code in src/dashscope_agenticx/providers/anthropic.py
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
async def chat_stream(
    self,
    messages: list[dict],
    tools: list[dict] | None = None,
    response_format: dict | None = None,  # pylint: disable=unused-argument
) -> AsyncIterator[LLMChunk]:
    system, converted = self._convert_messages(messages)
    kwargs: dict = {
        "model": self.model,
        "max_tokens": self.default_max_tokens,
        "messages": converted,
    }
    if system:
        kwargs["system"] = system
    claude_tools = self._convert_tools(tools)
    if claude_tools:
        kwargs["tools"] = claude_tools
    # Anthropic API does not support OpenAI-style response_format;
    # ignore it.

    current_tool: dict | None = None
    tool_input_json = ""
    received_content = False
    stream_usage: dict = {
        "input_tokens": 0,
        "output_tokens": 0,
        "cached_tokens": 0,
    }

    try:
        async with self.client.messages.stream(**kwargs) as stream:
            async for event in stream:
                if event.type == "content_block_start":
                    block = event.content_block
                    if block.type == "tool_use":
                        current_tool = {
                            "id": block.id,
                            "name": block.name,
                        }
                        tool_input_json = ""
                    elif block.type == "text" and getattr(
                        block,
                        "text",
                        "",
                    ):
                        received_content = True
                        # Some OpenAI-compatible backends emit the
                        # full text
                        # on content_block_start instead of as deltas.
                        yield LLMChunk(delta_content=block.text)
                elif event.type == "content_block_delta":
                    delta = event.delta
                    # Anthropic SDK uses "text_delta"; some
                    # proxied OpenAI-compatible backends emit
                    # "text" or put text directly on the delta.
                    # Accept any object that carries text.
                    if getattr(delta, "type", "") == "text_delta":
                        received_content = True
                        yield LLMChunk(delta_content=delta.text)
                    elif getattr(delta, "type", "") == "text":
                        received_content = True
                        yield LLMChunk(
                            delta_content=getattr(delta, "text", ""),
                        )
                    elif hasattr(delta, "text") and delta.text:
                        received_content = True
                        yield LLMChunk(delta_content=delta.text)
                    elif getattr(delta, "type", "") == "input_json_delta":
                        tool_input_json += delta.partial_json
                elif event.type == "content_block_stop":
                    if current_tool:
                        received_content = True
                        try:
                            args = (
                                json.loads(tool_input_json)
                                if tool_input_json
                                else {}
                            )
                        except json.JSONDecodeError as e:
                            # LLM produced malformed / truncated JSON.
                            # Surface it as an empty-args tool call so
                            # the agent loop can report the error
                            # instead of crashing.
                            args = {}
                            yield LLMChunk(
                                delta_content=(
                                    f"[Failed to parse tool args: {e}]"
                                ),
                            )
                        # pylint: disable=unsubscriptable-object
                        yield LLMChunk(
                            tool_calls=[
                                ToolCall(
                                    id=current_tool["id"],
                                    name=current_tool["name"],
                                    arguments=args,
                                ),
                            ],
                        )
                        # pylint: enable=unsubscriptable-object
                        current_tool = None
                        tool_input_json = ""
                elif event.type == "message_start":
                    usage = getattr(
                        getattr(event, "message", None),
                        "usage",
                        None,
                    )
                    if usage is not None:
                        stream_usage["input_tokens"] = (
                            getattr(usage, "input_tokens", 0) or 0
                        )
                        stream_usage["cached_tokens"] = (
                            getattr(usage, "cache_read_input_tokens", 0)
                            or 0
                        )
                elif event.type == "message_delta":
                    usage = getattr(event, "usage", None)
                    if usage is not None:
                        stream_usage["output_tokens"] = (
                            getattr(usage, "output_tokens", 0) or 0
                        )
                elif event.type == "message_stop":
                    yield LLMChunk(
                        finish_reason="end_turn",
                        usage={
                            **stream_usage,
                            "total_tokens": (
                                stream_usage["input_tokens"]
                                + stream_usage["output_tokens"]
                            ),
                        },
                    )

            # Detect silent failures: API returned 200 but no content.
            # Some backends (e.g. on rate-limit) send error in body
            # without raising, producing zero stream events.
            if not received_content:
                stop = None
                try:
                    final = await stream.get_final_message()
                    stop = getattr(final, "stop_reason", None)
                except Exception:
                    pass
                if stop and stop != "end_turn":
                    raise RuntimeError(
                        f"API stream ended abnormally: stop_reason={stop}",
                    )
                raise RuntimeError(
                    "API stream returned no content; possibly rate "
                    "limit, model unavailable, or service disruption",
                )
    except httpx.TimeoutException as e:
        raise RuntimeError(
            "API request timeout; check your network or retry later",
        ) from e
    except httpx.ConnectError as e:
        raise RuntimeError(
            "Unable to connect to the API server; check your network",
        ) from e
    except anthropic.NotFoundError as e:
        raise RuntimeError(
            "API endpoint not found (404): base_url and protocol may "
            "not match; run /provider to check the config",
        ) from e
    except anthropic.APIError as e:
        raise RuntimeError(f"API request failed: {e}") from e

档案与路由

ProviderProfile dataclass

ProviderProfile(
    name: str,
    provider: str,
    model: str,
    api_key: str,
    base_url: str | None = None,
    timeout: float = 120.0,
    protocol: str = "openai",
    max_retries: int = 3,
    module: str = "app",
)

Everything needed to talk to one model endpoint.

name instance-attribute

name: str

provider instance-attribute

provider: str

model instance-attribute

model: str

api_key instance-attribute

api_key: str

base_url class-attribute instance-attribute

base_url: str | None = None

timeout class-attribute instance-attribute

timeout: float = 120.0

protocol class-attribute instance-attribute

protocol: str = 'openai'

max_retries class-attribute instance-attribute

max_retries: int = 3

module class-attribute instance-attribute

module: str = 'app'

ProviderChain

ProviderChain(profiles: list[ProviderProfile])

Bases: LLMProvider

Ordered list of ProviderProfiles; routes to the next on retryable failure.

Source code in src/dashscope_agenticx/providers/profile.py
309
310
311
def __init__(self, profiles: list[ProviderProfile]):
    self.profiles = profiles
    self._instances: dict[int, LLMProvider] = {}

profiles instance-attribute

profiles = profiles

aclose async

aclose() -> None
Source code in src/dashscope_agenticx/providers/profile.py
313
314
315
316
317
318
319
320
321
322
323
324
325
326
async def aclose(self) -> None:
    import asyncio

    from dashscope_agenticx.providers.base import close_provider

    instances = list(self._instances.values())
    self._instances.clear()
    results = await asyncio.gather(
        *(close_provider(provider) for provider in instances),
        return_exceptions=True,
    )
    for result in results:
        if isinstance(result, BaseException):
            raise result

chat async

chat(
    messages: list[dict],
    tools: list[dict] | None = None,
    response_format: dict | None = None,
) -> LLMResponse
Source code in src/dashscope_agenticx/providers/profile.py
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
async def chat(
    self,
    messages: list[dict],
    tools: list[dict] | None = None,
    response_format: dict | None = None,
) -> LLMResponse:
    # Exactly ONE retry layer: HardenedProvider (see _get_instance) owns
    # per-profile retries; the chain only falls to the next profile when
    # the attempt fails with a retryable error. Non-retryable errors
    # (auth, 404, ...) stop the chain immediately.
    last_error: BaseException | None = None
    for i in range(len(self.profiles)):
        try:
            provider = self._get_instance(i)
            return await provider.chat(
                messages,
                tools,
                response_format=response_format,
            )
        except Exception as e:
            last_error = e
            if not is_retryable_error(e):
                break
            self._emit_fallback(i, e)
            continue
    raise last_error or RuntimeError("All providers failed")

chat_stream async

chat_stream(
    messages: list[dict],
    tools: list[dict] | None = None,
    response_format: dict | None = None,
) -> AsyncIterator[LLMChunk]
Source code in src/dashscope_agenticx/providers/profile.py
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
async def chat_stream(  # pylint: disable=invalid-overridden-method
    self,
    messages: list[dict],
    tools: list[dict] | None = None,
    response_format: dict | None = None,
) -> AsyncIterator[LLMChunk]:
    # Same single-retry-layer contract as chat(); HardenedProvider only
    # retries BEFORE the first chunk, but it still propagates errors that
    # occur mid-stream. So the chain may only fall to the next profile
    # when nothing was emitted yet — otherwise output would duplicate.
    last_error: BaseException | None = None
    for i in range(len(self.profiles)):
        emitted_anything = False
        try:
            provider = self._get_instance(i)
            async for chunk in provider.chat_stream(
                messages,
                tools,
                response_format=response_format,
            ):
                emitted_anything = True
                yield chunk
            return
        except Exception as e:
            last_error = e
            if emitted_anything or not is_retryable_error(e):
                break
            self._emit_fallback(i, e)
            continue
    raise last_error or RuntimeError("All providers failed")

build_profiles_from_config

build_profiles_from_config(config) -> list[ProviderProfile]

Build primary and fallback profiles from AgenticX config.

Source code in src/dashscope_agenticx/providers/profile.py
176
177
178
179
180
181
182
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
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
def build_profiles_from_config(config) -> list[ProviderProfile]:
    """Build primary and fallback profiles from AgenticX config."""
    profiles: list[ProviderProfile] = []

    def _profile_for(
        provider_name: str,
        model: str | None = None,
    ) -> ProviderProfile | None:
        api_key_attr = f"{provider_name}_api_key"
        api_key = getattr(config, api_key_attr, "") or ""

        # Resolve base_url: config.base_url only makes sense for the primary
        # provider; fallbacks use their well-known endpoints unless overridden.
        base_url = (
            config.base_url if provider_name == config.provider else None
        )

        # New MaaS gateway: workspace/region/maas_api_key reroute tongyi
        # traffic to the workspace gateway with its own key. An explicit
        # config.base_url still wins.
        if provider_name == "tongyi" and not base_url:
            maas = maas_gateway(config)
            if maas:
                base_url, api_key = maas

        timeout = float(getattr(config, "timeout", 120))
        # config.protocol describes the PRIMARY provider only; fallback
        # profiles must use their own extension-toml protocol (resolved
        # below) or the default, never inherit the primary's.
        if provider_name == config.provider:
            protocol = getattr(config, "protocol", "openai")
        else:
            protocol = ""

        # Consult the extension catalog (user custom-extensions.toml
        # at ~/.agenticx/ or ./.agenticx/) to fill base_url / protocol /
        # api_key
        # when Config doesn't. Config field wins for api_key and protocol;
        # toml provides base_url + protocol fallbacks.
        try:
            from dashscope_agenticx.extensions import find_provider

            ext = find_provider(provider_name)
            if ext is not None:
                if not api_key:
                    api_key = ext.resolve_api_key(config) or ""
                if not base_url:
                    base_url = ext.base_url
                if not protocol:
                    protocol = ext.resolved_protocol()
        except Exception:
            pass

        if not protocol:
            protocol = "openai"

        if not base_url:
            base_url = DEFAULT_BASE_URLS.get(provider_name, "")

        return ProviderProfile(
            name=provider_name,
            provider=provider_name,
            model=model or _default_model_for(provider_name, config),
            api_key=api_key,
            base_url=base_url or None,
            timeout=timeout,
            protocol=protocol,
            module=getattr(config, "_embedded_module", "") or "app",
        )

    # Primary profile.
    primary = _profile_for(config.provider, config.model)
    if primary:
        profiles.append(primary)

    # Fallback profiles.
    fallback_names = getattr(config, "fallback_providers", []) or []
    if not fallback_names:
        # If no explicit fallback list, try a sensible default based on
        # env keys.
        fallback_names = _infer_fallback_names(config)

    seen = {config.provider}
    for name in fallback_names:
        if name in seen:
            continue
        seen.add(name)
        prof = _profile_for(name)
        if not prof:
            continue
        # Skip only if the provider genuinely requires a key but has none.
        # Keyless providers (ollama, local proxies with auth=False) must not
        # be excluded here — they have an empty api_key by design.
        needs_key = (
            _API_KEY_ENVS.get(name) is not None
        )  # None sentinel = no key required
        if needs_key and not prof.api_key:
            continue
        profiles.append(prof)

    return profiles

validate_key_for_profile

validate_key_for_profile(
    profile: ProviderProfile,
) -> list[str]

Return warnings if the API key looks mismatched for the endpoint.

Source code in src/dashscope_agenticx/providers/profile.py
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
171
172
173
def validate_key_for_profile(profile: ProviderProfile) -> list[str]:
    """Return warnings if the API key looks mismatched for the endpoint."""
    warnings: list[str] = []
    key = profile.api_key or ""
    base_url = profile.base_url or ""

    if not key:
        warnings.append(f"{profile.name}: API key is empty")
        return warnings

    # Detect endpoint type from host.
    detected = _detect_provider_from_host(base_url)
    if detected and detected != profile.provider:
        warnings.append(
            f"{profile.name}: provider='{profile.provider}' but base_url "
            f"'{base_url}' looks like '{detected}'",
        )

    # Check key prefix when the provider has a known convention.
    prefixes = _KEY_PREFIXES.get(profile.provider, ("",))
    if prefixes and prefixes != ("",):
        if not any(key.startswith(p) for p in prefixes):
            warnings.append(
                f"{profile.name}: API key does not start with expected "
                f"prefix {prefixes} for provider '{profile.provider}'",
            )

    return warnings

maas_gateway

maas_gateway(config) -> tuple[str, str] | None

Return (base_url, api_key) for the new MaaS gateway.

None when workspace/region/maas_api_key are not all configured, in which case the caller falls back to the legacy gateway.

Source code in src/dashscope_agenticx/providers/profile.py
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
def maas_gateway(config) -> tuple[str, str] | None:
    """Return (base_url, api_key) for the new MaaS gateway.

    None when workspace/region/maas_api_key are not all configured, in
    which case the caller falls back to the legacy gateway.
    """
    workspace = (getattr(config, "workspace", "") or "").strip()
    region = (getattr(config, "region", "") or "").strip()
    api_key = (getattr(config, "maas_api_key", "") or "").strip()
    if not (workspace and region and api_key):
        return None
    return (
        MAAS_GATEWAY_TEMPLATE.format(workspace=workspace, region=region),
        api_key,
    )

warn_legacy_gateway

warn_legacy_gateway(config) -> None

One-time deprecation notice for the legacy DashScope gateway.

Suppress with AGENTICX_DISABLE_GATEWAY_WARNING=1.

Source code in src/dashscope_agenticx/providers/profile.py
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
def warn_legacy_gateway(config) -> None:
    """One-time deprecation notice for the legacy DashScope gateway.

    Suppress with AGENTICX_DISABLE_GATEWAY_WARNING=1.
    """
    import os

    if os.environ.get("AGENTICX_DISABLE_GATEWAY_WARNING") == "1":
        return
    if not uses_legacy_gateway(config):
        return
    signature = "legacy-gateway"
    if signature in _LEGACY_GATEWAY_WARNED:
        return
    _LEGACY_GATEWAY_WARNED.add(signature)
    from rich.console import Console

    Console().print(
        "[yellow]⚠ The legacy DashScope gateway (dashscope.aliyuncs.com) is "
        "being phased out. Configure workspace, region and maas_api_key to "
        "route requests through the new MaaS gateway "
        "https://{workspace}.{region}.maas.aliyuncs.com. Set "
        "AGENTICX_DISABLE_GATEWAY_WARNING=1 to silence this warning.[/yellow]",
    )

加固(Hardening)

HardenedProvider

HardenedProvider(
    provider: LLMProvider,
    max_retries: int = 3,
    retry_delay: float = 4.0,
    max_backoff: float = 16.0,
)

Wraps an LLMProvider with retries and empty-response recovery.

Source code in src/dashscope_agenticx/providers/hardening.py
202
203
204
205
206
207
208
209
210
211
212
def __init__(
    self,
    provider: LLMProvider,
    max_retries: int = 3,
    retry_delay: float = 4.0,
    max_backoff: float = 16.0,
):
    self.provider = provider
    self.max_retries = max_retries
    self.retry_delay = retry_delay
    self.max_backoff = max_backoff

provider instance-attribute

provider = provider

max_retries instance-attribute

max_retries = max_retries

retry_delay instance-attribute

retry_delay = retry_delay

max_backoff instance-attribute

max_backoff = max_backoff

aclose async

aclose() -> None
Source code in src/dashscope_agenticx/providers/hardening.py
214
215
216
217
async def aclose(self) -> None:
    from dashscope_agenticx.providers.base import close_provider

    await close_provider(self.provider)

chat async

chat(
    messages: list[dict],
    tools: list[dict] | None = None,
    response_format: dict | None = None,
) -> LLMResponse
Source code in src/dashscope_agenticx/providers/hardening.py
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
async def chat(
    self,
    messages: list[dict],
    tools: list[dict] | None = None,
    response_format: dict | None = None,
) -> LLMResponse:
    last_error: BaseException | None = None
    attempt_messages = messages
    started = time.monotonic()

    for attempt in range(self.max_retries + 1):
        try:
            resp = await self.provider.chat(
                attempt_messages,
                tools,
                response_format=response_format,
            )
        except Exception as e:
            last_error = e
            retryable = is_retryable_error(e)
            if retryable and attempt < self.max_retries:
                await asyncio.sleep(self._backoff(attempt))
                continue
            if retryable:
                raise RetriesExhausted(
                    e,
                    time.monotonic() - started,
                ) from e
            raise

        if _is_empty_response(resp):
            if attempt < self.max_retries:
                # Retry once with a recovery hint appended.
                attempt_messages = list(messages) + [_EMPTY_RECOVERY_HINT]
                await asyncio.sleep(self._backoff(attempt))
                continue
        return resp

    raise last_error or RuntimeError("Provider call failed")

chat_stream async

chat_stream(
    messages: list[dict],
    tools: list[dict] | None = None,
    response_format: dict | None = None,
) -> AsyncIterator[LLMChunk]
Source code in src/dashscope_agenticx/providers/hardening.py
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
async def chat_stream(
    self,
    messages: list[dict],
    tools: list[dict] | None = None,
    response_format: dict | None = None,
) -> AsyncIterator[LLMChunk]:
    attempt_messages = messages
    started = time.monotonic()

    for attempt in range(self.max_retries + 1):
        emitted_anything = False
        try:
            async for chunk in self.provider.chat_stream(
                attempt_messages,
                tools,
                response_format=response_format,
            ):
                emitted_anything = True
                yield chunk
            # Stream ended normally.
            if not emitted_anything and attempt < self.max_retries:
                # No chunks at all; treat like empty response.
                attempt_messages = list(messages) + [_EMPTY_RECOVERY_HINT]
                await asyncio.sleep(self._backoff(attempt))
                continue
            return
        except Exception as e:
            # First-chunk rule: after any chunk was yielded, retrying
            # would re-emit content — propagate the error instead. Such an
            # error also stays plain rather than RetriesExhausted: this
            # layer never spent a budget on it, so an upper layer deciding
            # to re-attempt is not duplicating work.
            retryable = not emitted_anything and is_retryable_error(e)
            if retryable and attempt < self.max_retries:
                # Retry with same messages for transient failures.
                attempt_messages = messages
                await asyncio.sleep(self._backoff(attempt))
                continue
            if retryable:
                raise RetriesExhausted(
                    e,
                    time.monotonic() - started,
                ) from e
            raise

RetriesExhausted

RetriesExhausted(
    error: BaseException, elapsed_sec: float = 0.0
)

Bases: RuntimeError

This layer already spent its whole retry budget on the wrapped error.

Keeps the original message so is_retryable_error still answers True and ProviderChain keeps falling back to the next profile — the budget that is exhausted is this layer's, not the chain's. What the type adds is a signal for layers above the provider stack: re-attempting there pays max_retries x request_timeout a second time, which against a stalled endpoint measured 819s of silent wall clock from a 60s configured timeout.

The type alone is not enough of a signal, though. A budget spent on a stalled endpoint costs max_retries x request_timeout (268s measured); the same budget spent on a refused connection costs only the ~28s of backoff, and there an upper layer re-attempting is cheap and is what rides out a transient blip. elapsed_sec lets the caller tell the two apart instead of paying for the expensive case's protection in the cheap case too.

Source code in src/dashscope_agenticx/providers/hardening.py
180
181
182
183
184
185
186
187
def __init__(
    self,
    error: BaseException,
    elapsed_sec: float = 0.0,
) -> None:
    super().__init__(str(error))
    self.error = error
    self.elapsed_sec = elapsed_sec

SLOW_BUDGET_SEC class-attribute instance-attribute

SLOW_BUDGET_SEC = 60.0

error instance-attribute

error = error

elapsed_sec instance-attribute

elapsed_sec = elapsed_sec

exhausted_slowly property

exhausted_slowly: bool

True when the budget went into slow attempts, not fast failures.

is_retryable_error

is_retryable_error(error: BaseException) -> bool

Classify an exception as retryable/fallback-worthy (bilingual).

Shared by HardenedProvider (retry) and ProviderChain (fallback) so both layers agree. Non-retryable patterns win over retryable ones.

Source code in src/dashscope_agenticx/providers/hardening.py
143
144
145
146
147
148
149
150
151
152
def is_retryable_error(error: BaseException) -> bool:
    """Classify an exception as retryable/fallback-worthy (bilingual).

    Shared by HardenedProvider (retry) and ProviderChain (fallback) so
    both layers agree. Non-retryable patterns win over retryable ones.
    """
    text = str(error).lower()
    if any(p in text for p in _NON_RETRYABLE_PATTERNS):
        return False
    return any(p in text for p in _RETRYABLE_PATTERNS)

account_error_hint

account_error_hint(error: BaseException) -> str

Actionable hint for account/billing failures, else an empty string.

Source code in src/dashscope_agenticx/providers/hardening.py
120
121
122
123
124
125
126
127
128
129
def account_error_hint(error: BaseException) -> str:
    """Actionable hint for account/billing failures, else an empty string."""
    text = str(error).lower()
    if any(p in text for p in _ACCOUNT_ERROR_PATTERNS):
        return (
            "This is an account/billing error (overdue payment or service "
            "not activated); retrying will not help until the account is "
            "in good standing."
        )
    return ""

协议适配器

anthropic_to_openai_request

anthropic_to_openai_request(
    messages: list[dict],
    system: str | None = None,
    tools: list[dict] | None = None,
    **kwargs
) -> dict

Convert Anthropic Messages API request to OpenAI Chat Completions format.

Anthropic format: { "system": "...", "messages": [{"role": "user", "content": "..."}], "tools": [{"name": "foo", "input_schema": {...}}] }

OpenAI format: { "messages": [ {"role": "system", "content": "..."}, {"role": "user", "content": "..."} ], "tools": [{"type": "function", "function": {"name": "foo", "parameters": {...}}}] }

Tool structures round-trip: assistant tool_use blocks (or the agent's internal tool_calls key) become OpenAI tool_calls, and tool_result blocks (or internal role: "tool" messages) become OpenAI tool messages correlated by tool_call_id.

Source code in src/dashscope_agenticx/providers/adapter.py
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 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
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
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
171
172
173
174
175
176
177
178
179
180
181
182
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
def anthropic_to_openai_request(
    messages: list[dict],
    system: str | None = None,
    tools: list[dict] | None = None,
    **kwargs,
) -> dict:
    """
    Convert Anthropic Messages API request to OpenAI Chat Completions format.

    Anthropic format:
    {
      "system": "...",
      "messages": [{"role": "user", "content": "..."}],
      "tools": [{"name": "foo", "input_schema": {...}}]
    }

    OpenAI format:
    {
      "messages": [
        {"role": "system", "content": "..."},
        {"role": "user", "content": "..."}
      ],
      "tools": [{"type": "function", "function": {"name": "foo",
      "parameters": {...}}}]
    }

    Tool structures round-trip: assistant tool_use blocks (or the agent's
    internal ``tool_calls`` key) become OpenAI tool_calls, and tool_result
    blocks (or internal ``role: "tool"`` messages) become OpenAI tool
    messages correlated by tool_call_id.
    """
    openai_messages: list[dict[str, Any]] = []

    # Add system message if present
    if system:
        openai_messages.append({"role": "system", "content": system})

    # Convert messages
    for msg in messages:
        role = msg.get("role", "user")
        content = msg.get("content", "")

        # Internal tool-result message → OpenAI tool message. The
        # tool_call_id correlation is mandatory for OpenAI-compatible
        # backends; without it the request is rejected.
        if role == "tool":
            openai_messages.append(
                {
                    "role": "tool",
                    "content": content,
                    "tool_call_id": (
                        msg.get("tool_call_id") or msg.get("tool_use_id", "")
                    ),
                },
            )
            continue

        # Assistant message carrying internal OpenAI-style tool_calls:
        # keep them so later tool messages can be correlated.
        if role == "assistant" and msg.get("tool_calls"):
            openai_messages.append(
                {
                    "role": "assistant",
                    "content": content or None,
                    "tool_calls": [
                        _normalize_tool_call(tc) for tc in msg["tool_calls"]
                    ],
                },
            )
            continue

        # Handle content blocks. Preserve media blocks (image_url, input_audio)
        # that are already in OpenAI format; flatten text blocks; convert
        # tool_use / tool_result blocks to OpenAI tool structures.
        if isinstance(content, list):
            new_blocks = []
            text_buffer: list[str] = []
            has_media = False
            tool_calls = []
            tool_results = []

            def _flush_text(text_buffer=text_buffer, new_blocks=new_blocks):
                # pylint: disable=dangerous-default-value
                if text_buffer:
                    new_blocks.append(
                        {"type": "text", "text": "\n".join(text_buffer)},
                    )
                    text_buffer.clear()

            for block in content:
                if not isinstance(block, dict):
                    continue
                btype = block.get("type")
                if btype == "text":
                    text_buffer.append(block.get("text", ""))
                elif btype in ("image_url", "input_audio"):
                    _flush_text()
                    new_blocks.append(block)
                    has_media = True
                elif btype == "tool_use":
                    args = block.get("input", {})
                    if not isinstance(args, str):
                        args = json.dumps(args, ensure_ascii=False)
                    tool_calls.append(
                        {
                            "id": block.get("id", ""),
                            "type": "function",
                            "function": {
                                "name": block.get("name", ""),
                                "arguments": args,
                            },
                        },
                    )
                elif btype == "tool_result":
                    tool_results.append(block)
            _flush_text()

            # Anthropic tool_result blocks become standalone OpenAI tool
            # messages; they must directly follow the assistant message
            # that carried the matching tool_calls.
            for tr in tool_results:
                openai_messages.append(
                    {
                        "role": "tool",
                        "content": _tool_result_text(tr.get("content", "")),
                        "tool_call_id": tr.get("tool_use_id", ""),
                    },
                )

            content = (
                new_blocks
                if has_media
                else "\n".join(
                    b.get("text", "")
                    for b in new_blocks
                    if b.get("type") == "text"
                )
            )
            if tool_results and not content:
                # Message carried only tool results — already emitted above.
                continue
            out = {"role": role, "content": content}
            if tool_calls:
                out["tool_calls"] = tool_calls
            openai_messages.append(out)
            continue

        openai_messages.append({"role": role, "content": content})

    # Convert tools
    openai_tools = None
    if tools:
        openai_tools = []
        for tool in tools:
            # Anthropic: {"name": "foo", "description": "...",
            # "input_schema": {...}}
            # OpenAI: {"type": "function", "function": {"name": "foo",
            # "description": "...", "parameters": {...}}}
            openai_tool = {
                "type": "function",
                "function": {
                    "name": tool.get("name", ""),
                    "description": tool.get("description", ""),
                    "parameters": tool.get("input_schema", {}),
                },
            }
            openai_tools.append(openai_tool)

    return {"messages": openai_messages, "tools": openai_tools, **kwargs}

openai_to_anthropic_response

openai_to_anthropic_response(openai_response: dict) -> dict

Convert OpenAI Chat Completions response to Anthropic Messages API format.

OpenAI format: { "choices": [{ "message": { "content": "...", "tool_calls": [{"id": "...", "function": {"name": "...", "arguments": "..."}}] }, "finish_reason": "stop" }], "usage": {"prompt_tokens": 10, "completion_tokens": 20, "total_tokens": 30} }

Anthropic format: { "id": "msg_...", "type": "message", "role": "assistant", "content": [ {"type": "text", "text": "..."}, {"type": "tool_use", "id": "...", "name": "...", "input": {...}} ], "stop_reason": "end_turn", "usage": {"input_tokens": 10, "output_tokens": 20} }

Source code in src/dashscope_agenticx/providers/adapter.py
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
def openai_to_anthropic_response(openai_response: dict) -> dict:
    """
    Convert OpenAI Chat Completions response to Anthropic Messages API format.

    OpenAI format:
    {
      "choices": [{
        "message": {
          "content": "...",
          "tool_calls": [{"id": "...", "function": {"name": "...",
          "arguments": "..."}}]
        },
        "finish_reason": "stop"
      }],
      "usage": {"prompt_tokens": 10, "completion_tokens": 20,
      "total_tokens": 30}
    }

    Anthropic format:
    {
      "id": "msg_...",
      "type": "message",
      "role": "assistant",
      "content": [
        {"type": "text", "text": "..."},
        {"type": "tool_use", "id": "...", "name": "...", "input": {...}}
      ],
      "stop_reason": "end_turn",
      "usage": {"input_tokens": 10, "output_tokens": 20}
    }
    """
    choice = openai_response.get("choices", [{}])[0]
    message = choice.get("message", {})

    content_blocks = []

    # Convert text content
    text_content = message.get("content", "")
    if text_content:
        content_blocks.append({"type": "text", "text": text_content})

    # Convert tool calls
    tool_calls = message.get("tool_calls", [])
    for call in tool_calls:
        func = call.get("function", {})
        args_str = func.get("arguments", "{}")
        try:
            args = (
                json.loads(args_str) if isinstance(args_str, str) else args_str
            )
        except json.JSONDecodeError:
            args = {}

        content_blocks.append(
            {
                "type": "tool_use",
                "id": call.get("id", ""),
                "name": func.get("name", ""),
                "input": args,
            },
        )

    # Convert finish reason
    finish_reason = choice.get("finish_reason", "stop")
    stop_reason_map = {
        "stop": "end_turn",
        "tool_calls": "tool_use",
        "length": "max_tokens",
    }
    stop_reason = stop_reason_map.get(finish_reason, "end_turn")

    # Convert usage
    usage = openai_response.get("usage", {})
    anthropic_usage = {
        "input_tokens": usage.get("prompt_tokens", 0),
        "output_tokens": usage.get("completion_tokens", 0),
    }

    return {
        "id": openai_response.get("id", "msg_0"),
        "type": "message",
        "role": "assistant",
        "content": content_blocks,
        "stop_reason": stop_reason,
        "usage": anthropic_usage,
    }

anthropic_to_openai_response

anthropic_to_openai_response(
    anthropic_response: dict,
) -> dict

Convert an Anthropic Messages API response back to an OpenAI-style message dict: {"content": str, "tool_calls": [...]}.

Reverse of openai_to_anthropic_response's message part — tool_use blocks become tool_calls entries with JSON-string arguments.

Source code in src/dashscope_agenticx/providers/adapter.py
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
def anthropic_to_openai_response(anthropic_response: dict) -> dict:
    """
    Convert an Anthropic Messages API response back to an OpenAI-style
    message dict: {"content": str, "tool_calls": [...]}.

    Reverse of openai_to_anthropic_response's message part — tool_use
    blocks become tool_calls entries with JSON-string arguments.
    """
    content = ""
    tool_calls = []
    for block in anthropic_response.get("content", []):
        if block.get("type") == "text":
            content += block.get("text", "")
        elif block.get("type") == "tool_use":
            tool_calls.append(
                {
                    "id": block.get("id", ""),
                    "type": "function",
                    "function": {
                        "name": block.get("name", ""),
                        "arguments": json.dumps(
                            block.get("input", {}),
                            ensure_ascii=False,
                        ),
                    },
                },
            )
    return {"content": content, "tool_calls": tool_calls}