diff --git a/README.md b/README.md index 23b9eff..2922939 100644 --- a/README.md +++ b/README.md @@ -203,6 +203,7 @@ $env:AZURE_TOKEN_CREDENTIALS = "AzureDeveloperCliCredential" python src/hello_claude.py # one-shot Messages call (Entra ID) python src/chat_stream.py # interactive streaming chat — type a message, `exit` to quit python src/hello_claude_token_refresh.py # long-running variant with per-request token refresh +python src/message_threads.py # two-turn Message Threads beta ```
@@ -239,7 +240,7 @@ The standard client does not consume `ANTHROPIC_FOUNDRY_RESOURCE`. The explicit A captured static token eventually expires. [src/hello_claude_token_refresh.py](./src/hello_claude_token_refresh.py) uses a cached bearer-token callback instead. The standard SDK's request hook asks for the current token on every request and retry; Azure Identity caches and renews it. There is no custom token cache, retry loop, SDK subclass, or automatic native OAuth beta header. -[requirements.txt](./requirements.txt) targets Anthropic SDK **2.1+** and Azure Identity **1.26+**, with upper bounds at the next major version. SDK 2.x uses `httpx2` for custom transports; it is not interchangeable with `httpx`. +[requirements.txt](./requirements.txt) targets Anthropic SDK **2.4+** and Azure Identity **1.26+**, with upper bounds at the next major version. SDK 2.x uses `httpx2` for custom transports; it is not interchangeable with `httpx`.
@@ -249,7 +250,7 @@ A captured static token eventually expires. [src/hello_claude_token_refresh.py]( | Language | Sample and instructions | |---|---| -| Python | [One-shot](./src/hello_claude.py), [streaming](./src/chat_stream.py), [token refresh](./src/hello_claude_token_refresh.py) | +| Python | [One-shot](./src/hello_claude.py), [streaming](./src/chat_stream.py), [token refresh](./src/hello_claude_token_refresh.py), [threads](./src/message_threads.py) | | TypeScript | [samples/typescript](./samples/typescript/README.md) | | C# | [samples/dotnet](./samples/dotnet/README.md) | | Go | [samples/go](./samples/go/README.md) | @@ -259,6 +260,8 @@ A captured static token eventually expires. [src/hello_claude_token_refresh.py]( Helpers return ordinary SDK clients; application code still calls the usual Messages and streaming APIs. [Shared configuration](./samples/README.md) selects the endpoint, model, authentication, key header and API version. The same samples can target Anthropic's native endpoint without changing imports or inference code. +Separate [Message Threads examples](./samples/message-threads.md) opt into `anthropic-beta: message-threads-2026-08-12`. The guide includes SDK requirements and live Foundry compatibility checks. + Python, TypeScript, C#, Go and Java use their official Azure Identity SDKs. PHP and Ruby accept a token-provider callback and use Azure CLI as a documented local fallback; this is **not** an official Azure Identity SDK for those languages. Claude Code's built-in Foundry mode below is independent of these SDK samples and remains unchanged. @@ -547,6 +550,7 @@ claude/ │ ├── hello_claude_apikey.py # Same, but with an API key (dev/test only) │ ├── hello_claude_token_refresh.py # Long-running variant with auto-refreshing Entra token │ ├── chat_stream.py # Streaming multi-turn chat loop +│ ├── message_threads.py # Two-turn Message Threads beta │ └── check_claude_quota.py # Inspect Claude quota + capacity via ARM (see Advanced) ├── Get-ClaudeCatalog.ps1 ├── requirements.txt diff --git a/requirements.txt b/requirements.txt index bcceb34..b1dbdc7 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,4 +1,4 @@ -anthropic>=2.1.0,<3 +anthropic>=2.4.0,<3 azure-identity>=1.26.0,<2 azure-core>=1.41.0,<2 python-dotenv>=1.2.4,<2 diff --git a/samples/README.md b/samples/README.md index 29fa806..c3796aa 100644 --- a/samples/README.md +++ b/samples/README.md @@ -14,6 +14,10 @@ Each language uses its standard Anthropic SDK client. Generic client/authenticat PHP/Ruby's CLI fallback is explicit because no current official Azure Identity SDK was identified for those languages. It is not a production managed-identity implementation. Supply an appropriate renewable-token callback in hosted applications. +## Message Threads + +The separate [Threads examples](message-threads.md) send only the new turn after creating a conversation. They opt into `anthropic-beta: message-threads-2026-08-12`; the existing Messages and streaming examples do not. See the guide for run commands, SDK requirements and Foundry API findings. + ## Configuration Python loads the gitignored root `.env.local`; the other entrypoints read process environment variables. Export the selected `azd` environment before running them. Never put real keys, tokens, tenant IDs or subscription IDs in checked-in configuration. @@ -77,7 +81,7 @@ Cloud provisioning remains the existing `azd up` workflow in one selected IaC va The migration was live-tested against a freshly provisioned Haiku 5.5 version 2 deployment in `eastus2`: all seven languages passed Messages, SSE streaming and resource-key authentication with native SDK defaults. Python, TypeScript, C#, Go and Java also passed a configuration-only switch between Azure CLI and Azure Developer CLI credentials. Native Anthropic endpoint routing is covered by offline recording transports; no native-account live test is claimed. -The TypeScript sample is pinned to the tested SDK 1.1.0 because the configured package feed did not provide 1.3.0 and direct public-registry access failed TLS negotiation in the test environment. Relevant 1.3.0 source was compared, but that package version was not executed. Other runtime/version details are in the language READMEs. +TypeScript now pins SDK 1.4.0 for Threads; its Messages, streaming and Threads paths also passed live bearer runs. Other runtime/version details are in the language READMEs. ## Upstream requests diff --git a/samples/dotnet/README.md b/samples/dotnet/README.md index 19d3f5b..69619a8 100644 --- a/samples/dotnet/README.md +++ b/samples/dotnet/README.md @@ -11,6 +11,7 @@ There is no `Anthropic.Foundry` package, client subclass, alternate Messages API | `src/AnthropicStandardSdk/ClientFactory.cs` | Generic helper. Builds the standard client with one explicit credential. Knows no identity library and reads no environment. Copy this one file (it needs only the `Anthropic` package). | | `src/AnthropicStandardSdk/CredentialSelector.cs` | The only code that uses Azure Identity: selects one credential class and adapts it to the helper's `TokenProvider` callback. | | `src/AnthropicStandardSdk/SampleSettings.cs`, `SampleRunner.cs`, `Program.cs` | Environment parsing, the Messages/streaming calls, output and exit codes. | +| `src/AnthropicStandardSdk/ThreadsExample.cs` | The `--threads` message-thread example. Same settings, factory and credentials; no extra project. | | `tests/AnthropicStandardSdk.Tests` | Offline tests: the real SDK against recording transports and loopback servers. | ## Run @@ -38,6 +39,17 @@ or usage error. Each call uses `max_tokens` 1024 and a 120 second per-call timeo policy, set explicitly in `SampleRunner`; `ClientFactory` keeps the SDK's timeout unless the caller sets `Timeout`. The SDK's default retries and cancellation behavior are unchanged. +## Message threads + +`--threads` runs the separate example in `ThreadsExample.cs` with the same configuration and client: + +```powershell +dotnet run --project samples/dotnet/src/AnthropicStandardSdk -- --threads +``` + +It prints the second reply and fails if there is no text. It takes no prompt and cannot be combined with `--stream`. +The SDK helper adds `anthropic-beta: message-threads-2026-08-12` and handles replay. See the [Threads guide](../message-threads.md). + ## Configuration Read by the sample entrypoint only (never by `ClientFactory`). Real keys and IDs belong in the environment or a @@ -124,4 +136,4 @@ dotnet test samples/dotnet/AnthropicStandardSdk.sln not the retries. - `AzureCliCredential` and `AzureDeveloperCliCredential` need their CLI on `PATH`; use `ManagedIdentityCredential` in hosted environments. -- Only the Messages and streaming calls are demonstrated. Other SDK APIs go through the same client and handler. \ No newline at end of file +- Only the Messages, streaming and message-thread calls are demonstrated. Other SDK APIs go through the same client and handler. \ No newline at end of file diff --git a/samples/dotnet/src/AnthropicStandardSdk/SampleRunner.cs b/samples/dotnet/src/AnthropicStandardSdk/SampleRunner.cs index e9f49b7..424d7c9 100644 --- a/samples/dotnet/src/AnthropicStandardSdk/SampleRunner.cs +++ b/samples/dotnet/src/AnthropicStandardSdk/SampleRunner.cs @@ -34,13 +34,14 @@ internal static class SampleRunner internal static readonly TimeSpan RequestTimeout = TimeSpan.FromSeconds(120); private const string DefaultPrompt = "Say hello in one short sentence."; - private const string UsageText = "usage: AnthropicStandardSdk [--stream] [prompt...]"; + private const string UsageText = "usage: AnthropicStandardSdk [--stream] [prompt...] | --threads"; private static readonly Regex Whitespace = new Regex(@"\s+", RegexOptions.Compiled); /// - /// Runs one Messages call (or one streaming call with --stream). Environment access, - /// credential creation and the HTTP transport are parameters so tests can supply recording fakes. + /// Runs one Messages call, one streaming call with --stream, or the message-thread example with + /// --threads. Environment access, credential creation and the HTTP transport are parameters so + /// tests can supply recording fakes. /// public static async Task RunAsync( string[] args, @@ -52,6 +53,7 @@ public static async Task RunAsync( Func? credentialFactory = null) { bool stream = false; + bool threads = false; bool optionsEnded = false; List promptWords = new List(); foreach (string arg in args) @@ -64,6 +66,10 @@ public static async Task RunAsync( { stream = true; } + else if (!optionsEnded && arg == "--threads") + { + threads = true; + } else if (!optionsEnded && (arg == "-h" || arg == "--help")) { output.WriteLine(UsageText); @@ -81,6 +87,13 @@ public static async Task RunAsync( } } + if (threads && (stream || promptWords.Count > 0)) + { + error.WriteLine("error: --threads takes no prompt and cannot be combined with --stream"); + error.WriteLine(UsageText); + return ExitUsage; + } + string prompt = promptWords.Count > 0 ? string.Join(" ", promptWords) : DefaultPrompt; SampleSettings settings; @@ -139,6 +152,12 @@ public static async Task RunAsync( using (client) { + if (threads) + { + await ThreadsExample.RunAsync(client, settings.Model, output, cancellationToken).ConfigureAwait(false); + return ExitOk; + } + MessageCreateParams parameters = new MessageCreateParams { Model = settings.Model, diff --git a/samples/dotnet/src/AnthropicStandardSdk/ThreadsExample.cs b/samples/dotnet/src/AnthropicStandardSdk/ThreadsExample.cs new file mode 100644 index 0000000..59e9092 --- /dev/null +++ b/samples/dotnet/src/AnthropicStandardSdk/ThreadsExample.cs @@ -0,0 +1,60 @@ +using System.Collections.Generic; +using System.IO; +using System.Text; +using System.Threading; +using System.Threading.Tasks; +using Anthropic; +using Anthropic.Helpers.Beta; +using Anthropic.Models.Beta.Messages; + +namespace AnthropicStandardSdk; + +/// Message threads (beta), run with --threads: the second turn sends only its new message. +internal static class ThreadsExample +{ + private const string FirstPrompt = "Remember the code ORCHID-47. Reply with OK."; + private const string SecondPrompt = "What code did I ask you to remember? Reply with only the code."; + private const string SystemPrompt = "Keep replies short."; + private const long MaxTokens = 1024; + + public static async Task RunAsync( + AnthropicClient client, string model, TextWriter output, CancellationToken cancellationToken) + { + BetaMessageThread thread = client.Beta.Messages.Thread(new ThreadCreateParams + { + Model = model, + MaxTokens = MaxTokens, + System = SystemPrompt, + Messages = [], + }); + + await thread.Send(new BetaUserMessageParam { Content = FirstPrompt }, cancellationToken).ConfigureAwait(false); + BetaMessage second = await thread + .Send(new BetaUserMessageParam { Content = SecondPrompt }, cancellationToken) + .ConfigureAwait(false); + + output.WriteLine(TextOf(second)); + } + + private static string TextOf(BetaMessage message) + { + StringBuilder text = new StringBuilder(); + List blockKinds = new List(); + foreach (BetaContentBlock block in message.Content) + { + blockKinds.Add(block.Value?.GetType().Name ?? "unknown"); + if (block.TryPickText(out BetaTextBlock? textBlock)) + { + text.Append(textBlock.Text); + } + } + + if (string.IsNullOrWhiteSpace(text.ToString())) + { + throw new UnusableResponseException( + "The response contained no text (content blocks: " + string.Join(", ", blockKinds) + ")."); + } + + return text.ToString(); + } +} diff --git a/samples/dotnet/tests/AnthropicStandardSdk.Tests/SampleRunnerTests.Threads.cs b/samples/dotnet/tests/AnthropicStandardSdk.Tests/SampleRunnerTests.Threads.cs new file mode 100644 index 0000000..c7067c4 --- /dev/null +++ b/samples/dotnet/tests/AnthropicStandardSdk.Tests/SampleRunnerTests.Threads.cs @@ -0,0 +1,212 @@ +using System; +using System.Collections.Generic; +using System.Linq; +using System.Net; +using System.Net.Http; +using System.Text.Json; +using System.Threading.Tasks; +using Xunit; + +namespace AnthropicStandardSdk.Tests; + +/// The --threads example: the real SDK thread helper against a recording transport. +public sealed partial class SampleRunnerTests +{ + private const string ThreadsBeta = "message-threads-2026-08-12"; + private const string RememberPrompt = "Remember the code ORCHID-47. Reply with OK."; + private const string RecallPrompt = "What code did I ask you to remember? Reply with only the code."; + + private static string ThreadType(RecordedRequest request) => + request.BodyJson().TryGetProperty("thread", out JsonElement thread) ? thread.GetProperty("type").GetString()! : "none"; + + /// The request messages as "role: text", whether the SDK sent a string or text blocks. + private static string[] Messages(RecordedRequest request) => + request.BodyJson().GetProperty("messages").EnumerateArray() + .Select((JsonElement message) => + message.GetProperty("role").GetString() + ": " + MessageText(message.GetProperty("content"))) + .ToArray(); + + private static string MessageText(JsonElement content) => + content.ValueKind == JsonValueKind.String + ? content.GetString()! + : string.Concat(content.EnumerateArray().Select((JsonElement block) => block.GetProperty("text").GetString())); + + [Fact] + public async Task Threads_CreateThenContinue_SendsOnlyTheNewMessage_WithTheBetaOnBothCalls() + { + RecordingTransport transport = new RecordingTransport(); + transport.Enqueue(Responses.Message("OK", id: "msg_first")); + transport.Enqueue(Responses.Message("ORCHID-47", id: "msg_second")); + + RunResult result = await Run(["--threads"], BearerEnv, transport, new FakeCredential()); + + Assert.Equal(0, result.ExitCode); + Assert.Equal("ORCHID-47\n", result.Output); + Assert.Equal(string.Empty, result.Error); + IReadOnlyList requests = transport.Requests; + Assert.Equal(2, requests.Count); + foreach (RecordedRequest request in requests) + { + JsonElement body = request.BodyJson(); + Assert.Equal(HttpMethod.Post, request.Method); + Assert.Equal("/anthropic/v1/messages", request.Url.AbsolutePath); + Assert.Equal(ThreadsBeta, request.Header("anthropic-beta")); + Assert.StartsWith("Bearer fake-credential-token-", request.Header("Authorization"), StringComparison.Ordinal); + Assert.False(request.Has("x-api-key")); + Assert.Equal("claude-sonnet-5-5", body.GetProperty("model").GetString()); + Assert.Equal(1024, body.GetProperty("max_tokens").GetInt32()); + AmbientEnvironment.AssertNoCanaryEgress(request); + } + + JsonElement create = requests[0].BodyJson(); + Assert.Equal("create", ThreadType(requests[0])); + Assert.False(create.GetProperty("thread").TryGetProperty("previous_message_id", out JsonElement _)); + Assert.Equal("Keep replies short.", create.GetProperty("system").GetString()); + Assert.Equal(new string[] { "user: " + RememberPrompt }, Messages(requests[0])); + + JsonElement continued = requests[1].BodyJson(); + Assert.Equal("continue", ThreadType(requests[1])); + Assert.Equal("msg_first", continued.GetProperty("thread").GetProperty("previous_message_id").GetString()); + Assert.Equal(new string[] { "user: " + RecallPrompt }, Messages(requests[1])); + Assert.False(continued.TryGetProperty("system", out JsonElement _)); + Assert.False(continued.TryGetProperty("tools", out JsonElement _)); + Assert.DoesNotContain("ORCHID-47", requests[1].Body, StringComparison.Ordinal); + } + + [Fact] + public async Task Threads_ThreadNotFound_ReplaysTheWholeConversationOnce() + { + RecordingTransport transport = new RecordingTransport(); + transport.Enqueue(Responses.Message("OK", id: "msg_first")); + transport.Enqueue(Responses.Error(HttpStatusCode.NotFound, "not_found_error", "thread expired", "thread_not_found")); + transport.Enqueue(Responses.Message("ORCHID-47", id: "msg_replay")); + + RunResult result = await Run(["--threads"], BearerEnv, transport, new FakeCredential()); + + Assert.Equal(0, result.ExitCode); + Assert.Equal("ORCHID-47\n", result.Output); + IReadOnlyList requests = transport.Requests; + Assert.Equal(new string[] { "create", "continue", "create" }, requests.Select(ThreadType).ToArray()); + Assert.All(requests, (RecordedRequest request) => Assert.Equal(ThreadsBeta, request.Header("anthropic-beta"))); + JsonElement replay = requests[2].BodyJson(); + Assert.Equal("Keep replies short.", replay.GetProperty("system").GetString()); + Assert.Equal( + new string[] { "user: " + RememberPrompt, "assistant: OK", "user: " + RecallPrompt }, Messages(requests[2])); + Assert.False(replay.GetProperty("thread").TryGetProperty("previous_message_id", out JsonElement _)); + } + + [Theory] + [InlineData(null)] + [InlineData("model_not_found")] + public async Task Threads_Other404_IsNotReplayed_AndFailsWithTheSanitizedError(string? errorCode) + { + RecordingTransport transport = new RecordingTransport(); + transport.Enqueue(Responses.Message("OK", id: "msg_first")); + transport.Enqueue(Responses.Error( + HttpStatusCode.NotFound, "not_found_error", "no such model for fake-credential-token-2", errorCode)); + + RunResult result = await Run(["--threads"], BearerEnv, transport, new FakeCredential()); + + Assert.Equal(SampleRunner.ExitFailure, result.ExitCode); + Assert.Equal(string.Empty, result.Output); + Assert.Contains("AnthropicNotFoundException (HTTP 404)", result.Error, StringComparison.Ordinal); + Assert.Contains("[redacted]", result.Error, StringComparison.Ordinal); + Assert.DoesNotContain("fake-credential-token", result.Error, StringComparison.Ordinal); + Assert.Equal(new string[] { "create", "continue" }, transport.Requests.Select(ThreadType).ToArray()); + } + + [Fact] + public async Task Threads_UnsupportedRequest_FailsWithoutAnUnthreadedFallback() + { + RecordingTransport transport = new RecordingTransport(); + transport.Enqueue(Responses.Message("OK", id: "msg_first")); + transport.Enqueue(Responses.Error( + HttpStatusCode.BadRequest, "invalid_request_error", "too many cache breakpoints", "thread_unsupported_request")); + + RunResult result = await Run(["--threads"], BearerEnv, transport, new FakeCredential()); + + Assert.Equal(SampleRunner.ExitFailure, result.ExitCode); + Assert.Equal(string.Empty, result.Output); + Assert.Contains("AnthropicBadRequestException (HTTP 400)", result.Error, StringComparison.Ordinal); + Assert.Equal(new string[] { "create", "continue" }, transport.Requests.Select(ThreadType).ToArray()); + } + + [Theory] + [InlineData("")] + [InlineData(" \n ")] + public async Task Threads_BlankSecondReply_IsAFailure(string text) + { + RecordingTransport transport = new RecordingTransport(); + transport.Enqueue(Responses.Message("OK", id: "msg_first")); + transport.Enqueue(Responses.Message(text, id: "msg_second")); + + RunResult result = await Run(["--threads"], BearerEnv, transport, new FakeCredential()); + + Assert.Equal(SampleRunner.ExitFailure, result.ExitCode); + Assert.Equal(string.Empty, result.Output); + Assert.Contains("UnusableResponseException", result.Error, StringComparison.Ordinal); + Assert.Equal(2, transport.Requests.Count); + } + + [Fact] + public async Task Threads_ThinkingOnlySecondReply_IsAFailure() + { + RecordingTransport transport = new RecordingTransport(); + transport.Enqueue(Responses.Message("OK", id: "msg_first")); + transport.Enqueue(Responses.ThinkingOnly()); + + RunResult result = await Run(["--threads"], BearerEnv, transport, new FakeCredential()); + + Assert.Equal(SampleRunner.ExitFailure, result.ExitCode); + Assert.Equal(string.Empty, result.Output); + Assert.Contains("UnusableResponseException", result.Error, StringComparison.Ordinal); + Assert.Contains("ThinkingBlock", result.Error, StringComparison.Ordinal); + } + + [Theory] + [InlineData("--threads", "--stream")] + [InlineData("--threads", "some prompt")] + public async Task Threads_TakesNoPromptAndNoStreamFlag(string first, string second) + { + RecordingTransport transport = new RecordingTransport(); + FakeCredential credential = new FakeCredential(); + + RunResult result = await Run([first, second], BearerEnv, transport, credential); + + Assert.Equal(SampleRunner.ExitUsage, result.ExitCode); + Assert.Equal(string.Empty, result.Output); + Assert.Contains("--threads", result.Error, StringComparison.Ordinal); + Assert.Empty(transport.Requests); + Assert.False(credential.Disposed, "no credential may be created for a usage error"); + } + + [Fact] + public async Task Help_ListsTheThreadsOption() + { + RunResult help = await Run(["--help"], string.Empty, new RecordingTransport()); + + Assert.Equal(SampleRunner.ExitOk, help.ExitCode); + Assert.Contains("--threads", help.Output, StringComparison.Ordinal); + } + + [Theory] + [InlineData(false)] + [InlineData(true)] + public async Task WithoutThreads_NoBetaHeaderOrThreadFieldIsSent(bool stream) + { + RecordingTransport transport = new RecordingTransport(); + if (stream) + { + transport.Enqueue(Responses.Stream("hi")); + } + + string[] args = stream ? new string[] { "--stream" } : Array.Empty(); + RunResult result = await Run(args, BearerEnv, transport, new FakeCredential()); + + Assert.Equal(0, result.ExitCode); + RecordedRequest request = transport.Single; + Assert.False(request.Has("anthropic-beta")); + Assert.Equal(string.Empty, request.Url.Query); + Assert.False(request.BodyJson().TryGetProperty("thread", out JsonElement _)); + } +} diff --git a/samples/dotnet/tests/AnthropicStandardSdk.Tests/SampleRunnerTests.cs b/samples/dotnet/tests/AnthropicStandardSdk.Tests/SampleRunnerTests.cs index 5a19660..f0fb6cb 100644 --- a/samples/dotnet/tests/AnthropicStandardSdk.Tests/SampleRunnerTests.cs +++ b/samples/dotnet/tests/AnthropicStandardSdk.Tests/SampleRunnerTests.cs @@ -12,7 +12,7 @@ namespace AnthropicStandardSdk.Tests; /// The sample entrypoint end to end: environment, credential wiring, real SDK, output, exit codes. -public sealed class SampleRunnerTests +public sealed partial class SampleRunnerTests { private const string Foundry = TestClients.FoundryUrl; diff --git a/samples/dotnet/tests/AnthropicStandardSdk.Tests/TestSupport.cs b/samples/dotnet/tests/AnthropicStandardSdk.Tests/TestSupport.cs index 99548cd..b8c4dc5 100644 --- a/samples/dotnet/tests/AnthropicStandardSdk.Tests/TestSupport.cs +++ b/samples/dotnet/tests/AnthropicStandardSdk.Tests/TestSupport.cs @@ -187,8 +187,9 @@ protected override async Task SendAsync( internal static class Responses { - public static HttpResponseMessage Message(string text = "OK", long inputTokens = 11, long outputTokens = 5) => - Json(HttpStatusCode.OK, MessageJson(JsonSerializer.Serialize(text), inputTokens, outputTokens)); + public static HttpResponseMessage Message( + string text = "OK", long inputTokens = 11, long outputTokens = 5, string id = "msg_test") => + Json(HttpStatusCode.OK, MessageJson(JsonSerializer.Serialize(text), inputTokens, outputTokens, id)); public static HttpResponseMessage ThinkingOnly() => Json(HttpStatusCode.OK, """ @@ -197,8 +198,11 @@ public static HttpResponseMessage ThinkingOnly() => "stop_reason":"max_tokens","stop_sequence":null,"usage":{"input_tokens":11,"output_tokens":1024}} """); - public static HttpResponseMessage Error(HttpStatusCode status, string type, string message) => - Json(status, $$$"""{"type":"error","error":{"type":"{{{type}}}","message":"{{{message}}}"}}"""); + /// An API error; becomes error.details.error_code. + public static HttpResponseMessage Error(HttpStatusCode status, string type, string message, string? errorCode = null) => + Json(status, errorCode is null + ? $$$"""{"type":"error","error":{"type":"{{{type}}}","message":"{{{message}}}"}}""" + : $$$"""{"type":"error","error":{"details":{"error_code":"{{{errorCode}}}"},"type":"{{{type}}}","message":"{{{message}}}"}}"""); public static HttpResponseMessage Redirect(HttpStatusCode status, string location) { @@ -240,9 +244,9 @@ private static HttpResponseMessage BuildStream(bool includeStop, string[] textDe }; } - public static string MessageJson(string textLiteral, long inputTokens, long outputTokens) => + public static string MessageJson(string textLiteral, long inputTokens, long outputTokens, string id = "msg_test") => $$$""" - {"id":"msg_test","type":"message","role":"assistant","model":"test-model", + {"id":"{{{id}}}","type":"message","role":"assistant","model":"test-model", "content":[{"type":"text","text":{{{textLiteral}}}}], "stop_reason":"end_turn","stop_sequence":null, "usage":{"input_tokens":{{{inputTokens}}},"output_tokens":{{{outputTokens}}}}} diff --git a/samples/go/README.md b/samples/go/README.md index 8b24bbe..6f3246f 100644 --- a/samples/go/README.md +++ b/samples/go/README.md @@ -12,6 +12,7 @@ documented by the SDK. | `credential.go` | Selects one Azure Identity credential and turns it into a token provider. | | `settings.go`, `sample_client.go` | Read the environment and build the client for the sample. | | `main.go` | Command-line entrypoint. | +| `message_threads.go` | `-threads`: the message threads example (beta), built on the SDK's `Beta.Messages.NewThread` helper. | | `*_test.go`, `internal/testserver` | Offline tests: the real SDK against loopback servers, with the standard `testing` package. | ## Requirements @@ -47,6 +48,16 @@ The command exits 0 only when the reply contains text. A reply with only thinkin configuration problem or any request error exits nonzero (2 for a command-line usage error). Errors report the HTTP status and error type, never the credential, the endpoint, the model name or the response body. +## Message threads + +```powershell +go run . -threads # prints the second reply: ORCHID-47 +``` + +The separate `message_threads.go` example uses the same configuration and prints the second reply. It takes no prompt +and cannot be combined with `-stream`. The SDK helper adds `anthropic-beta: message-threads-2026-08-12` and handles replay. +See the [Threads guide](../message-threads.md). + ## Configuration The sample reads one of two variable families and never mixes them, so a URL, a model and a key from different @@ -146,4 +157,6 @@ header canaries (with a control proving the canaries are live), the selected key OAuth beta, user header and beta pass-through, streaming, 401/403/429/500 statuses, cancellation and timeouts, cross-origin and redirect safety, variable-family pairing (mixed `ANTHROPIC_*` and `CLAUDE_*` canaries), credential selection and the command's exit codes (the test binary starts -itself as the command). \ No newline at end of file +itself as the command). The `-threads` tests check the create and continue requests on the wire (beta header on +both turns, previous message ID, only the new message, no `system` or `tools`), the replay on `thread_not_found` +and its absence on an unrelated 404. \ No newline at end of file diff --git a/samples/go/main.go b/samples/go/main.go index c7ac73d..9bb8255 100644 --- a/samples/go/main.go +++ b/samples/go/main.go @@ -2,6 +2,7 @@ // // go run . print the reply text and token usage // go run . -stream stream the reply text as it arrives +// go run . -threads send two turns on one message thread (beta); print the second reply // go run . "your prompt" use your own prompt (flags go before the prompt) // // It exits 0 only when the reply has text; thinking-only or empty replies and every error @@ -30,7 +31,7 @@ import ( const ( defaultPrompt = "What are 3 things to visit in Seattle?" maxTokens = 1024 - usage = "Usage: go run . [-stream] [prompt...]" + usage = "Usage: go run . [-stream] [prompt...]\n go run . -threads" ) // totalTimeout is the application policy of this sample, not a helper default: the whole call, @@ -55,6 +56,7 @@ func run(ctx context.Context, args []string, getenv func(string) string, stdout, flags := flag.NewFlagSet("main", flag.ContinueOnError) flags.SetOutput(io.Discard) stream := flags.Bool("stream", false, "stream the reply text") + threads := flags.Bool("threads", false, "send two turns on one message thread (beta)") if err := flags.Parse(args); err != nil { if errors.Is(err, flag.ErrHelp) { fmt.Fprintln(stdout, usage) @@ -64,6 +66,10 @@ func run(ctx context.Context, args []string, getenv func(string) string, stdout, return 2 } prompt := strings.TrimSpace(strings.Join(flags.Args(), " ")) + if *threads && (*stream || prompt != "") { + fmt.Fprintln(stderr, usage) + return 2 + } if prompt == "" { prompt = defaultPrompt } @@ -92,9 +98,12 @@ func run(ctx context.Context, args []string, getenv func(string) string, stdout, } var code int - if *stream { + switch { + case *threads: + code, err = threadReply(ctx, client, loaded.model, stdout, stderr) + case *stream: code, err = streamReply(ctx, client, params, stdout, stderr) - } else { + default: code, err = printReply(ctx, client, params, stdout, stderr) } if err != nil { diff --git a/samples/go/message_threads.go b/samples/go/message_threads.go new file mode 100644 index 0000000..9b09c56 --- /dev/null +++ b/samples/go/message_threads.go @@ -0,0 +1,47 @@ +package main + +import ( + "context" + "fmt" + "io" + "strings" + + "github.com/anthropics/anthropic-sdk-go/v2" +) + +const ( + threadSystem = "Keep replies short." + threadFirst = "Remember the code ORCHID-47. Reply with OK." + threadSecond = "What code did I ask you to remember? Reply with only the code." +) + +// threadReply sends two turns on one message thread and prints the second reply. The SDK helper adds the beta +// header and replays the conversation if the thread can no longer be continued. +func threadReply(ctx context.Context, client anthropic.Client, model string, stdout, stderr io.Writer) (int, error) { + thread := client.Beta.Messages.NewThread(anthropic.BetaMessageThreadCreateParams{ + Model: anthropic.Model(model), + MaxTokens: maxTokens, + System: []anthropic.BetaTextBlockParam{{Text: threadSystem}}, + }) + var reply *anthropic.BetaMessage + for _, prompt := range []string{threadFirst, threadSecond} { + var err error + reply, err = thread.Send(ctx, anthropic.BetaMessageThreadSendParams{ + Messages: []anthropic.BetaMessageParam{anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock(prompt))}, + }) + if err != nil { + return 0, err + } + } + hasText := false + for _, block := range reply.Content { + if block.Type == "text" && strings.TrimSpace(block.Text) != "" { + fmt.Fprintln(stdout, block.Text) + hasText = true + } + } + if !hasText { + return noText(string(reply.StopReason), stderr), nil + } + return 0, nil +} diff --git a/samples/go/message_threads_test.go b/samples/go/message_threads_test.go new file mode 100644 index 0000000..7d6d9f5 --- /dev/null +++ b/samples/go/message_threads_test.go @@ -0,0 +1,260 @@ +package main + +import ( + "context" + "encoding/json" + "fmt" + "net/http" + "reflect" + "strings" + "sync/atomic" + "testing" + + "github.com/Azure-Samples/claude/samples/go/internal/testserver" +) + +const ( + threadsBeta = "message-threads-2026-08-12" + threadNotFoundBody = `{"type":"error","error":{"type":"not_found_error","message":"test failure","details":{"error_code":"thread_not_found"}}}` + wantFirstTurn = "user: Remember the code ORCHID-47. Reply with OK." + wantSecondTurn = "user: What code did I ask you to remember? Reply with only the code." + createThread = `{"type":"create"}` + continueThread = `{"previous_message_id":"msg_first","type":"continue"}` + keepRepliesShort = `[{"text":"Keep replies short.","type":"text"}]` +) + +var ( + firstReply = testserver.Respond(threadMessage("msg_first", "OK")) + secondReply = testserver.Respond(threadMessage("msg_second", "ORCHID-47")) +) + +func threadMessage(id, text string) string { + return fmt.Sprintf(`{"id":%q,"type":"message","role":"assistant","model":"claude-test","content":[%s],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":1,"output_tokens":2}}`, id, testserver.TextBlock(text)) +} + +// script answers the nth request with the nth handler. +func script(handlers ...testserver.Handler) testserver.Handler { + return func(w http.ResponseWriter, r *http.Request, count int) { + handlers[min(count, len(handlers))-1](w, r, count) + } +} + +// threadRequest is a request body: its top-level fields and its messages as "role: text" lines. +type threadRequest struct { + fields map[string]any + messages []string +} + +func parseThreadRequest(t *testing.T, r testserver.Request) threadRequest { + t.Helper() + request := threadRequest{} + if err := json.Unmarshal([]byte(r.Body), &request.fields); err != nil { + t.Fatalf("request body %q: %v", r.Body, err) + } + messages, _ := request.fields["messages"].([]any) + for _, m := range messages { + message, _ := m.(map[string]any) + blocks, _ := message["content"].([]any) + for _, b := range blocks { + block, _ := b.(map[string]any) + request.messages = append(request.messages, fmt.Sprintf("%v: %v", message["role"], block["text"])) + } + } + return request +} + +// field returns a top-level field as JSON with sorted keys, or "" when it is absent (null counts as present). +func (r threadRequest) field(name string) string { + value, ok := r.fields[name] + if !ok { + return "" + } + encoded, _ := json.Marshal(value) + return string(encoded) +} + +func TestThreadsCreateThenContinueWithOnlyTheNewMessage(t *testing.T) { + testserver.CleanEnvironment(t) + server := testserver.New(t, script(firstReply, secondReply)) + var out output + + if code := out.run([]string{"-threads"}, sampleEnv(server, nil), runOptions{}); code != 0 { + t.Fatalf("exit code %d, stderr %q", code, out.stderr.String()) + } + + if out.stdout.String() != "ORCHID-47\n" || out.stderr.Len() != 0 { + t.Errorf("stdout %q, stderr %q", out.stdout.String(), out.stderr.String()) + } + requests := server.Requests() + if len(requests) != 2 { + t.Fatalf("got %d requests", len(requests)) + } + for i, r := range requests { + request := parseThreadRequest(t, r) + if r.Method != http.MethodPost || !strings.HasPrefix(r.URL, "/anthropic/v1/messages") || r.Header.Get("Anthropic-Beta") != threadsBeta { + t.Errorf("request %d: %s %s, anthropic-beta %q", i, r.Method, r.URL, r.Header.Get("Anthropic-Beta")) + } + if request.field("model") != `"sample-deployment"` || request.field("max_tokens") != "1024" || request.field("tools") != "" { + t.Errorf("request %d: body %s", i, r.Body) + } + } + create, next := parseThreadRequest(t, requests[0]), parseThreadRequest(t, requests[1]) + if create.field("thread") != createThread || create.field("system") != keepRepliesShort || !reflect.DeepEqual(create.messages, []string{wantFirstTurn}) { + t.Errorf("create request = %s", requests[0].Body) + } + if next.field("thread") != continueThread || next.field("system") != "" || !reflect.DeepEqual(next.messages, []string{wantSecondTurn}) { + t.Errorf("continue request = %s", requests[1].Body) + } +} + +func TestThreadsUseTheExistingBearerAuthenticationOnBothTurns(t *testing.T) { + testserver.CleanEnvironment(t) + server := testserver.New(t, script(firstReply, secondReply)) + var calls atomic.Int32 + options := runOptions{clientOverrides: clientOverrides{tokenProvider: func(context.Context) (string, error) { + return fmt.Sprintf("entra-test-token-%d", calls.Add(1)), nil + }}} + var out output + + code := out.run([]string{"-threads"}, map[string]string{"ANTHROPIC_BASE_URL": server.URL, "ANTHROPIC_MODEL": "sample-deployment", "AUTH_MODE": "bearer"}, options) + + if code != 0 || server.Count() != 2 { + t.Fatalf("exit code %d, %d requests, stderr %q", code, server.Count(), out.stderr.String()) + } + for i, r := range server.Requests() { + if got, want := r.Header.Get("Authorization"), fmt.Sprintf("Bearer entra-test-token-%d", i+1); got != want || r.Header.Get("X-Api-Key") != "" || r.Header.Get("Anthropic-Beta") != threadsBeta { + t.Errorf("request %d: headers %v", i, r.Header) + } + } +} + +func TestThreadsReplayTheWholeConversationWhenTheThreadIsNotFound(t *testing.T) { + testserver.CleanEnvironment(t) + server := testserver.New(t, script(firstReply, testserver.JSON(http.StatusNotFound, threadNotFoundBody), secondReply)) + var out output + + if code := out.run([]string{"-threads"}, sampleEnv(server, nil), fastRetries()); code != 0 { + t.Fatalf("exit code %d, stderr %q", code, out.stderr.String()) + } + + if out.stdout.String() != "ORCHID-47\n" || out.stderr.Len() != 0 { + t.Errorf("stdout %q, stderr %q", out.stdout.String(), out.stderr.String()) + } + requests := server.Requests() + if len(requests) != 3 { + t.Fatalf("got %d requests", len(requests)) + } + rejected, replay := parseThreadRequest(t, requests[1]), parseThreadRequest(t, requests[2]) + if rejected.field("thread") != continueThread || rejected.field("system") != "" { + t.Errorf("rejected request = %s", requests[1].Body) + } + wantConversation := []string{wantFirstTurn, "assistant: OK", wantSecondTurn} + if replay.field("thread") != createThread || replay.field("system") != keepRepliesShort || !reflect.DeepEqual(replay.messages, wantConversation) || requests[2].Header.Get("Anthropic-Beta") != threadsBeta { + t.Errorf("replay request = %s", requests[2].Body) + } +} + +func TestThreadsDoNotReplayAnUnrelated404(t *testing.T) { + testserver.CleanEnvironment(t) + bodies := map[string]string{ + "no details": `{"type":"error","error":{"type":"not_found_error","message":"test failure"}}`, + "another code": `{"type":"error","error":{"type":"not_found_error","message":"test failure","details":{"error_code":"model_not_found"}}}`, + } + for name, body := range bodies { + server := testserver.New(t, script(firstReply, testserver.JSON(http.StatusNotFound, body))) + var out output + + code := out.run([]string{"-threads"}, sampleEnv(server, nil), fastRetries()) + + if code != 1 || out.stdout.Len() != 0 || !strings.Contains(out.stderr.String(), "HTTP 404 (not_found_error)") || strings.Contains(out.stderr.String(), "model_not_found") { + t.Errorf("%s: exit code %d, stdout %q, stderr %q", name, code, out.stdout.String(), out.stderr.String()) + } + if server.Count() != 2 { + t.Errorf("%s: got %d requests, want the rejected continue and no replay", name, server.Count()) + } + } +} + +func TestThreadFailuresAreReportedWithoutSecrets(t *testing.T) { + testserver.CleanEnvironment(t) + cases := []struct { + name string + status int + handler testserver.Handler + requests int + }{ + {"first turn", 401, testserver.Error(401), 1}, + {"second turn", 500, script(firstReply, testserver.Error(500)), 2}, + } + for _, c := range cases { + server := testserver.New(t, c.handler) + var out output + + code := out.run([]string{"-threads"}, sampleEnv(server, nil), fastRetries()) + + if want := fmt.Sprintf("HTTP %d (api_error)", c.status); code != 1 || !strings.Contains(out.stderr.String(), want) || out.stdout.Len() != 0 { + t.Errorf("%s: exit code %d, stdout %q, stderr %q", c.name, code, out.stdout.String(), out.stderr.String()) + } + for _, secret := range []string{"sample-key", server.URL, strings.TrimPrefix(server.URL, "http://"), "sample-deployment", "test failure"} { + if strings.Contains(out.stderr.String(), secret) { + t.Errorf("%s: %q leaked: %s", c.name, secret, out.stderr.String()) + } + } + if server.Count() != c.requests { + t.Errorf("%s: got %d requests, want %d", c.name, server.Count(), c.requests) + } + } +} + +func TestAThreadReplyWithoutTextExitsNonzero(t *testing.T) { + testserver.CleanEnvironment(t) + replies := map[string]string{ + "thinking only": thinkingOnly, + "blank text": testserver.Message("end_turn", testserver.TextBlock(" \n")), + } + for name, reply := range replies { + server := testserver.New(t, script(firstReply, testserver.Respond(reply))) + var out output + + code := out.run([]string{"-threads"}, sampleEnv(server, nil), runOptions{}) + + if code != 1 || out.stdout.Len() != 0 || !strings.Contains(out.stderr.String(), "No text response (stop_reason=") { + t.Errorf("%s: exit code %d, stdout %q, stderr %q", name, code, out.stdout.String(), out.stderr.String()) + } + } +} + +func TestThreadsTakeNoPromptAndDoNotCombineWithStream(t *testing.T) { + for _, args := range [][]string{{"-threads", "-stream"}, {"-threads", "Say", "hi"}} { + var out output + + if code := out.run(args, nil, runOptions{}); code != 2 || !strings.Contains(out.stderr.String(), "Usage: go run .") { + t.Errorf("%v: exit code %d, stderr %q", args, code, out.stderr.String()) + } + } + var help output + if code := help.run([]string{"-h"}, nil, runOptions{}); code != 0 || !strings.Contains(help.stdout.String(), "go run . -threads") { + t.Errorf("help: exit code %d, stdout %q", code, help.stdout.String()) + } +} + +func TestOnlyThreadsSendTheBetaHeader(t *testing.T) { + testserver.CleanEnvironment(t) + plain := testserver.New(t, testserver.Respond(textReply)) + streamed := testserver.New(t, testserver.Stream(testserver.Block{Kind: "text", Text: "Hello"})) + var first, second output + + if code := first.run(nil, sampleEnv(plain, nil), runOptions{}); code != 0 { + t.Fatalf("plain: exit code %d, stderr %q", code, first.stderr.String()) + } + if code := second.run([]string{"-stream"}, sampleEnv(streamed, nil), runOptions{}); code != 0 { + t.Fatalf("stream: exit code %d, stderr %q", code, second.stderr.String()) + } + + for _, server := range []*testserver.Server{plain, streamed} { + r := server.Requests()[0] + if r.Header.Get("Anthropic-Beta") != "" || strings.Contains(r.URL, "beta=") || strings.Contains(r.Body, `"thread"`) { + t.Errorf("%s %v %s", r.URL, r.Header, r.Body) + } + } +} diff --git a/samples/java/README.md b/samples/java/README.md index 32e7f5e..3b9e18f 100644 --- a/samples/java/README.md +++ b/samples/java/README.md @@ -12,6 +12,7 @@ retry loop. | `ClientFactory.java` | Generic helper. Builds the standard client with one explicit credential. Knows no identity library and reads no environment or system property. Copy this one file (it needs only the Anthropic SDK). | | `CredentialSelector.java` | The only code that uses Azure Identity: selects one credential class and adapts it to the helper's `Supplier`. | | `SampleSettings.java`, `SampleRunner.java`, `Main.java` | Environment parsing, the Messages/streaming calls, output and exit codes. | +| `MessageThreads.java` | Message Threads entrypoint. | Tests live in `src/test/java/sample/anthropic` and run offline. @@ -48,6 +49,14 @@ mvn -q dependency:build-classpath "-Dmdep.outputFile=target/classpath.txt" java -cp "target/classes;$(Get-Content target/classpath.txt -Raw)" sample.anthropic.Main --stream "Say hello" # use ':' on Linux/macOS ``` +## Message threads + +```powershell +mvn -q compile exec:java "-Dexec.mainClass=sample.anthropic.MessageThreads" +``` + +This separate entrypoint uses the same configuration and prints the second reply. The SDK helper adds `anthropic-beta: message-threads-2026-08-12` and handles replay. See the [Threads guide](../message-threads.md). + ## Configuration Read by the sample entrypoint only (never by `ClientFactory`). Real keys and IDs belong in the environment or a secret diff --git a/samples/java/src/main/java/sample/anthropic/MessageThreads.java b/samples/java/src/main/java/sample/anthropic/MessageThreads.java new file mode 100644 index 0000000..32a0071 --- /dev/null +++ b/samples/java/src/main/java/sample/anthropic/MessageThreads.java @@ -0,0 +1,60 @@ +package sample.anthropic; + +import com.anthropic.helpers.BetaMessageThread; +import com.anthropic.models.beta.messages.BetaMessage; +import com.anthropic.models.beta.messages.BetaStopReason; +import com.anthropic.models.beta.messages.BetaTextBlock; +import com.anthropic.models.beta.messages.ThreadCreateParams; +import java.io.PrintStream; +import java.util.function.Function; +import java.util.stream.Collectors; + +/** Two-turn Message Threads example using the SDK helper. */ +public final class MessageThreads { + private static final long MAX_TOKENS = 1024; + private static final String SYSTEM_PROMPT = "Keep replies short."; + private static final String FIRST_PROMPT = "Remember the code ORCHID-47. Reply with OK."; + private static final String SECOND_PROMPT = "What code did I ask you to remember? Reply with only the code."; + private static final String USAGE = "usage: MessageThreads (takes no arguments; settings come from the environment)"; + + private MessageThreads() {} + + public static void main(String[] args) { + System.exit(run(args, System::getenv, System.out, System.err, CredentialSelector::create)); + } + + static int run( + String[] args, + Function environment, + PrintStream out, + PrintStream err, + SampleRunner.CredentialFactory credentialFactory) { + if (args.length > 0) { + boolean help = args[0].equals("-h") || args[0].equals("--help"); + (help ? out : err).println(USAGE); + return help ? SampleRunner.EXIT_OK : SampleRunner.EXIT_USAGE; + } + + return SampleRunner.execute(environment, err, credentialFactory, (client, settings) -> { + BetaMessageThread thread = client.beta().messages().thread(ThreadCreateParams.builder() + .model(settings.model()) + .maxTokens(MAX_TOKENS) + .system(SYSTEM_PROMPT) + .build()); + thread.send(FIRST_PROMPT); + out.println(textOf(thread.send(SECOND_PROMPT))); + }); + } + + private static String textOf(BetaMessage reply) { + String text = reply.content().stream() + .flatMap(block -> block.text().stream()) + .map(BetaTextBlock::text) + .collect(Collectors.joining()); + if (text.isBlank()) { + throw new SampleRunner.UnusableResponseException("The reply contained no text (stop_reason: " + + reply.stopReason().map(BetaStopReason::asString).orElse("none") + ")."); + } + return text; + } +} \ No newline at end of file diff --git a/samples/java/src/main/java/sample/anthropic/SampleRunner.java b/samples/java/src/main/java/sample/anthropic/SampleRunner.java index 97ebdfa..1cbfbf6 100644 --- a/samples/java/src/main/java/sample/anthropic/SampleRunner.java +++ b/samples/java/src/main/java/sample/anthropic/SampleRunner.java @@ -40,6 +40,12 @@ interface CredentialFactory { TokenCredential create(SampleSettings settings); } + /** What a sample does with the client: it writes its own output and throws on failure. */ + @FunctionalInterface + interface ClientCall { + void run(AnthropicClient client, SampleSettings settings) throws Exception; + } + /** Raised when a successful HTTP response cannot count as a result (for example, no text). */ static final class UnusableResponseException extends RuntimeException { private static final long serialVersionUID = 1L; @@ -75,7 +81,24 @@ static int run( } } String prompt = promptWords.isEmpty() ? DEFAULT_PROMPT : String.join(" ", promptWords); + boolean streaming = stream; + return execute(environment, err, credentialFactory, (client, settings) -> { + MessageCreateParams params = MessageCreateParams.builder() + .model(settings.model()) + .maxTokens(MAX_TOKENS) + .addUserMessage(prompt) + .build(); + if (streaming) { + writeStream(client, params, out); + } else { + writeMessage(client, params, out); + } + }); + } + /** Settings, one credential and one client around a single call, with an exit code for every outcome. */ + static int execute( + Function environment, PrintStream err, CredentialFactory credentialFactory, ClientCall call) { SampleSettings settings; try { settings = SampleSettings.fromEnvironment(environment); @@ -110,16 +133,7 @@ static int run( // The SDK client is deliberately not AutoCloseable, so release it explicitly. try { - MessageCreateParams params = MessageCreateParams.builder() - .model(settings.model()) - .maxTokens(MAX_TOKENS) - .addUserMessage(prompt) - .build(); - if (stream) { - writeStream(client, params, out); - } else { - writeMessage(client, params, out); - } + call.run(client, settings); } finally { client.close(); } diff --git a/samples/java/src/test/java/sample/anthropic/MessageThreadsTest.java b/samples/java/src/test/java/sample/anthropic/MessageThreadsTest.java new file mode 100644 index 0000000..ac81fdb --- /dev/null +++ b/samples/java/src/test/java/sample/anthropic/MessageThreadsTest.java @@ -0,0 +1,330 @@ +package sample.anthropic; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import com.azure.core.credential.AccessToken; +import com.azure.core.credential.TokenCredential; +import com.azure.core.credential.TokenRequestContext; +import com.fasterxml.jackson.databind.JsonNode; +import com.fasterxml.jackson.databind.ObjectMapper; +import com.sun.net.httpserver.HttpExchange; +import java.io.ByteArrayOutputStream; +import java.io.IOException; +import java.io.PrintStream; +import java.nio.charset.StandardCharsets; +import java.time.OffsetDateTime; +import java.util.ArrayList; +import java.util.HashMap; +import java.util.List; +import java.util.Map; +import java.util.concurrent.atomic.AtomicInteger; +import java.util.function.Function; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.CsvSource; +import org.junit.jupiter.params.provider.ValueSource; +import reactor.core.publisher.Mono; + +/** The thread example end to end: the real SDK helper against a loopback server that records every request. */ +class MessageThreadsTest { + private static final ObjectMapper JSON = new ObjectMapper(); + private static final String BETA = "message-threads-2026-08-12"; + private static final String FIRST = "user: Remember the code ORCHID-47. Reply with OK."; + private static final String SECOND = "user: What code did I ask you to remember? Reply with only the code."; + + private record RunResult(int exitCode, String output, String error) {} + + private static final class FakeCredential implements TokenCredential, AutoCloseable { + private final AtomicInteger calls = new AtomicInteger(); + boolean closed; + + @Override + public Mono getToken(TokenRequestContext context) { + return Mono.fromSupplier(this::token); + } + + @Override + public AccessToken getTokenSync(TokenRequestContext context) { + return token(); + } + + private AccessToken token() { + return new AccessToken("thread-token-" + calls.incrementAndGet(), OffsetDateTime.now().plusHours(1)); + } + + @Override + public void close() { + closed = true; + } + } + + private static Function env(String spec) { + Map values = new HashMap<>(); + for (String pair : spec.split(";")) { + if (!pair.isEmpty()) { + int separator = pair.indexOf('='); + values.put(pair.substring(0, separator), pair.substring(separator + 1)); + } + } + return values::get; + } + + private static RunResult run(String[] args, String environment, FakeCredential credential) { + ByteArrayOutputStream output = new ByteArrayOutputStream(); + ByteArrayOutputStream error = new ByteArrayOutputStream(); + int exitCode = MessageThreads.run( + args, + env(environment), + new PrintStream(output, true, StandardCharsets.UTF_8), + new PrintStream(error, true, StandardCharsets.UTF_8), + settings -> credential); + return new RunResult( + exitCode, + output.toString(StandardCharsets.UTF_8).replace("\r\n", "\n"), + error.toString(StandardCharsets.UTF_8).replace("\r\n", "\n")); + } + + private static RunResult run(RecordingServer server) { + return run(new String[0], keyEnv(server), new FakeCredential()); + } + + private static String keyEnv(RecordingServer server) { + return "ANTHROPIC_BASE_URL=" + server.baseUrl() + ";ANTHROPIC_MODEL=claude-sonnet-5-5;AUTH_MODE=api_key;" + + "ANTHROPIC_API_KEY=thread-test-key"; + } + + private static String bearerEnv(RecordingServer server) { + return "ANTHROPIC_BASE_URL=" + server.baseUrl() + ";ANTHROPIC_MODEL=claude-sonnet-5-5;AUTH_MODE=bearer"; + } + + private static void reply(HttpExchange exchange, String id, String text) throws IOException { + Responses.json(exchange, 200, Responses.messageJson(Responses.quote(text), 11, 5).replace("msg_test", id)); + } + + private static void threadError(HttpExchange exchange, int status, String type, String errorCode) throws IOException { + Responses.json(exchange, status, "{\"type\":\"error\",\"error\":{\"type\":\"" + type + "\",\"message\":\"synthetic\"," + + "\"details\":{\"error_code\":\"" + errorCode + "\"}}}"); + } + + private static JsonNode body(Recorded request) throws IOException { + return JSON.readTree(request.body()); + } + + /** One "role: text" entry per message, whether its content is a string or a list of text blocks. */ + private static List messages(JsonNode body) { + List messages = new ArrayList<>(); + for (JsonNode message : body.get("messages")) { + JsonNode content = message.get("content"); + StringBuilder text = new StringBuilder(); + if (content.isTextual()) { + text.append(content.asText()); + } else { + content.forEach(block -> text.append(block.get("text").asText())); + } + messages.add(message.get("role").asText() + ": " + text); + } + return messages; + } + + private static void assertThreadRequest(Recorded request) { + assertEquals("POST", request.method()); + assertTrue(request.path().startsWith("/v1/messages"), request.path()); + assertEquals(BETA, request.header("anthropic-beta")); + request.assertNoCanaryEgress(); + } + + @Test + void createsTheThreadThenContinuesWithOnlyTheNewMessage() throws Exception { + try (RecordingServer server = new RecordingServer()) { + server.enqueue((exchange, request) -> reply(exchange, "msg_first", "OK")); + server.enqueue((exchange, request) -> reply(exchange, "msg_second", "ORCHID-47")); + + RunResult result = run(server); + + assertEquals(0, result.exitCode(), result.error()); + assertEquals("ORCHID-47\n", result.output()); + assertEquals("", result.error()); + List requests = server.requests(); + assertEquals(2, requests.size()); + requests.forEach(MessageThreadsTest::assertThreadRequest); + + JsonNode create = body(requests.get(0)); + assertEquals(JSON.readTree("{\"type\":\"create\"}"), create.get("thread")); + assertEquals("claude-sonnet-5-5", create.get("model").asText()); + assertEquals(1024, create.get("max_tokens").asLong()); + assertEquals("Keep replies short.", create.get("system").asText()); + assertEquals(List.of(FIRST), messages(create)); + + JsonNode proceed = body(requests.get(1)); + assertEquals( + JSON.readTree("{\"type\":\"continue\",\"previous_message_id\":\"msg_first\"}"), proceed.get("thread")); + assertEquals(create.get("model"), proceed.get("model")); + assertEquals(create.get("max_tokens"), proceed.get("max_tokens")); + assertEquals(List.of(SECOND), messages(proceed)); + assertFalse(proceed.has("system"), "system must be left out, even as null"); + assertFalse(proceed.has("tools"), "tools must be left out, even as null"); + } + } + + @ParameterizedTest + @CsvSource({ + "404,not_found_error,thread_not_found", + "400,invalid_request_error,thread_already_continued", + "400,invalid_request_error,thread_continue_in_flight" + }) + void replaysTheWholeConversationOnceWhenTheThreadCannotBeContinued(int status, String type, String errorCode) + throws Exception { + try (RecordingServer server = new RecordingServer()) { + server.enqueue((exchange, request) -> reply(exchange, "msg_first", "OK")); + server.enqueue((exchange, request) -> threadError(exchange, status, type, errorCode)); + server.enqueue((exchange, request) -> reply(exchange, "msg_third", "ORCHID-47")); + + RunResult result = run(server); + + assertEquals(0, result.exitCode(), result.error()); + assertEquals("ORCHID-47\n", result.output()); + List requests = server.requests(); + assertEquals(3, requests.size()); + requests.forEach(MessageThreadsTest::assertThreadRequest); + + JsonNode rejected = body(requests.get(1)); + assertEquals("continue", rejected.get("thread").get("type").asText()); + assertEquals(List.of(SECOND), messages(rejected)); + + JsonNode replay = body(requests.get(2)); + assertEquals(JSON.readTree("{\"type\":\"create\"}"), replay.get("thread")); + assertEquals("Keep replies short.", replay.get("system").asText()); + assertEquals(List.of(FIRST, "assistant: OK", SECOND), messages(replay)); + } + } + + @Test + void aReplayThatIsNotFoundAgainIsReportedNotRepeated() throws Exception { + try (RecordingServer server = new RecordingServer()) { + server.enqueue((exchange, request) -> reply(exchange, "msg_first", "OK")); + server.enqueue((exchange, request) -> threadError(exchange, 404, "not_found_error", "thread_not_found")); + server.enqueue((exchange, request) -> threadError(exchange, 404, "not_found_error", "thread_not_found")); + + RunResult result = run(server); + + assertEquals(SampleRunner.EXIT_FAILURE, result.exitCode()); + assertEquals("", result.output()); + assertTrue(result.error().contains("NotFoundException (HTTP 404)"), result.error()); + assertEquals(3, server.requests().size()); + } + } + + // A missing thread is told apart by error.details.error_code, never by the status alone. + @ParameterizedTest + @CsvSource({"0,thread_not_found", "1,model_not_found", "1,"}) + void anotherNotFoundIsReportedNotReplayed(int failing, String errorCode) throws Exception { + try (RecordingServer server = new RecordingServer()) { + if (failing == 1) { + server.enqueue((exchange, request) -> reply(exchange, "msg_first", "OK")); + } + server.enqueue((exchange, request) -> { + if (errorCode == null) { + Responses.error(exchange, 404, "not_found_error", "model: nope"); + } else { + threadError(exchange, 404, "not_found_error", errorCode); + } + }); + + RunResult result = run(server); + + assertEquals(SampleRunner.EXIT_FAILURE, result.exitCode()); + assertEquals("", result.output()); + assertTrue(result.error().contains("NotFoundException (HTTP 404)"), result.error()); + assertEquals(failing + 1, server.requests().size()); + } + } + + @Test + void anUnsupportedThreadRequestIsAnErrorNotAnUnthreadedFallback() throws Exception { + try (RecordingServer server = new RecordingServer()) { + server.enqueue((exchange, request) -> reply(exchange, "msg_first", "OK")); + server.enqueue((exchange, request) -> + threadError(exchange, 400, "invalid_request_error", "thread_unsupported_request")); + + RunResult result = run(server); + + assertEquals(SampleRunner.EXIT_FAILURE, result.exitCode()); + assertEquals("", result.output()); + assertTrue(result.error().contains("BadRequestException (HTTP 400)"), result.error()); + assertEquals(2, server.requests().size()); + } + } + + @ParameterizedTest + @ValueSource(strings = {"", " "}) + void aSecondReplyWithoutTextIsAFailure(String text) throws Exception { + try (RecordingServer server = new RecordingServer()) { + server.enqueue((exchange, request) -> reply(exchange, "msg_first", "OK")); + server.enqueue((exchange, request) -> reply(exchange, "msg_second", text)); + + RunResult result = run(server); + + assertEquals(SampleRunner.EXIT_FAILURE, result.exitCode()); + assertEquals("", result.output()); + assertTrue(result.error().contains("UnusableResponseException"), result.error()); + assertTrue(result.error().contains("no text (stop_reason: end_turn)"), result.error()); + } + } + + @Test + void everyTurnCarriesItsOwnBearerToken() throws Exception { + try (RecordingServer server = new RecordingServer()) { + FakeCredential credential = new FakeCredential(); + + RunResult result = run(new String[0], bearerEnv(server), credential); + + assertEquals(0, result.exitCode(), result.error()); + List requests = server.requests(); + assertEquals(2, requests.size()); + for (int turn = 0; turn < 2; turn++) { + Recorded request = requests.get(turn); + assertThreadRequest(request); + assertEquals("Bearer " + "thread-token-" + (turn + 1), request.header("Authorization")); + assertFalse(request.has("x-api-key")); + } + assertTrue(credential.closed); + } + } + + @Test + void rejectedCredentialsAreReportedWithoutTheToken() throws Exception { + try (RecordingServer server = new RecordingServer()) { + server.enqueue((exchange, request) -> + Responses.error(exchange, 401, "authentication_error", "denied for thread-token-1")); + + RunResult result = run(new String[0], bearerEnv(server), new FakeCredential()); + + assertEquals(SampleRunner.EXIT_FAILURE, result.exitCode()); + assertEquals("", result.output()); + assertTrue(result.error().contains("UnauthorizedException (HTTP 401)"), result.error()); + assertTrue(result.error().contains("[redacted]"), result.error()); + assertFalse(result.error().contains("thread-token"), result.error()); + assertEquals(1, server.requests().size()); + } + } + + @Test + void invalidConfigurationAndArgumentsSendNothing() throws Exception { + try (RecordingServer server = new RecordingServer()) { + RunResult noModel = run( + new String[0], "ANTHROPIC_BASE_URL=" + server.baseUrl() + ";AUTH_MODE=bearer", new FakeCredential()); + RunResult argument = run(new String[] {"hello"}, keyEnv(server), new FakeCredential()); + RunResult help = run(new String[] {"--help"}, "", new FakeCredential()); + + assertEquals(SampleRunner.EXIT_USAGE, noModel.exitCode()); + assertTrue(noModel.error().contains("ANTHROPIC_MODEL"), noModel.error()); + assertEquals(SampleRunner.EXIT_USAGE, argument.exitCode()); + assertTrue(argument.error().contains("usage: MessageThreads"), argument.error()); + assertEquals(SampleRunner.EXIT_OK, help.exitCode()); + assertTrue(help.output().contains("usage: MessageThreads"), help.output()); + assertTrue(server.requests().isEmpty()); + } + } +} \ No newline at end of file diff --git a/samples/message-threads.md b/samples/message-threads.md new file mode 100644 index 0000000..98aa312 --- /dev/null +++ b/samples/message-threads.md @@ -0,0 +1,66 @@ +# Message Threads + +[Message Threads](https://platform.claude.com/docs/en/build-with-claude/message-threads) adds server-side conversation state to the Messages API. It requires `anthropic-beta: message-threads-2026-08-12`. These examples opt in separately; the existing quickstarts stay unchanged. + +Each example asks Claude to remember `ORCHID-47`, then recall it on a second turn using only the new message. + +| Language | Example / run instructions | +|---|---| +| Python | [`python src/message_threads.py`](../src/message_threads.py), from the repository root | +| TypeScript | [Run](typescript/README.md#message-threads) | +| C# | [Run](dotnet/README.md#message-threads) | +| Go | [Run](go/README.md#message-threads) | +| Java | [Run](java/README.md#message-threads) | +| PHP | [Run](php/README.md#message-threads) | +| Ruby | [Run](ruby/README.md#message-threads) | + +Use the same [endpoint, model and authentication configuration](README.md#configuration) as the other samples. Pass the Foundry **deployment name**, not a different native model ID. + +## SDK checks + +All seven use native SDK thread helpers, not a custom replay implementation. The helpers add the beta header and keep the transcript in memory. Persist it yourself if it must survive a process restart. + +| Language | Tested SDK | Notes | +|---|---|---| +| Python | `anthropic` 2.4.0 | Raised the floor from 2.1, which has no thread helper | +| TypeScript | `@anthropic-ai/sdk` 1.4.0 | Updated the tested pin from 1.1 | +| C# | `Anthropic` 13.3.0 | Existing version works | +| Go | `anthropic-sdk-go/v2` 2.4.0 | Existing version works | +| Java | `anthropic-java` 3.3.0 | Existing version works | +| PHP | `anthropic-ai/sdk` 1.3.0 | Existing version works; on Windows, configure [TLS certificates](php/README.md#tls-certificates) | +| Ruby | `anthropic` 2.3.0 | Existing version works | + +Each example passed offline wire tests and a live two-turn Foundry recall. PHP/Ruby used their local Azure CLI fallback; the other five used Azure Developer CLI credentials. + +## Contract + +- Create: send the conversation, `system` and `tools`, with `thread: {"type":"create"}`. +- Continue: send only new messages, with `thread: {"type":"continue","previous_message_id":""}`. Omit `system` and `tools`, including null values. +- Keep the model, beta headers and other [fixed fields](https://platform.claude.com/docs/en/build-with-claude/message-threads#what-to-send-on-each-request) unchanged. Each response ID can be continued once. +- Keep your own transcript. Threads are best-effort and expire after five idle minutes. On `404` with `error.details.error_code = thread_not_found`, replay the full conversation in a new create request. Do not treat every 404 as an expired thread. +- For streaming, wait for `message_stop` before continuing. + +Threads are **not ZDR eligible**. The documented deletion window is at most one hour after last use; there is no list, get or delete API. Threads do not enable prompt caching or reduce token pricing by themselves. + +## Foundry API checks + +Tested on **2026-11-10**, against existing **Opus 5.5 and Sonnet 5.5** deployments in `eastus2`, with Microsoft Entra ID. No infrastructure changes were needed. + +| Check | Observed | +|---|---| +| Create, delta-only continue, third-turn recall | Passed | +| Streaming create followed by continue | Passed | +| Tool call followed by a delta-only tool result | Passed; stored tools were retained | +| Missing beta header | `400`: `thread: Extra inputs are not permitted` | +| Missing / expired previous ID | `404`, `thread_not_found`; idle expiry checked after more than five minutes | +| Reusing an already-continued ID | `400`, `thread_already_continued` | +| `system` on continue, or explicit null `system` / `tools` | Rejected with `400` | +| Changing cache TTL or output effort | `400`, `thread_fingerprint_mismatch`; the unchanged retry still worked | +| Full-conversation replay after `thread_not_found` | Passed; the Python helper also recovered after 310 seconds idle | +| Token counting with `thread` | Rejected with `400`, as documented | + +The basic flow also passed with both `anthropic-version: 2026-10-21` and `2023-06-01`. + +**One contract discrepancy:** adding or removing top-level `cache_control` on continue returned `200` on both models. The guide marks that field as fixed and says a changed value returns `400`. Changing its TTL from `5m` to `1h` did return the documented fingerprint error. Keep it unchanged regardless. + +This compares Foundry observations with Anthropic's documented contract, **not** a live native-endpoint comparison: no Anthropic account key was available. The cache-control discrepancy is not proven to be Foundry-specific. Other regions, managed identity, the one-hour deletion bound and unsupported organization settings were not tested. diff --git a/samples/php/README.md b/samples/php/README.md index 2070fcd..0c79ebb 100644 --- a/samples/php/README.md +++ b/samples/php/README.md @@ -5,7 +5,9 @@ Calls a Claude deployment through the **standard** Anthropic PHP SDK client (`An | File | Purpose | |---|---| | `main.php` | Entry point: one Messages call, printed whole or streamed (`--stream`). | +| `message_threads.php` | Entry point: two turns on one [message thread](../message-threads.md). | | `src/Sample.php` | Reads the environment, builds the client, prints the text and usage. | +| `src/MessageThreads.php` | The thread sample. `MessageThreads::converse()` runs it on any standard client. | | `src/ClientFactory.php` | The generic helper. `ClientFactory::createClient()` returns the standard client with exactly one explicit credential. It reads no environment variables and imports no cloud-provider code. | | `src/CliTokenProvider.php` | Token provider for local development: a command-line fallback that runs `az account get-access-token`. | | `tests/` | Offline tests: no cloud, no credentials. | @@ -100,6 +102,16 @@ Both modes print only the text, then the token usage (the sample waits up to 120 Thinking blocks are not printed. A response without any text fails with a message and a non-zero exit status instead of reporting success; so do API errors, credential failures and bad configuration (exit status 1; an unknown argument exits with 2). A failure prints `Error: ...` and then one ` caused by: ...` line per underlying error (for example the transport error behind an `APIConnectionException`), with credentials and token-like strings replaced by `[redacted]`. +## Message threads + +```sh +php message_threads.php # two turns on one message thread +``` + +It uses the same configuration as `main.php` and prints the second reply. The SDK helper adds `anthropic-beta: message-threads-2026-08-12` and handles replay. See the [Threads guide](../message-threads.md). + +`MessageThreads::converse($client, $model, $stdout)` runs the same two turns on any standard client, for example one from `ClientFactory::createClient()` with your own token provider. + ## Authentication **`AUTH_MODE=bearer` is a local-development fallback** (the legacy profile's default; the canonical profile needs it set explicitly). The sample runs `az account get-access-token --scope --output json` (adding `--tenant ` when set) for every token request and sends the returned `accessToken` as `Authorization: Bearer`. The Azure CLI owns token caching and renewal; the sample keeps no cache. The price is one CLI process per HTTP attempt, which takes seconds on a typical machine. @@ -146,7 +158,7 @@ composer test The suite uses PHP's built-in `assert()` (the runner refuses to start with assertions off, which would pass silently) and needs no framework. It runs offline: -- a recording PSR-18 transport checks the request the SDK builds: the Foundry-style and native paths and the model, a rotating bearer token, a resource key in `x-api-key` and the native `Authorization` key, the API version, no OAuth beta, canaries for `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_PROFILE`, `ANTHROPIC_BASE_URL` and `ANTHROPIC_CUSTOM_HEADERS` (with a control showing the SDK defaults would send them), streaming, HTTP error statuses, retries that fetch a fresh token, and redirects; +- a recording PSR-18 transport checks the request the SDK builds: the Foundry-style and native paths and the model, a rotating bearer token, a resource key in `x-api-key` and the native `Authorization` key, the API version, no OAuth beta, canaries for `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_PROFILE`, `ANTHROPIC_BASE_URL` and `ANTHROPIC_CUSTOM_HEADERS` (with a control showing the SDK defaults would send them), streaming, HTTP error statuses, retries that fetch a fresh token, redirects, and the message threads sample (the beta on both turns; a create, then a continue with only the new message and no `system` or `tools`; a replay after a 404 `thread_not_found` and none after any other 404); - the token provider (`CliTokenProvider`) is tested with a fake process runner and with a fixture `az` (a `.cmd` on Windows, a shell script elsewhere) that is really launched; - the entry point is tested end to end, including mixed-family canaries (decoy `ANTHROPIC_*` and `CLAUDE_*` values must never be paired with the other profile's endpoint, model or key) and the 120 second policy; the error output (the cause chain behind a connection failure, credential redaction, the certificate hint) is tested with synthetic failures and with a real refused connection; a few tests talk to PHP's built-in web server on a loopback port through the default Guzzle transport (credential headers on a real socket, redirects, streaming and the timeout). Nothing leaves your machine. diff --git a/samples/php/message_threads.php b/samples/php/message_threads.php new file mode 100644 index 0000000..1ba97ec --- /dev/null +++ b/samples/php/message_threads.php @@ -0,0 +1,13 @@ +#!/usr/bin/env php + $arguments command-line arguments after the script name + * @param array $env + * @param resource $stdout + * @param resource $stderr + * @param ClientInterface|null $httpClient PSR-18 transport override (tests) + * @param (callable(list): array{int, string})|null $runCli Azure CLI process override (tests) + */ + public static function run(array $arguments, array $env, $stdout, $stderr, ?ClientInterface $httpClient = null, ?callable $runCli = null): int + { + foreach ($arguments as $argument) { + if ('-h' === $argument || '--help' === $argument) { + fwrite($stdout, self::USAGE); + + return 0; + } + fwrite($stderr, sprintf("Unknown argument: %s\n%s", $argument, self::USAGE)); + + return 2; + } + + $issued = new \ArrayObject(); + try { + [$client, $model] = Sample::configure($env, $httpClient, $runCli, $issued); + self::converse($client, $model, $stdout); + } catch (\Throwable $error) { + $configured = array_filter(array_map(static fn (string $name): mixed => $env[$name] ?? null, Sample::KEY_VARIABLES), 'is_string'); + fwrite($stderr, Sample::describeError($error, [...$configured, ...$issued->getArrayCopy()])); + + return 1; + } + + return 0; + } + + /** + * @param resource $stdout + * + * @return string the text that was printed + */ + public static function converse(Client $client, string $model, $stdout): string + { + $thread = $client->beta->messages->thread( + maxTokens: Sample::MAX_TOKENS, + model: $model, + system: self::SYSTEM, + ); + $thread->send(['role' => 'user', 'content' => self::FIRST_PROMPT]); + $reply = $thread->send(['role' => 'user', 'content' => self::SECOND_PROMPT]); + + $blocks = []; + foreach ($reply->content as $block) { + if ($block instanceof BetaTextBlock && '' !== trim($block->text)) { + $blocks[] = $block->text; + } + } + if ([] === $blocks) { + throw new \RuntimeException(Sample::noText($reply->stopReason)); + } + $text = implode("\n", $blocks); + fwrite($stdout, $text."\n"); + + return $text; + } +} \ No newline at end of file diff --git a/samples/php/src/Sample.php b/samples/php/src/Sample.php index 17ca078..6362682 100644 --- a/samples/php/src/Sample.php +++ b/samples/php/src/Sample.php @@ -34,7 +34,7 @@ final class Sample private const USAGE = "Usage: php main.php [--stream]\n"; /** Variables whose values are credentials: they are removed from error output. */ - private const KEY_VARIABLES = ['ANTHROPIC_API_KEY', 'CLAUDE_API_KEY', 'ANTHROPIC_AUTH_TOKEN']; + public const KEY_VARIABLES = ['ANTHROPIC_API_KEY', 'CLAUDE_API_KEY', 'ANTHROPIC_AUTH_TOKEN']; private const MAX_CAUSES = 5; @@ -292,7 +292,7 @@ private static function redact(string $text, array $secrets): string return strlen($text) > self::MAX_MESSAGE_LENGTH ? substr($text, 0, self::MAX_MESSAGE_LENGTH).'...' : $text; } - private static function noText(?string $stopReason): string + public static function noText(?string $stopReason): string { return sprintf('No text response (stop_reason=%s). Increase max_tokens if the response exhausted its budget.', $stopReason ?? 'none'); } diff --git a/samples/php/tests/MessageThreadsTest.php b/samples/php/tests/MessageThreadsTest.php new file mode 100644 index 0000000..1d2c3fd --- /dev/null +++ b/samples/php/tests/MessageThreadsTest.php @@ -0,0 +1,267 @@ + $arguments + * @param array $env + * + * @return array{int, string, string} exit code, stdout, stderr + */ +function run_threads(array $arguments, array $env, ?Recorder $recorder = null): array +{ + $stdout = fopen('php://memory', 'w+'); + $stderr = fopen('php://memory', 'w+'); + $code = MessageThreads::run($arguments, $env, $stdout, $stderr, $recorder, static fn (): array => [0, '{"accessToken":"entra-test-token"}']); + rewind($stdout); + rewind($stderr); + + return [$code, (string) stream_get_contents($stdout), (string) stream_get_contents($stderr)]; +} + +/** @return array a reply with an id of its own, which a continue can name */ +function thread_reply(string $id, string $text = 'OK'): array +{ + return [...message_body($text), 'id' => $id]; +} + +function thread_error(int $status, string $type, ?string $code = null, string $message = 'The request was rejected.'): Response +{ + $error = ['type' => $type, 'message' => $message]; + if (null !== $code) { + $error['details'] = ['error_code' => $code]; + } + + return json_response(['type' => 'error', 'error' => $error], $status); +} + +/** Answers the n-th request with the n-th response. A request beyond the script fails the test. */ +function scripted(ResponseInterface ...$script): Recorder +{ + return new Recorder(static fn (RequestInterface $request, int $call): ResponseInterface => $script[$call - 1] ?? throw new \LogicException("Unexpected request $call.")); +} + +/** @return array the JSON body of the request at $index (from 0) */ +function body_of(Recorder $recorder, int $index): array +{ + return json_decode((string) $recorder->requests[$index]->getBody(), true, flags: JSON_THROW_ON_ERROR); +} + +/** + * @param array $body + * + * @return list the top-level field names, sorted + */ +function fields_of(array $body): array +{ + $names = array_keys($body); + sort($names); + + return $names; +} + +test('message threads: the first turn creates the thread, the second continues it with only its new message', function (): void { + with_env([], static function (): void { + $recorder = scripted(json_response(thread_reply('msg_first')), json_response(thread_reply('msg_second', 'ORCHID-47')), json_response(message_body())); + $client = make($recorder); + $stdout = fopen('php://memory', 'w+'); + + same('ORCHID-47', MessageThreads::converse($client, MODEL, $stdout), 'returned text'); + rewind($stdout); + same("ORCHID-47\n", stream_get_contents($stdout), 'printed text'); + same(2, count($recorder->requests), 'one request per turn'); + foreach ($recorder->requests as $turn => $request) { + $headers = headers_of($request); + same('POST', $request->getMethod(), "turn $turn: method"); + same('/anthropic/v1/messages', $request->getUri()->getPath(), "turn $turn: path"); + same(THREADS_BETA, $headers['anthropic-beta'] ?? null, "turn $turn: beta"); + same('Bearer selected-token', $headers['authorization'] ?? null, "turn $turn: credential"); + same(Client::ANTHROPIC_API_VERSION, $headers['anthropic-version'] ?? null, "turn $turn: API version"); + assert(!isset($headers['x-api-key']) && !isset($headers['api-key']), "turn $turn: one credential header only"); + same(MODEL, body_of($recorder, $turn)['model'], "turn $turn: model"); + same(Sample::MAX_TOKENS, body_of($recorder, $turn)['max_tokens'], "turn $turn: max_tokens"); + } + + $first = body_of($recorder, 0); + same(['max_tokens', 'messages', 'model', 'system', 'thread'], fields_of($first), 'create request fields'); + same(['type' => 'create'], $first['thread'], 'create'); + same(MessageThreads::SYSTEM, $first['system'], 'system'); + same([['role' => 'user', 'content' => MessageThreads::FIRST_PROMPT]], $first['messages'], 'first turn messages'); + + $second = body_of($recorder, 1); + same(['max_tokens', 'messages', 'model', 'thread'], fields_of($second), 'a continue has no system and no tools, not even null'); + same(['type' => 'continue', 'previous_message_id' => 'msg_first'], $second['thread'], 'continue from the first reply'); + same([['role' => 'user', 'content' => MessageThreads::SECOND_PROMPT]], $second['messages'], 'only the new message'); + + send($client); + assert(!isset(headers_of($recorder->requests[2])['anthropic-beta']), 'the beta belongs to the thread requests, not to the client'); + }); +}); + +test('message threads: a 404 thread_not_found is replayed once as a new thread with the whole conversation', function (): void { + with_env([], static function (): void { + $recorder = scripted( + json_response(thread_reply('msg_first')), + thread_error(404, 'not_found_error', 'thread_not_found'), + json_response(thread_reply('msg_replayed', 'ORCHID-47')), + ); + $stdout = fopen('php://memory', 'w+'); + + same('ORCHID-47', MessageThreads::converse(make($recorder), MODEL, $stdout), 'returned text'); + same(3, count($recorder->requests), 'create, rejected continue, replay'); + foreach ($recorder->requests as $call => $request) { + same(THREADS_BETA, headers_of($request)['anthropic-beta'] ?? null, "request $call: beta"); + } + same(['type' => 'continue', 'previous_message_id' => 'msg_first'], body_of($recorder, 1)['thread'], 'the rejected request'); + + $replay = body_of($recorder, 2); + same(['max_tokens', 'messages', 'model', 'system', 'thread'], fields_of($replay), 'the replay is a create request'); + same(['type' => 'create'], $replay['thread'], 'create'); + same(MessageThreads::SYSTEM, $replay['system'], 'system'); + same([ + ['role' => 'user', 'content' => MessageThreads::FIRST_PROMPT], + ['role' => 'assistant', 'content' => [['type' => 'text', 'text' => 'OK']]], + ['role' => 'user', 'content' => MessageThreads::SECOND_PROMPT], + ], $replay['messages'], 'the whole conversation'); + }); + + $recorder = scripted( + json_response(thread_reply('msg_first')), + thread_error(404, 'not_found_error', 'thread_not_found'), + thread_error(404, 'not_found_error', 'thread_not_found'), + ); + [$code, $stdout, $stderr] = with_env([], static fn (): array => run_threads([], SAMPLE_ENV, $recorder)); + same(1, $code, 'a second thread_not_found: exit code'); + same('', $stdout, 'a second thread_not_found: stdout'); + assert(str_starts_with($stderr, 'Error: NotFoundException: '), "a second thread_not_found is reported: $stderr"); + same(3, count($recorder->requests), 'the replay is not repeated'); +}); + +test('message threads: any other 404 is an error and is not replayed', function (): void { + $cases = [ + 'a model that does not exist' => thread_error(404, 'not_found_error', message: 'model: no-such-deployment'), + 'another error code' => thread_error(404, 'not_found_error', 'model_not_found'), + 'thread_not_found in the message only' => thread_error(404, 'not_found_error', message: 'thread_not_found'), + ]; + foreach ($cases as $label => $notFound) { + $recorder = scripted(json_response(thread_reply('msg_first')), $notFound); + [$code, $stdout, $stderr] = with_env([], static fn (): array => run_threads([], SAMPLE_ENV, $recorder)); + same(1, $code, "$label: exit code"); + same('', $stdout, "$label: stdout"); + assert(str_starts_with($stderr, 'Error: NotFoundException: '), "$label: the API error is reported: $stderr"); + same(2, count($recorder->requests), "$label: no replay"); + } +}); + +test('message threads: a request the API cannot thread fails and is never sent again without a thread', function (): void { + $unsupported = static fn (): Response => thread_error(400, 'invalid_request_error', 'thread_unsupported_request'); + foreach (['the first turn' => [$unsupported()], 'the second turn' => [json_response(thread_reply('msg_first')), $unsupported()]] as $label => $script) { + $recorder = scripted(...$script); + [$code, $stdout, $stderr] = with_env([], static fn (): array => run_threads([], SAMPLE_ENV, $recorder)); + same(1, $code, "$label: exit code"); + same('', $stdout, "$label: stdout"); + assert(str_starts_with($stderr, 'Error: BadRequestException: '), "$label: the API error is reported: $stderr"); + same(count($script), count($recorder->requests), "$label: no further request"); + foreach (array_keys($recorder->requests) as $call) { + assert(isset(body_of($recorder, $call)['thread']), "$label: request $call carries a thread"); + } + } +}); + +test('message threads: a second reply without text is an error, not a silent success', function (): void { + $thinkingOnly = thread_reply('msg_second'); + $thinkingOnly['content'] = [['type' => 'thinking', 'thinking' => 'not for display', 'signature' => 'sample']]; + foreach (['thinking only' => $thinkingOnly, 'blank text' => thread_reply('msg_second', " \n")] as $label => $second) { + $recorder = scripted(json_response(thread_reply('msg_first')), json_response($second)); + [$code, $stdout, $stderr] = with_env([], static fn (): array => run_threads([], SAMPLE_ENV, $recorder)); + same(1, $code, "$label: exit code"); + same('', $stdout, "$label: stdout"); + same("Error: No text response (stop_reason=end_turn). Increase max_tokens if the response exhausted its budget.\n", $stderr, "$label: stderr"); + } +}); + +test('message threads: the entry point sends the configured credential, API version and model on both turns', function (): void { + $cases = [ + 'legacy profile, bearer from the Azure CLI' => [SAMPLE_ENV, 'authorization', 'Bearer entra-test-token', Client::ANTHROPIC_API_VERSION, MODEL], + 'legacy profile, key header and API version' => [ + SAMPLE_ENV + ['AUTH_MODE' => 'api_key', 'CLAUDE_API_KEY' => 'sample-key', 'API_KEY_HEADER' => 'x-api-key', 'ANTHROPIC_API_VERSION' => '2023-06-01'], + 'x-api-key', 'sample-key', '2023-06-01', MODEL, + ], + 'canonical profile and its own model' => [ + ['ANTHROPIC_BASE_URL' => BASE_URL, 'ANTHROPIC_MODEL' => 'canonical-model', 'AUTH_MODE' => 'api_key', 'ANTHROPIC_API_KEY' => 'sample-key', 'API_KEY_HEADER' => 'x-api-key'], + 'x-api-key', 'sample-key', Client::ANTHROPIC_API_VERSION, 'canonical-model', + ], + ]; + foreach ($cases as $label => [$env, $header, $credential, $version, $model]) { + $recorder = scripted(json_response(thread_reply('msg_first')), json_response(thread_reply('msg_second', 'ORCHID-47'))); + [$code, $stdout, $stderr] = with_env([], static fn (): array => run_threads([], $env, $recorder)); + same(0, $code, "$label: exit code (stderr: $stderr)"); + same("ORCHID-47\n", $stdout, "$label: stdout"); + same('', $stderr, "$label: stderr"); + same(2, count($recorder->requests), "$label: requests"); + foreach ($recorder->requests as $turn => $request) { + $headers = headers_of($request); + same($credential, $headers[$header] ?? null, "$label, turn $turn: credential"); + same($version, $headers['anthropic-version'] ?? null, "$label, turn $turn: API version"); + same(THREADS_BETA, $headers['anthropic-beta'] ?? null, "$label, turn $turn: beta"); + same($model, body_of($recorder, $turn)['model'], "$label, turn $turn: model"); + foreach (['authorization', 'x-api-key', 'api-key'] as $other) { + assert($other === $header || !isset($headers[$other]), "$label, turn $turn: $other must be absent"); + } + } + same('continue', body_of($recorder, 1)['thread']['type'], "$label: the second turn continues the thread"); + } +}); + +test('message threads: a failure shows its cause without any credential', function (): void { + $request = new Request('POST', BASE_URL.'/v1/messages'); + $cases = [ + 'bearer token' => [SAMPLE_ENV, 'entra-test-token'], + 'api key' => [SAMPLE_ENV + ['AUTH_MODE' => 'api_key', 'CLAUDE_API_KEY' => 'sample-key-canary-value'], 'sample-key-canary-value'], + ]; + foreach ($cases as $label => [$env, $secret]) { + $recorder = new Recorder(static fn (RequestInterface $sent, int $call): ResponseInterface => 1 === $call + ? json_response(thread_reply('msg_first')) + : throw new ConnectException("cURL error 7: refused ($secret)", $request)); + [$code, $stdout, $stderr] = with_env([], static fn (): array => run_threads([], $env, $recorder)); + same(1, $code, "$label: exit code"); + same('', $stdout, "$label: stdout"); + assert(str_starts_with($stderr, "Error: APIConnectionException: Anthropic API Connection Error\n caused by: ConnectException: cURL error 7: refused ([redacted])"), "$label: the cause is shown: $stderr"); + assert(!str_contains($stderr, $secret), "$label: the credential must not be printed"); + same(4, count($recorder->requests), "$label: the first turn, then the second turn and the SDK's two retries"); + } +}); + +test('message threads: usage, unknown arguments and configuration errors are reported like main.php', function (): void { + [$code, $stdout, $stderr] = run_threads(['--help'], []); + same(0, $code, 'help exit code'); + same("Usage: php message_threads.php\n", $stdout, 'help output'); + same('', $stderr, 'help stderr'); + + $recorder = new Recorder(); + [$code, $stdout, $stderr] = run_threads(['--stream'], SAMPLE_ENV, $recorder); + same(2, $code, 'unknown argument: exit code'); + same('', $stdout, 'unknown argument: stdout'); + same("Unknown argument: --stream\nUsage: php message_threads.php\n", $stderr, 'unknown argument: stderr'); + same(0, count($recorder->requests), 'unknown argument: requests'); + + $recorder = new Recorder(); + [$code, $stdout, $stderr] = with_env([], static fn (): array => run_threads([], [], $recorder)); + same(1, $code, 'no endpoint: exit code'); + same('', $stdout, 'no endpoint: stdout'); + same(NO_ENDPOINT."\n", $stderr, 'no endpoint: stderr'); + same(0, count($recorder->requests), 'no endpoint: requests'); +}); \ No newline at end of file diff --git a/samples/php/tests/run.php b/samples/php/tests/run.php index 36c1085..1401c8e 100644 --- a/samples/php/tests/run.php +++ b/samples/php/tests/run.php @@ -10,7 +10,7 @@ require __DIR__.'/../vendor/autoload.php'; require __DIR__.'/support.php'; -foreach (['ClientFactoryTest', 'CliTokenProviderTest', 'SampleTest', 'EndToEndTest'] as $file) { +foreach (['ClientFactoryTest', 'CliTokenProviderTest', 'SampleTest', 'MessageThreadsTest', 'EndToEndTest'] as $file) { require __DIR__."/$file.php"; } diff --git a/samples/ruby/README.md b/samples/ruby/README.md index 98f6bd1..a8a3d11 100644 --- a/samples/ruby/README.md +++ b/samples/ruby/README.md @@ -5,6 +5,7 @@ Calls a Claude deployment through the **standard** Anthropic Ruby SDK client (`A | File | Purpose | |---|---| | `main.rb` | Entry point: one Messages call, printed whole or streamed (`--stream`). | +| `message_threads.rb`, `lib/claude_sample/message_threads.rb` | Message Threads entrypoint and example. | | `lib/claude_sample/sample.rb` | Reads the environment, builds the client, prints the text and usage. | | `lib/claude_sample/client_factory.rb` | The generic helper. `ClaudeSample::ClientFactory.create_client` returns the standard client with exactly one explicit credential. It reads no environment variables and imports no cloud-provider code. | | `lib/claude_sample/cli_token_provider.rb` | Token provider for local development: a command-line fallback that runs `az account get-access-token`. | @@ -82,6 +83,16 @@ bundle exec ruby main.rb --stream # the same request, streamed as it is genera Thinking blocks are not printed. A response without any text fails with a message and a non-zero exit status instead of reporting success; so do API errors, credential failures and bad configuration (exit status 1; an unknown argument exits with 2). +## Message threads + +```sh +bundle exec ruby message_threads.rb +``` + +This separate entrypoint uses the same configuration and prints the second reply. The SDK helper adds `anthropic-beta: message-threads-2026-08-12` and handles replay. See the [Threads guide](../message-threads.md). + +`ClaudeSample::MessageThreads.converse(client, model, stdout)` also accepts a standard client built with your own token provider. + ## Authentication **`AUTH_MODE=bearer` is a local-development fallback** (the legacy profile's default; the canonical profile needs it set explicitly). The sample runs `az account get-access-token --scope --output json` (adding `--tenant ` when set) for every token request and sends the returned `accessToken` as `Authorization: Bearer`. The Azure CLI owns token caching and renewal; the sample keeps no cache. The price is one CLI process per HTTP attempt, which takes seconds on a typical machine. diff --git a/samples/ruby/lib/claude_sample/message_threads.rb b/samples/ruby/lib/claude_sample/message_threads.rb new file mode 100644 index 0000000..ce54d3c --- /dev/null +++ b/samples/ruby/lib/claude_sample/message_threads.rb @@ -0,0 +1,54 @@ +# frozen_string_literal: true + +require_relative "sample" + +module ClaudeSample + module MessageThreads + SYSTEM = "Keep replies short." + FIRST_PROMPT = "Remember the code ORCHID-47. Reply with OK." + SECOND_PROMPT = "What code did I ask you to remember? Reply with only the code." + USAGE = "Usage: ruby message_threads.rb\n" + + class << self + # @param argv [Array] command-line arguments + # @param env [Hash{String=>String}] + # @param run_cli [#call, nil] Azure CLI process override (tests) + # @return [Integer] the exit status + def run(argv, env, stdout, stderr, run_cli: nil) + argv.each do |argument| + case argument + when "-h", "--help" + stdout.write(USAGE) + return 0 + else + stderr.write("Unknown argument: #{argument}\n#{USAGE}") + return 2 + end + end + + begin + client, model = Sample.configure(env, run_cli) + converse(client, model, stdout) + 0 + rescue StandardError => e + stderr.write("Error: #{Sample.describe(e)}\n") + 1 + end + end + + # @param client [Anthropic::Client] a standard client, however it was built + # @param model [String] the model or deployment name + # @raise [RuntimeError] if the second reply has no text + def converse(client, model, stdout) + thread = client.beta.messages.thread(model: model, max_tokens: Sample::MAX_TOKENS, system_: SYSTEM) + thread.send_message({role: "user", content: FIRST_PROMPT}) + reply = thread.send_message({role: "user", content: SECOND_PROMPT}) + + texts = reply.content.filter_map { |block| block.text if block.type == :text && !block.text.strip.empty? } + raise Sample.no_text(reply.stop_reason) if texts.empty? + + texts.each { |text| stdout.write("#{text}\n") } + end + end + end +end diff --git a/samples/ruby/lib/claude_sample/sample.rb b/samples/ruby/lib/claude_sample/sample.rb index ba4333e..29dba68 100644 --- a/samples/ruby/lib/claude_sample/sample.rb +++ b/samples/ruby/lib/claude_sample/sample.rb @@ -117,6 +117,17 @@ def configure(env, run_cli = nil) [client, model] end + # The failure message for a response without text. + def no_text(stop_reason) + "No text response (stop_reason=#{stop_reason || "none"}). Increase max_tokens if the response exhausted its budget." + end + + # How the sample reports an error: its own messages as they are, any other error with its class name. + def describe(error) + own = error.instance_of?(ArgumentError) || error.instance_of?(RuntimeError) + own ? error.message : "#{error.class.name.split("::").last}: #{error.message}" + end + private def message(client, model, stdout) @@ -158,15 +169,6 @@ def stream_message(client, model, stdout) stdout.write("\n\n[usage] input=#{input} output=#{output}\n") end - def no_text(stop_reason) - "No text response (stop_reason=#{stop_reason || "none"}). Increase max_tokens if the response exhausted its budget." - end - - def describe(error) - own = error.instance_of?(ArgumentError) || error.instance_of?(RuntimeError) - own ? error.message : "#{error.class.name.split("::").last}: #{error.message}" - end - # The first of names that is set and not empty. def setting(env, *names) names.each do |name| diff --git a/samples/ruby/message_threads.rb b/samples/ruby/message_threads.rb new file mode 100644 index 0000000..0e0ca6b --- /dev/null +++ b/samples/ruby/message_threads.rb @@ -0,0 +1,7 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +require "bundler/setup" +require_relative "lib/claude_sample/message_threads" + +exit(ClaudeSample::MessageThreads.run(ARGV, ENV.to_h, $stdout, $stderr)) diff --git a/samples/ruby/test/message_threads_test.rb b/samples/ruby/test/message_threads_test.rb new file mode 100644 index 0000000..e7b622d --- /dev/null +++ b/samples/ruby/test/message_threads_test.rb @@ -0,0 +1,112 @@ +# frozen_string_literal: true + +require_relative "test_helper" +require "stringio" +require "claude_sample/message_threads" + +class MessageThreadsTest < Minitest::Test + include EnvHelper + + BETA = "message-threads-2026-08-12" + FIRST = {"role" => "user", "content" => ClaudeSample::MessageThreads::FIRST_PROMPT} + SECOND = {"role" => "user", "content" => ClaudeSample::MessageThreads::SECOND_PROMPT} + + def with_replies(*replies) + server = LoopbackServer.new { |_request, count| replies.fetch(count - 1) } + yield server + ensure + server&.close + end + + def client(server) + ClaudeSample::ClientFactory.create_client( + base_url: server.base_url, token_provider: -> { "test-token" }, max_retries: 0 + ) + end + + def response(text = "OK") + LoopbackServer.json_response(message_body(text)) + end + + def failure(status, code) + body = error_body(status == 404 ? "not_found_error" : "invalid_request_error", "canary-error-body") + body["error"]["details"] = {"error_code" => code} + LoopbackServer.json_response(body, status) + end + + def test_create_and_continue_send_only_the_new_turn + with_env do + with_replies(response, response("ORCHID-47")) do |server| + output = StringIO.new + ClaudeSample::MessageThreads.converse(client(server), MODEL, output) + assert_equal "ORCHID-47\n", output.string + assert_equal 2, server.requests.length + server.requests.each do |request| + assert_equal "POST", request.verb + assert_equal "/anthropic/v1/messages", request.path.split("?").first + assert_equal BETA, request.header("anthropic-beta") + assert_equal "Bearer test-token", request.header("authorization") + assert_equal MODEL, request.json["model"] + assert_equal 1024, request.json["max_tokens"] + end + first, second = server.requests.map(&:json) + assert_equal({"type" => "create"}, first["thread"]) + assert_equal "Keep replies short.", first["system"] + assert_equal [FIRST], first["messages"] + assert_equal({"type" => "continue", "previous_message_id" => "msg_test"}, second["thread"]) + assert_equal [SECOND], second["messages"] + refute second.key?("system") + refute second.key?("tools") + end + end + end + + def test_expired_thread_replays_the_whole_conversation + with_env do + with_replies(response, failure(404, "thread_not_found"), response("ORCHID-47")) do |server| + ClaudeSample::MessageThreads.converse(client(server), MODEL, StringIO.new) + assert_equal 3, server.requests.length + replay = server.requests.last.json + assert_equal({"type" => "create"}, replay["thread"]) + assert_equal "Keep replies short.", replay["system"] + assert_equal [FIRST, {"role" => "assistant", "content" => message_body["content"]}, SECOND], replay["messages"] + assert server.requests.all? { |request| request.header("anthropic-beta") == BETA } + end + end + end + + def test_other_errors_do_not_replay_or_continue_unthreaded + [[404, "model_not_found"], [400, "thread_unsupported_request"]].each do |status, code| + with_env do + with_replies(response, failure(status, code)) do |server| + assert_raises(Anthropic::Errors::APIStatusError) do + ClaudeSample::MessageThreads.converse(client(server), MODEL, StringIO.new) + end + assert_equal 2, server.requests.length + end + end + end + end + + def test_blank_or_thinking_only_reply_fails + [[], [{"type" => "text", "text" => " \n "}], [{"type" => "thinking", "thinking" => "hidden", "signature" => "test"}]].each do |content| + body = message_body + body["content"] = content + with_env do + with_replies(response, LoopbackServer.json_response(body)) do |server| + output = StringIO.new + assert_raises(RuntimeError) { ClaudeSample::MessageThreads.converse(client(server), MODEL, output) } + assert_equal "", output.string + end + end + end + end + + def test_usage_and_configuration_errors + output, error = StringIO.new, StringIO.new + assert_equal 0, ClaudeSample::MessageThreads.run(["--help"], {}, output, error) + assert_equal 2, ClaudeSample::MessageThreads.run(["--stream"], {}, output, error) + assert_equal 1, ClaudeSample::MessageThreads.run([], {}, output, error) + assert_includes error.string, "CLAUDE_BASE_URL" + end +end diff --git a/samples/typescript/README.md b/samples/typescript/README.md index d39d494..d153b44 100644 --- a/samples/typescript/README.md +++ b/samples/typescript/README.md @@ -11,14 +11,13 @@ no SDK subclass and no provider-specific SDK package; `createClient` returns a p | `src/token_provider.ts` | Selects one Azure Identity credential and wraps it with `getBearerTokenProvider`. | | `src/sample_client.ts` | Reads the environment and builds the client for the sample. | | `src/main.ts` | Command-line entrypoint. | +| `src/message_threads.ts` | Message Threads entrypoint (`npm run threads`). | | `test/` | Offline tests: the real SDK against loopback mock servers, run with Node's built-in test runner. | ## Requirements Node.js 24 or later. The `.ts` files run directly with Node's built-in type stripping, so there is no build -step. Tested with Node.js 24.22 and 26.13, `@anthropic-ai/sdk` 1.1.0 and `@azure/identity` 4.14.0. The SDK source -this sample relies on (the client's credential and header handling, `middleware`, the error classes and the stream -helper) is unchanged in SDK 1.3.0, but 1.3.0 itself has not been tested. +step. Tested with Node.js 24.22, `@anthropic-ai/sdk` 1.4.0 and `@azure/identity` 4.14.0. ## Run @@ -53,6 +52,14 @@ The command exits 0 only when the reply contains text. A reply with only thinkin configuration problem or any request error exits nonzero. Errors report the HTTP status and error type, never the credential, the endpoint, the model name or the response body. +## Message threads + +```powershell +npm run threads +``` + +The separate `src/message_threads.ts` example uses the same configuration and prints the second reply. The SDK helper adds `anthropic-beta: message-threads-2026-08-12` and handles replay. See the [Threads guide](../message-threads.md). + ## Configuration The sample reads one of two variable families and never mixes them, so a URL, a model and a key from different diff --git a/samples/typescript/package-lock.json b/samples/typescript/package-lock.json index e8341be..9d47a31 100644 --- a/samples/typescript/package-lock.json +++ b/samples/typescript/package-lock.json @@ -8,7 +8,7 @@ "name": "anthropic-explicit-auth-sample", "version": "0.0.0", "dependencies": { - "@anthropic-ai/sdk": "1.1.0", + "@anthropic-ai/sdk": "1.4.0", "@azure/identity": "4.14.0" }, "devDependencies": { @@ -20,9 +20,9 @@ } }, "node_modules/@anthropic-ai/sdk": { - "version": "1.1.0", - "resolved": "https://registry.npmjs.org/@anthropic-ai/sdk/-/sdk-1.1.0.tgz", - "integrity": "sha512-Op/fKMsfVwFCfObc87leLOFlORE0RjOvLzRzPCWWLI7Ww6bobpKR6YmYC8ZYgulRh+m2a/3/61VUXoWHFtCXIw==", + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/@anthropic-ai/sdk/-/sdk-1.4.0.tgz", + "integrity": "sha512-tyuibnhQL57kLOx5oomY4Ld7jOVOPNC5v3IiyRtR3l+Friv66tI4VbuZYF2NMel/T0WMuQMBFOMKDBUbUh8gPA==", "license": "Apache-2.0", "dependencies": { "@opentelemetry/api": "^1.4.1", diff --git a/samples/typescript/package.json b/samples/typescript/package.json index abbe8c8..a79847d 100644 --- a/samples/typescript/package.json +++ b/samples/typescript/package.json @@ -10,12 +10,13 @@ "scripts": { "build": "tsc -p tsconfig.build.json", "start": "node src/main.ts", + "threads": "node src/message_threads.ts", "typecheck": "tsc --noEmit", "pretest": "npm run typecheck", "test": "node --test --test-timeout=60000 \"test/*.test.ts\"" }, "dependencies": { - "@anthropic-ai/sdk": "1.1.0", + "@anthropic-ai/sdk": "1.4.0", "@azure/identity": "4.14.0" }, "devDependencies": { diff --git a/samples/typescript/src/main.ts b/samples/typescript/src/main.ts index 6972c4c..d62db3d 100644 --- a/samples/typescript/src/main.ts +++ b/samples/typescript/src/main.ts @@ -19,10 +19,10 @@ import { ConfigError } from './config_error.ts'; import { configuredClient, loadSettings, type ClientOverrides, type Environment } from './sample_client.ts'; const DEFAULT_PROMPT = 'What are 3 things to visit in Seattle?'; -const MAX_TOKENS = 1024; +export const MAX_TOKENS = 1024; // Application policy of this sample, not a helper default: the whole call, including SDK retries and // streaming, ends after 120 seconds. The SDK's own per-attempt timeout and retry defaults are untouched. -const TOTAL_TIMEOUT_MS = 120_000; +export const TOTAL_TIMEOUT_MS = 120_000; const USAGE = 'Usage: node src/main.ts [--stream] [prompt...]'; export interface Output { @@ -114,7 +114,7 @@ async function streamReply(client: Anthropic, request: MessageRequest, signal: A return hasText ? 0 : noText(message.stop_reason, io); } -function noText(stopReason: string | null, io: RunIO): number { +export function noText(stopReason: string | null, io: RunIO): number { io.stderr.write(`No text response (stop_reason=${stopReason}). Increase max_tokens if the response exhausted its budget.\n`); return 1; } @@ -128,7 +128,7 @@ const HTTP_HINTS: Array<[(status: number) => boolean, string]> = [ [(status) => status >= 500, 'The service reported an error. Retry later.'], ]; -function describeError(error: unknown, signal: AbortSignal, totalTimeoutMs: number): string { +export function describeError(error: unknown, signal: AbortSignal, totalTimeoutMs: number): string { if (error instanceof ConfigError) return error.message; if (error instanceof ClientAuthError) { const cause = error.cause instanceof Error ? ` Cause: ${error.cause.name}.` : ''; diff --git a/samples/typescript/src/message_threads.ts b/samples/typescript/src/message_threads.ts new file mode 100644 index 0000000..499d3c6 --- /dev/null +++ b/samples/typescript/src/message_threads.ts @@ -0,0 +1,36 @@ +import { MAX_TOKENS, TOTAL_TIMEOUT_MS, describeError, noText, type RunIO, type RunOptions } from './main.ts'; +import { configuredClient, loadSettings, type Environment } from './sample_client.ts'; + +export const FIRST_PROMPT = 'Remember the code ORCHID-47. Reply with OK.'; +export const SECOND_PROMPT = 'What code did I ask you to remember? Reply with only the code.'; +const USAGE = 'Usage: node src/message_threads.ts'; + +export async function run(argv: readonly string[], env: Environment, io: RunIO, options: RunOptions = {}): Promise { + if (argv.length > 0) { + const help = argv.length === 1 && (argv[0] === '--help' || argv[0] === '-h'); + (help ? io.stdout : io.stderr).write(`${USAGE}\n`); + return help ? 0 : 2; + } + const timeoutMs = options.totalTimeoutMs ?? TOTAL_TIMEOUT_MS; + const signal = AbortSignal.timeout(timeoutMs); + try { + const settings = loadSettings(env); + const client = configuredClient(settings, options); + const thread = client.beta.messages.thread({ + model: settings.model, max_tokens: MAX_TOKENS, system: 'Keep replies short.', + }, { signal }); + await thread.send({ role: 'user', content: FIRST_PROMPT }); + const reply = await thread.send({ role: 'user', content: SECOND_PROMPT }); + const texts = reply.content.flatMap((block) => block.type === 'text' && block.text.trim() ? [block.text] : []); + if (texts.length === 0) return noText(reply.stop_reason, io); + for (const text of texts) io.stdout.write(`${text}\n`); + return 0; + } catch (error) { + io.stderr.write(`${describeError(error, signal, timeoutMs)}\n`); + return 1; + } +} + +if (import.meta.main) { + process.exitCode = await run(process.argv.slice(2), process.env, process); +} diff --git a/samples/typescript/test/message_threads.test.ts b/samples/typescript/test/message_threads.test.ts new file mode 100644 index 0000000..8e29491 --- /dev/null +++ b/samples/typescript/test/message_threads.test.ts @@ -0,0 +1,120 @@ +import assert from 'node:assert/strict'; +import { it } from 'node:test'; + +import { FIRST_PROMPT, SECOND_PROMPT, run } from '../src/message_threads.ts'; +import { MESSAGE, THINKING_BLOCK, hang, sendJSON, useCleanEnvironment, useServers } from './helpers.ts'; + +const serve = useServers(); +useCleanEnvironment(); +const BETA = 'message-threads-2026-08-12'; +const first = { role: 'user', content: FIRST_PROMPT }; +const second = { role: 'user', content: SECOND_PROMPT }; + +function output() { + const result = { stdout: '', stderr: '' }; + return { + result, + io: { + stdout: { write: (text: string) => { result.stdout += text; } }, + stderr: { write: (text: string) => { result.stderr += text; } }, + }, + }; +} + +it('creates then continues with only the new message and the beta on both calls', async () => { + const server = await serve((_request, response) => sendJSON(response, 200, { + ...MESSAGE, id: `msg_${server.requests.length}`, + content: server.requests.length === 1 ? MESSAGE.content : [THINKING_BLOCK, { type: 'text', text: 'ORCHID-47' }], + })); + const { io, result } = output(); + const code = await run([], { + CLAUDE_BASE_URL: `${server.origin}/anthropic`, CLAUDE_DEPLOYMENT_NAME: 'test-model', + }, io, { tokenProvider: () => 'test-token', maxRetries: 0 }); + assert.equal(code, 0); + assert.deepEqual(result, { stdout: 'ORCHID-47\n', stderr: '' }); + assert.equal(server.requests.length, 2); + for (const request of server.requests) { + assert.equal(request.method, 'POST'); + assert.equal(request.url.split('?')[0], '/anthropic/v1/messages'); + assert.equal(request.headers['anthropic-beta'], BETA); + assert.equal(request.headers['authorization'], 'Bearer test-token'); + const body = JSON.parse(request.body); + assert.equal(body.model, 'test-model'); + assert.equal(body.max_tokens, 1024); + } + const bodies = server.requests.map((request) => JSON.parse(request.body)); + assert.deepEqual(bodies[0].thread, { type: 'create' }); + assert.equal(bodies[0].system, 'Keep replies short.'); + assert.deepEqual(bodies[0].messages, [first]); + assert.deepEqual(bodies[1].thread, { type: 'continue', previous_message_id: 'msg_1' }); + assert.deepEqual(bodies[1].messages, [second]); + assert.ok(!('system' in bodies[1])); + assert.ok(!('tools' in bodies[1])); +}); + +it('replays the complete conversation only for thread_not_found', async () => { + const server = await serve((_request, response) => { + if (server.requests.length === 2) { + sendJSON(response, 404, { type: 'error', error: { + type: 'not_found_error', message: 'expired', details: { error_code: 'thread_not_found' }, + } }); + } else { + sendJSON(response, 200, MESSAGE); + } + }); + const { io } = output(); + assert.equal(await run([], { + CLAUDE_BASE_URL: server.origin, CLAUDE_DEPLOYMENT_NAME: 'test-model', + }, io, { tokenProvider: () => 'test-token', maxRetries: 0 }), 0); + assert.equal(server.requests.length, 3); + const replay = JSON.parse(server.requests[2]!.body); + assert.deepEqual(replay.thread, { type: 'create' }); + assert.equal(replay.system, 'Keep replies short.'); + assert.deepEqual(replay.messages, [first, { role: 'assistant', content: MESSAGE.content }, second]); + assert.ok(server.requests.every((request) => request.headers['anthropic-beta'] === BETA)); +}); + +it('surfaces unrelated 404s and unsupported requests without unthreaded fallback', async () => { + for (const [status, errorCode] of [[404, 'model_not_found'], [400, 'thread_unsupported_request']] as const) { + const server = await serve((_request, response) => sendJSON(response, + server.requests.length === 1 ? 200 : status, + server.requests.length === 1 ? MESSAGE : { type: 'error', error: { + type: status === 404 ? 'not_found_error' : 'invalid_request_error', + message: 'canary-error-body', details: { error_code: errorCode }, + } })); + const { io, result } = output(); + assert.equal(await run([], { + CLAUDE_BASE_URL: server.origin, CLAUDE_DEPLOYMENT_NAME: 'test-model', + }, io, { tokenProvider: () => 'test-token', maxRetries: 0 }), 1); + assert.equal(server.requests.length, 2); + assert.equal(result.stdout, ''); + assert.ok(result.stderr.includes(`HTTP ${status}`)); + assert.ok(!result.stderr.includes('canary-error-body')); + } +}); + +it('rejects blank and thinking-only replies', async () => { + for (const content of [[], [{ type: 'text', text: ' \n ' }], [THINKING_BLOCK]]) { + const server = await serve((_request, response) => sendJSON(response, 200, { + ...MESSAGE, content: server.requests.length === 1 ? MESSAGE.content : content, + })); + const { io, result } = output(); + assert.equal(await run([], { + CLAUDE_BASE_URL: server.origin, CLAUDE_DEPLOYMENT_NAME: 'test-model', + }, io, { tokenProvider: () => 'test-token', maxRetries: 0 }), 1); + assert.equal(result.stdout, ''); + assert.ok(result.stderr.includes('No text response')); + } +}); + +it('honors the deadline, configuration errors and command usage', async () => { + const server = await serve(hang); + const { io, result } = output(); + assert.equal(await run([], { + CLAUDE_BASE_URL: server.origin, CLAUDE_DEPLOYMENT_NAME: 'test-model', + }, io, { tokenProvider: () => 'test-token', maxRetries: 0, totalTimeoutMs: 50 }), 1); + assert.ok(result.stderr.includes('timed out')); + assert.equal(await run([], {}, output().io), 1); + assert.equal(await run(['--stream'], {}, output().io), 2); + assert.equal(await run(['--help'], {}, output().io), 0); +}); diff --git a/skills/claude-on-foundry/SKILL.md b/skills/claude-on-foundry/SKILL.md index 2d7fc82..77d6833 100644 --- a/skills/claude-on-foundry/SKILL.md +++ b/skills/claude-on-foundry/SKILL.md @@ -224,6 +224,7 @@ The full POSIX parallel-purge snippet lives in [README → Free quota held by so | [`src/hello_claude.py`](../../src/hello_claude.py) | One-shot Messages call (Entra ID) | — | | [`src/hello_claude_token_refresh.py`](../../src/hello_claude_token_refresh.py) | Long-running variant with per-request refresh | use for daemons / notebooks | | [`src/chat_stream.py`](../../src/chat_stream.py) | Streaming multi-turn REPL | `exit` to quit | +| [`src/message_threads.py`](../../src/message_threads.py) | Two-turn Message Threads beta | — | Each `.ps1` has a `.sh` POSIX equivalent next to it. diff --git a/src/message_threads.py b/src/message_threads.py new file mode 100644 index 0000000..5f1f6d8 --- /dev/null +++ b/src/message_threads.py @@ -0,0 +1,53 @@ +"""Two-turn Message Threads beta using the standard SDK helper.""" + +from __future__ import annotations + +import sys + +from anthropic import APIError, APIStatusError, Anthropic +from anthropic.types.beta import BetaMessage + +from sample_client import configured_client + +FIRST_PROMPT = "Remember the code ORCHID-47. Reply with OK." +SECOND_PROMPT = "What code did I ask you to remember? Reply with only the code." + + +def run_threads(client: Anthropic, deployment: str) -> BetaMessage: + thread = client.beta.messages.thread( + model=deployment, max_tokens=1024, system="Keep replies short." + ) + thread.send({"role": "user", "content": FIRST_PROMPT}) + return thread.send({"role": "user", "content": SECOND_PROMPT}) + + +def main() -> int: + try: + with configured_client() as (client, deployment): + message = run_threads(client, deployment) + except ValueError as error: + print(str(error), file=sys.stderr) + return 1 + except APIError as error: + status = f" (status {error.status_code})" if isinstance(error, APIStatusError) else "" + print(f"API request failed: {type(error).__name__}{status}", file=sys.stderr) + return 1 + + texts = [ + block.text for block in message.content + if block.type == "text" and block.text.strip() + ] + if not texts: + print( + f"No text response (stop_reason={message.stop_reason}). " + "Increase max_tokens if the response exhausted its budget.", + file=sys.stderr, + ) + return 1 + for text in texts: + print(text) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/tests/test_message_threads.py b/tests/test_message_threads.py new file mode 100644 index 0000000..343d90b --- /dev/null +++ b/tests/test_message_threads.py @@ -0,0 +1,163 @@ +from __future__ import annotations + +from contextlib import nullcontext, redirect_stderr, redirect_stdout +from copy import deepcopy +import io +import json +import os +from pathlib import Path +import sys +import unittest +from unittest.mock import patch + +from anthropic import APIStatusError +import httpx2 as httpx + +sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src")) +from client_auth import create_client +import message_threads + +BETA = "message-threads-2026-08-12" +MESSAGE = { + "id": "msg_first", "type": "message", "role": "assistant", "model": "test-model", + "content": [{"type": "text", "text": "OK"}], "stop_reason": "end_turn", + "stop_sequence": None, "usage": {"input_tokens": 1, "output_tokens": 1}, +} +FIRST = {"role": "user", "content": message_threads.FIRST_PROMPT} +SECOND = {"role": "user", "content": message_threads.SECOND_PROMPT} + + +def reply(text: str = "ORCHID-47") -> httpx.Response: + body = deepcopy(MESSAGE) + body["id"] = "msg_second" + body["content"] = [{"type": "text", "text": text}] + return httpx.Response(200, json=body) + + +def error(status: int, code: str) -> httpx.Response: + return httpx.Response(status, json={ + "type": "error", + "error": { + "type": "not_found_error" if status == 404 else "invalid_request_error", + "message": "canary-error-body", + "details": {"error_code": code}, + }, + }) + + +class MessageThreadsTests(unittest.TestCase): + def setUp(self) -> None: + environment = patch.dict(os.environ, {}, clear=True) + environment.start() + self.addCleanup(environment.stop) + self.responses = [httpx.Response(200, json=MESSAGE), reply()] + self.requests: list[httpx.Request] = [] + + def client(self): + def respond(request: httpx.Request) -> httpx.Response: + self.requests.append(request) + return self.responses.pop(0) + return create_client( + base_url="https://example.test/anthropic", + token_provider=lambda: "test-token", + transport=httpx.MockTransport(respond), max_retries=0, + ) + + def run_main(self) -> tuple[int, str, str]: + output, stderr = io.StringIO(), io.StringIO() + with ( + self.client() as client, + patch.object(message_threads, "configured_client", return_value=nullcontext((client, "test-model"))), + redirect_stdout(output), redirect_stderr(stderr), + ): + result = message_threads.main() + return result, output.getvalue(), stderr.getvalue() + + def test_create_and_continue_send_only_the_new_turn(self) -> None: + with self.client() as client: + result = message_threads.run_threads(client, "test-model") + self.assertEqual(result.id, "msg_second") + self.assertEqual(len(self.requests), 2) + for request in self.requests: + self.assertEqual(request.method, "POST") + self.assertEqual(request.url.path, "/anthropic/v1/messages") + self.assertEqual(request.headers["anthropic-beta"], BETA) + self.assertEqual(request.headers["authorization"], "Bearer test-token") + body = json.loads(request.content) + self.assertEqual(body["model"], "test-model") + self.assertEqual(body["max_tokens"], 1024) + first, second = [json.loads(request.content) for request in self.requests] + self.assertEqual(first["thread"], {"type": "create"}) + self.assertEqual(first["system"], "Keep replies short.") + self.assertEqual(first["messages"], [FIRST]) + self.assertEqual(second["thread"], {"type": "continue", "previous_message_id": "msg_first"}) + self.assertEqual(second["messages"], [SECOND]) + self.assertNotIn("system", second) + self.assertNotIn("tools", second) + + def test_expired_thread_replays_the_complete_transcript(self) -> None: + self.responses.insert(1, error(404, "thread_not_found")) + with self.client() as client: + result = message_threads.run_threads(client, "test-model") + self.assertEqual(result.id, "msg_second") + self.assertEqual(len(self.requests), 3) + replay = json.loads(self.requests[2].content) + self.assertEqual(replay["thread"], {"type": "create"}) + self.assertEqual(replay["system"], "Keep replies short.") + self.assertEqual(replay["messages"], [ + FIRST, {"role": "assistant", "content": MESSAGE["content"]}, SECOND, + ]) + self.assertTrue(all(request.headers["anthropic-beta"] == BETA for request in self.requests)) + + def test_unrelated_errors_do_not_replay_or_fall_back_unthreaded(self) -> None: + for status, code in ((404, "model_not_found"), (400, "thread_unsupported_request")): + with self.subTest(code=code): + self.requests.clear() + self.responses = [httpx.Response(200, json=MESSAGE), error(status, code)] + with self.client() as client, self.assertRaises(APIStatusError): + message_threads.run_threads(client, "test-model") + self.assertEqual(len(self.requests), 2) + + def test_main_prints_text_not_thinking(self) -> None: + body = deepcopy(MESSAGE) + body["content"] = [ + {"type": "thinking", "thinking": "not-for-display", "signature": "test"}, + {"type": "text", "text": "ORCHID-47"}, + ] + self.responses[1] = httpx.Response(200, json=body) + result, output, stderr = self.run_main() + self.assertEqual((result, output, stderr), (0, "ORCHID-47\n", "")) + + def test_blank_or_thinking_only_reply_is_a_failure(self) -> None: + for content in ([], [{"type": "text", "text": " \n "}], [ + {"type": "thinking", "thinking": "not-for-display", "signature": "test"}, + ]): + with self.subTest(content=content): + body = deepcopy(MESSAGE) + body["content"] = content + self.responses = [httpx.Response(200, json=MESSAGE), httpx.Response(200, json=body)] + result, output, stderr = self.run_main() + self.assertEqual((result, output), (1, "")) + self.assertIn("stop_reason=end_turn", stderr) + self.assertIn("max_tokens", stderr) + self.assertNotIn("not-for-display", stderr) + + def test_api_error_reports_status_without_response_body(self) -> None: + self.responses = [error(400, "invalid_request")] + result, output, stderr = self.run_main() + self.assertEqual((result, output), (1, "")) + self.assertIn("BadRequestError (status 400)", stderr) + self.assertNotIn("canary-error-body", stderr) + + def test_configuration_error_is_visible(self) -> None: + stderr = io.StringIO() + with ( + patch.object(message_threads, "configured_client", side_effect=ValueError("Set CLAUDE_BASE_URL.")), + redirect_stderr(stderr), + ): + self.assertEqual(message_threads.main(), 1) + self.assertIn("Set CLAUDE_BASE_URL.", stderr.getvalue()) + + +if __name__ == "__main__": + unittest.main()