Model Access & Compatibility

Heicode can connect to different model providers, but "the interface is callable" does not mean "all Agent capabilities are available." Development tasks usually also depend on tool calling, structured output, long context, stable streaming responses, and controllable timeouts.

Pre-Integration Checks

When configuring a model, confirm at least:

• The API Base URL matches the interface protocol;
• The API key is valid and has sufficient permissions;
• The model name and deployment name are correct;
• The max context and max output length meet the task's needs;
• Tool Calling or structured output is supported;
• The timeout, retry, and concurrency limits are known;
• Whether the current provider returns content, reasoning_content, or other extension fields.

Capability Matrix

We recommend recording the following for each model:

Thinking Mode & Structured Output

Once thinking mode is enabled, some models put large amounts of content into reasoning_content, while the final content is empty, too short, or contains no valid JSON. In that case, you should not parse the reasoning text directly as a structured result.

For execution calls that need Function Calling, a JSON Schema, or full file output, we recommend:

• Using the provider's officially recommended structured-output configuration;
• Turning off thinking mode where necessary;
• Explicitly requiring the final result to go into content;
• Strictly validating the final JSON;
• Keeping the raw response when parsing fails — but not mistaking reasoning prose for a valid result.

For the Qwen series in structured-output scenarios, pay particular attention to the enable_thinking setting. If the execution chain depends on strict JSON, you can configure the execution call as:

extra_body={"enable_thinking": False}

Whether this parameter is supported, and its exact behavior, depends on your current model provider and deployment version.

OpenAI-Compatible Is Not Fully Compatible

Even when different providers use an OpenAI-compatible interface, they may still differ in:

• Tool-call fields;
• Streaming event format;
• The reasoning_content extension field;
• The degree of JSON Schema support;
• System-message restrictions;
• Token accounting;
• Error codes and retry headers;
• The model deployment name versus the real model name.

For that reason, run a minimal compatibility test against each provider rather than verifying just one chat request.

Recommended Minimum Test

1. Plain Q&A returns final content;
2. A single Tool Calling call has valid arguments;
3. It can keep answering after the tool result is returned;
4. Strict JSON output is parseable;
5. Long input does not silently truncate key instructions;
6. Timeout and throttling errors are identifiable;
7. It doesn't keep failing under multi-Agent concurrency.

Failure Handling

When a model request fails, distinguish between:

• Authentication failure;
• Model or deployment not found;
• Throttling;
• Context overflow;
• Invalid tool call;
• Structured-output parsing failure;
• Only reasoning content returned;
• Network or gateway timeout.

Different causes call for different retry and fallback strategies — you can't apply the same unlimited retry to all of them.