epam · olegmikhnovich · Aug 3, 2026
@@ -0,0 +1,60 @@
+# Agentic Tools
+
+## Introduction
+
+Agentic coding tools — command-line agents and IDE assistants — run their turns against a model backend. This section shows how to point that backend at DIAL, so a DIAL-hosted model answers through the tool while DIAL applies its roles, quotas, and cost tracking.
+
+Each tutorial is self-contained and ends the same way: a model replying to you *through DIAL*, so you can see the connection working. Follow the one for the tool you use.
+
+> Refer to [DIAL as Agentic Platform](/docs/platform/0.architecture-and-concepts/4.agentic-platform.md) to learn how DIAL itself hosts and serves agents, as opposed to being used as a backend for one.
+
+- [Connect Codex to DIAL](/docs/tutorials/1.developers/2.agentic-tools/1.codex.md) — the command-line agent that speaks the OpenAI Responses API, direct or through a translating proxy
+- [Connect GitHub Copilot to DIAL](/docs/tutorials/1.developers/2.agentic-tools/2.github-copilot.md) — add your DIAL deployments to the Copilot model picker in VS Code
+- [Connect Open Claw to DIAL](/docs/tutorials/1.developers/2.agentic-tools/3.open-claw.md) — register DIAL as a model provider in the self-hosted agent gateway
+- [Connect OpenCode to DIAL](/docs/tutorials/1.developers/2.agentic-tools/4.opencode.md) — add DIAL as a custom provider in the terminal coding agent
+- [Connect Claude Code to DIAL](/docs/tutorials/1.developers/2.agentic-tools/5.claude-code.md) — point Anthropic's command-line agent at DIAL's native Anthropic Messages API
+
+## Prerequisites
+
+Every tutorial needs two things:
+
+- The URL of your DIAL host, written throughout as `<YOUR_DIAL_HOST>`.
+- A DIAL API key, written throughout as `<DIAL_API_KEY>`.
+
+Each tutorial lists any extra tools it needs at the top. Replace `<YOUR_DIAL_HOST>` with your real host and `<DIAL_API_KEY>` with your real key everywhere they appear.
+
+## Before you begin
+
+### Check your DIAL version
+
+Some behavior depends on your DIAL release. The native Responses API — which lets Codex reach DIAL without a proxy — is only available from DIAL **v0.45** onwards, and how deployments handle request settings can vary by release. Ask the host for its version (no key needed):
+
+```bash
+curl -s https://<YOUR_DIAL_HOST>/version
+```
+
+On Windows, use `curl.exe`, or `Invoke-RestMethod` if curl is unavailable:
+
+```powershell
+curl.exe -s https://<YOUR_DIAL_HOST>/version
+Invoke-RestMethod https://<YOUR_DIAL_HOST>/version
+```
+
+It prints a bare version string such as `0.45`. Below v0.45, no deployment serves the Responses API, so Codex must use the proxy path regardless of any `responses_api` flag.
+
+### Azure-backed deployment settings
+
+Azure OpenAI–backed deployments (for example, GPT-5.x) need two extra request settings. If a call fails with one of these errors, apply the matching fix wherever the tutorial sets the DIAL URL or the output-token limit:
+
+- `api-version is a required query parameter` — append `?api-version=2025-04-01-preview` to the DIAL URL the tool calls (the chat-completions or `/responses` URL).
+- `Unsupported parameter: 'max_tokens' … use 'max_completion_tokens'` — Azure-backed GPT-5.x reject the plain `max_tokens` field for any value. Switch the tool to its `max_completion_tokens` equivalent, or send no output cap at all, since uncapped requests are accepted.
+
+An output cap is never required. You only think about it when a tool sends one: GPT-5.x care about the field **name** above, while other deployments accept `max_tokens` but reject a **value** above that deployment's completion-token ceiling (`max_tokens is too large`). Not every deployment needs an `api-version` either, so leave both settings out unless you hit the matching error.
+
+**Note**: Do not trust a deployment's `max_tokens_supported` flag here — GPT-5.x report it `true` yet still reject `max_tokens`.
+
+## Additional Information
+
+Start with [Connect Codex to DIAL](/docs/tutorials/1.developers/2.agentic-tools/1.codex.md) — it is the most involved case, and shows both the direct and proxy paths.
+
+> Refer to the [Unified API reference](https://dialx.ai/dial_api) for the API every tool in this section calls.
@@ -0,0 +1,215 @@
+# Connect Codex to DIAL
+
+## Introduction
+
+From this tutorial, you will learn how to point Codex, the command-line coding agent, at DIAL and watch a DIAL-hosted model reply. Codex speaks only the OpenAI Responses API, so how it reaches DIAL depends on your deployment: one that exposes the Responses API natively connects directly, while a Chat-Completions-only deployment needs a small translating proxy. Step 1 shows which case you are in. By the end, `codex exec` sends a prompt and prints the model's reply, routed through your DIAL deployment with DIAL's roles, quotas, and cost tracking applied.
+
+## Prerequisites
+
+- A DIAL host and API key. Refer to [Prerequisites](/docs/tutorials/1.developers/2.agentic-tools/0.overview.md#prerequisites).
+- [Codex](https://github.com/openai/codex) installed.
+- For the proxy path only: [Docker](https://docs.docker.com/get-docker/) and [git](https://git-scm.com/downloads).
+
+## Step 1: Find out which path your deployment needs
+
+Ask DIAL for the deployment's metadata and read the `responses_api` flag:
+
+```bash
+curl -s -H "Api-Key: <DIAL_API_KEY>" \
+  "https://<YOUR_DIAL_HOST>/openai/deployments/gpt-5.4-2026-03-05" \
+  | grep -o '"responses_api":[^,]*'
+```
+
+On Windows (PowerShell), call `curl.exe` — PowerShell's `curl` is an `Invoke-WebRequest` alias — and pipe to `findstr`:
+
+```powershell
+curl.exe -s -H "Api-Key: <DIAL_API_KEY>" `
+  "https://<YOUR_DIAL_HOST>/openai/deployments/gpt-5.4-2026-03-05" | findstr responses_api
+```
+
+If curl is unavailable, `Invoke-RestMethod` reads the flag directly and prints `True` or `False`:
+
+```powershell
+(Invoke-RestMethod -Headers @{ "Api-Key" = "<DIAL_API_KEY>" } `
+  "https://<YOUR_DIAL_HOST>/openai/deployments/gpt-5.4-2026-03-05").features.responses_api
+```
+
+- `"responses_api":true` — follow [The direct path](#the-direct-path) and ignore the proxy.
+- `"responses_api":false` — your deployment is chat-only; follow [The proxy path](#the-proxy-path).
+
+**Note**: The `responses_api` flag only means anything on DIAL v0.45+ (refer to [Check your DIAL version](/docs/tutorials/1.developers/2.agentic-tools/0.overview.md#check-your-dial-version)); on older DIAL every deployment is chat-only, so take the proxy path. Even on v0.45+, many deployments are still chat-only, so check the flag rather than assume. You can also test it functionally: a `POST` to `https://<YOUR_DIAL_HOST>/openai/v1/responses` returns `200` on a Responses-capable deployment and `503` on a chat-only one.
+
+## The direct path
+
+Follow this path when Step 1 reported `responses_api: true`.
+
+### Step 2: Tell Codex about DIAL
+
+Open `~/.codex/config.toml` (on Windows, `%USERPROFILE%\.codex\config.toml`; create it if it does not exist) and paste the following. The `model_provider` and `model_providers` keys only take effect in this user-level file.
+
+```toml
+model = "gpt-5.4-2026-03-05"      # the DIAL deployment id; Codex sends it to DIAL as the model
+model_provider = "dial"
+disable_response_storage = true   # DIAL doesn't store responses, so this must be on
+
+[model_providers.dial]
+name = "DIAL (direct)"
+base_url = "https://<YOUR_DIAL_HOST>/openai/v1"     # Codex appends /responses
+wire_api = "responses"            # the only valid value — Codex's old "chat" wire was removed
+env_key = "DIAL_API_KEY"
+env_http_headers = { "Api-Key" = "DIAL_API_KEY" }   # DIAL authenticates on Api-Key
+requires_openai_auth = false                         # don't enforce the sk- prefix check
+query_params = { api-version = "2025-04-01-preview" }  # Azure-backed deployments require this
+```
+
+**Note**: Put the `api-version` in `query_params`, not in `base_url`. Codex appends `/responses` to `base_url`, so a query string there lands in the wrong place. Drop the `query_params` line if your DIAL host does not require an Azure API version — refer to [Azure-backed deployment settings](/docs/tutorials/1.developers/2.agentic-tools/0.overview.md#azure-backed-deployment-settings).
+
+### Step 3: Set your API key
+
+Bash or Zsh:
+
+```bash
+export DIAL_API_KEY="<DIAL_API_KEY>"
+```
+
+PowerShell:
+
+```powershell
+$env:DIAL_API_KEY = "<DIAL_API_KEY>"
+```
+
+### Step 4: Check the wiring
+
+```bash
+codex doctor
+```
+
+Your config loads cleanly and a row appears for the `dial` provider — `config.toml parse ok`, `auth ✓` with `provider auth env var DIAL_API_KEY (present)`, and `wire API responses`. The model line names your deployment, for example `gpt-5.4-2026-03-05 · dial`.
+
+### Step 5: Run Codex
+
+```bash
+codex exec "Reply with exactly: PONG"
+```
+
+You see `PONG` printed back, routed Codex → DIAL with no proxy in between. Run plain `codex` for the interactive session you will use day to day.
+
+The direct path is complete. Skip to [Additional Information](#additional-information).
+
+## The proxy path
+
+Follow this path when Step 1 reported `responses_api: false`. Put a small translating proxy between Codex and DIAL. The proxy ([responses-proxy](https://github.com/chutesai/responses-proxy)) converts Codex's Responses calls into the Chat Completions calls DIAL understands and forwards your `Api-Key` header to DIAL.
+
+### Step 2: Build and run the proxy
+
+There is no published image, so build it from the repo — a one-time Rust build:
+
+```bash
+git clone https://github.com/chutesai/responses-proxy && cd responses-proxy
+```
+
+**Warning**: Do not use the project's `install_codex.sh` one-liner for DIAL. It installs chutes' own fork of Codex and points it at their hosted proxy (`responses.chutes.ai`, whose backend is chutes — not DIAL), and the config it writes omits both `disable_response_storage` and the `Api-Key` header DIAL needs. Build and run the proxy yourself, as below.
+
+Point the proxy's `BACKEND_URL` at your DIAL chat deployment — the deployment id lives in the URL. If your DIAL's Chat Completions endpoint requires an Azure API version, append `?api-version=2025-04-01-preview` to `BACKEND_URL` (refer to [Azure-backed deployment settings](/docs/tutorials/1.developers/2.agentic-tools/0.overview.md#azure-backed-deployment-settings)). Start it either way:
+
+```bash
+# Option A — Docker Compose (the maintainers' path). --build compiles the image;
+# naming the service skips the bundled Caddy/TLS sidecar you don't need locally.
+BACKEND_URL="https://<YOUR_DIAL_HOST>/openai/deployments/gpt-5.4-2026-03-05/chat/completions" \
+  docker compose up --build openai-responses-proxy
+```
+
+```bash
+# Option B — plain Docker (build once, then run).
+docker build -t responses-proxy .
+docker run -d --name responses-proxy -p 8282:8282 \
+  -e BACKEND_URL="https://<YOUR_DIAL_HOST>/openai/deployments/gpt-5.4-2026-03-05/chat/completions" \
+  responses-proxy
+```
+
+On Windows (PowerShell), the inline `VAR=… command` form and the `\` line-continuation do not work. Set the variable with `$env:` first and use a backtick to continue lines:
+
+```powershell
+$env:BACKEND_URL = "https://<YOUR_DIAL_HOST>/openai/deployments/gpt-5.4-2026-03-05/chat/completions"
+docker compose up --build openai-responses-proxy          # Option A
+# or, after `docker build -t responses-proxy .` :
+docker run -d --name responses-proxy -p 8282:8282 `
+  -e BACKEND_URL="$env:BACKEND_URL" responses-proxy        # Option B
+```
+
+The proxy now listens on `http://0.0.0.0:8282`. Confirm it is up:
+
+```bash
+curl -s -o /dev/null -w "%{http_code}\n" http://0.0.0.0:8282/health
+```
+
+On Windows, use `curl.exe`, or `Invoke-WebRequest` if curl is unavailable:
+
+```powershell
+curl.exe -s -o NUL -w "%{http_code}`n" http://0.0.0.0:8282/health
+(Invoke-WebRequest -UseBasicParsing http://0.0.0.0:8282/health).StatusCode
+```
+
+You should see `200`.
+
+### Step 3: Tell Codex about the proxy
+
+Open `~/.codex/config.toml` (on Windows, `%USERPROFILE%\.codex\config.toml`; create it if it does not exist) and paste the following. The `model_provider` and `model_providers` keys only take effect in this user-level file.
+
+```toml
+model = "gpt-5.4"                 # the DIAL deployment id you set in BACKEND_URL above
+model_provider = "dial"
+disable_response_storage = true   # DIAL doesn't store responses, so this must be on
+
+[model_providers.dial]
+name = "DIAL (via responses-proxy)"
+base_url = "http://0.0.0.0:8282/v1"   # the proxy; Codex appends /responses
+wire_api = "responses"            # the only valid value — Codex's old "chat" wire was removed
+env_key = "DIAL_API_KEY"
+env_http_headers = { "Api-Key" = "DIAL_API_KEY" }   # forwarded through the proxy to DIAL
+requires_openai_auth = false                         # don't enforce the sk- prefix check
+```
+
+### Step 4: Set your API key
+
+Bash or Zsh:
+
+```bash
+export DIAL_API_KEY="<DIAL_API_KEY>"
+```
+
+PowerShell:
+
+```powershell
+$env:DIAL_API_KEY = "<DIAL_API_KEY>"
+```
+
+### Step 5: Check the wiring
+
+Before running a real prompt, ask Codex to inspect its own setup:
+
+```bash
+codex doctor
+```
+
+Your config loads cleanly and a row appears for the `dial` provider — `config.toml parse ok`, `auth ✓` with `provider auth env var DIAL_API_KEY (present)`, and `wire API responses`. The model line names your deployment, for example `gpt-5.4 · dial`.
+
+### Step 6: Run Codex
+
+```bash
+codex exec "Reply with exactly: PONG"
+```
+
+You see `PONG` printed back, routed Codex → proxy → DIAL. Run plain `codex` for the interactive session you will use day to day.
+
+## Additional Information
+
+DIAL does not store responses or support `previous_response_id`, which is why `disable_response_storage = true` is required on both paths — without it, Codex breaks after the first turn.
+
+- Which path you need depends on the deployment. Re-run the Step 1 check for any new deployment — the flag can differ even between versions of the same model family.
+- Codex sends the key as an `Authorization: Bearer` token; the `env_http_headers` line is what makes it also send the `Api-Key` header that DIAL authenticates on. On the proxy path, the proxy forwards it.
+- On the proxy path, mind the proxy's own limits: only `function` tools are forwarded, file inputs must be inlined, and no session state is kept.
+
+> - Refer to [Connect Claude Code to DIAL](/docs/tutorials/1.developers/2.agentic-tools/5.claude-code.md) for another command-line agent, with no proxy needed.
+> - Refer to the [Agentic Tools overview](/docs/tutorials/1.developers/2.agentic-tools/0.overview.md) for shared prerequisites and the other tools.
+> - Refer to the [Unified API reference](https://dialx.ai/dial_api) for the API DIAL exposes.
@@ -0,0 +1,55 @@
+# Connect GitHub Copilot to DIAL
+
+## Introduction
+
+From this tutorial, you will learn how to add your DIAL deployments to the GitHub Copilot model picker in VS Code, then chat with one of them. Turns you send through the picker run on DIAL, with DIAL auth, roles, quotas, and cost tracking applied. By the end, you pick a DIAL model in Copilot Chat and get a reply streamed back from your DIAL deployment.
+
+## Prerequisites
+
+- A DIAL host and API key. Refer to [Prerequisites](/docs/tutorials/1.developers/2.agentic-tools/0.overview.md#prerequisites).
+- VS Code **1.110** or newer.
+- The GitHub Copilot extension, installed and signed in.
+
+**Note**: The DIAL Chat Model Provider used below is a community extension, not published by GitHub, Microsoft, or EPAM. Review its source and install it at your own discretion.
+
+## Step 1: Install the DIAL extension
+
+Download the **DIAL Chat Model Provider** `.vsix` from either source:
+
+- [Open VSX](https://open-vsx.org/extension/sergey-zinchenko/dial-chat-model-provider)
+- [GitHub releases](https://github.com/sergey-zinchenko/DialChatModelProvider/releases)
+
+In VS Code, open the Command Palette (`Ctrl+Shift+P` / `Cmd+Shift+P`), run **`Extensions: Install from VSIX…`**, and select the file you downloaded. When prompted, reload VS Code. **DIAL Chat Model Provider** now appears in the Extensions view, and new `DIAL:` commands are available in the Command Palette.
+
+## Step 2: Point at DIAL and sign in
+
+Open the Command Palette and run **`DIAL: Open Settings`**. Set:
+
+| Setting           | Value               |
+| ----------------- | ------------------- |
+| `dial.serverUrl`  | `https://<YOUR_DIAL_HOST>` |
+| `dial.authMethod` | `openid` or `apikey` |
+
+Then run **`DIAL: Login`**:
+
+- `openid` — VS Code opens your browser, you sign in, and the tokens are stored in your OS keychain.
+- `apikey` — run **`DIAL: Set API Key`** first, or paste the key when prompted. The key is sent as DIAL's `Api-Key` header on every request.
+
+## Step 3: Pick a DIAL model in Copilot
+
+Open Copilot Chat, open the model picker, and choose a deployment listed under **DIAL**. The deployments your DIAL role can access appear automatically, and vision-capable models are marked.
+
+Send a message — for example, *"What model are you?"* You get a reply streamed back from your DIAL deployment.
+
+## Additional Information
+
+- Only turns that go through the model picker (and other `vscode.lm.*` clients) reach DIAL. Inline ghost-text completions keep using GitHub's backend.
+- The extension uses DIAL's Chat Completions surface. Deployments exposed only over the Responses API are not reachable this way.
+- A deployment works correctly through the extension only when its DIAL model configuration explicitly declares token limits and a tokenizer. Deployments missing either may fail or misbehave in the picker.
+- Copilot's prompt-cache markers (`cache_control`) are not forwarded to DIAL, so Bedrock-style prompt caching is not activated from Copilot turns.
+- Auto-compaction does not work with this setup. When a conversation grows past the model's context window, Copilot will not summarize it down automatically — start a new chat instead.
+- For `openid`, your DIAL admins must allow the extension's OIDC client registration and its redirect URI `http://127.0.0.1:47821/oauth-callback`.
+
+> - Refer to [Connect OpenCode to DIAL](/docs/tutorials/1.developers/2.agentic-tools/4.opencode.md) for a terminal agent that also uses Chat Completions.
+> - Refer to the [Agentic Tools overview](/docs/tutorials/1.developers/2.agentic-tools/0.overview.md) for shared prerequisites and the other tools.
+> - Refer to [DIAL Chat Model Provider on Open VSX](https://open-vsx.org/extension/sergey-zinchenko/dial-chat-model-provider) for the extension's current feature list and settings reference.