An agent that only reads text is limited. Much of real work lives in screenshots, scanned forms, product photos, and the screens of apps that have no API. Those jobs need a model that can see the picture and act on it, and the bill has to stay reasonable when the agent runs hundreds of times a day.
GPT-6.1 Terra is now generally available in Microsoft Foundry. Microsoft positions it for high-volume visual and screen-based work, and it says Terra is quick and efficient for day-to-day professional tasks.
Sources for the facts in this post: the Foundry announcement and the Responses API documentation. The pricing is Microsoft's published table, and I haven't checked it against your region or contract.
The full sample is on GitHub: GPT-6-1-Terra-CSharp-Sample.
What Terra is good at
Microsoft lists four core strengths. For a C# developer, each one maps to a concrete kind of work.
- Stronger vision. Better visual reasoning picks out the details in product photos, technical drawings, floor plans, and application screens.
- Faster, more precise computer use. The model pairs what it sees with quick, accurate actions in browsers, desktop software, and apps.
- Clear writing. It summarizes what it finds in plain language and drafts emails and proposals.
- Large context. A 1.05M-token context window, with up to 922K input tokens and 128K output tokens. It takes text and image input.
Microsoft's own examples are a good shortlist: reviewing campaign assets for cropping and text placement, matching supplier product images to catalog entries, finding a moment in a video, and completing forms. Each one starts with a picture and ends in software.
One note on video: the model takes text and images, not video files. To find a moment in a video, your app pulls frames at an interval, sends them as images, and keeps track of each frame's timestamp itself.
Where it fits, and where it doesn't
Terra is not the model for the hardest reasoning. Microsoft says it complements GPT-6 Astra: Astra plans open-ended, multi-step work, and Terra handles the high-volume visual and on-screen tasks inside that plan, at a lower price point.
| Use Terra for | Keep another model for |
|---|---|
| Reading screenshots, scans, and product photos | Open-ended planning across many steps |
| Form filling and routine email or proposal drafts | Long reasoning on hard technical problems |
| Retail catalog checks and listing updates | Decisions that need a strong, explained rationale |
| Finding a moment in video frames and acting on it | A fast, typed answer with no generated text (use the Decisions API) |
For the last row, Microsoft suggests pairing the two. Terra handles the visual work, and the Decisions API makes the quick call on what happens next. That is the same split I described for the Decisions API.
The developer controls
Three controls matter for a .NET app.
- Reasoning effort. You can set it, including
nonefor latency-sensitive calls. The sample useslow. - Verbosity. It matches the length of the response to the task. The sample uses
low. - Interim updates. When your orchestration layer supports it, Terra can send messages to the user while it keeps working on a long task.
The sample sends reasoning.effort and text.verbosity in the request body. Check the exact names and allowed values in the Responses API reference before you rely on them, because the parts I checked did not show the full parameter list.
The API is the Responses API
Terra works with the Foundry APIs you already use, through the Responses API, with no new SDK or schema changes. That matters for C#: you do not need a Terra-specific package. A plain HttpClient call is enough, which is what the sample does.
You can use the OpenAI .NET SDK instead. Microsoft's Responses API docs show it with the OpenAI and Azure.Identity packages and a ResponsesClient pointed at your resource's /openai/v1 endpoint, and it gives you typed requests and responses instead of hand-built JSON. Its Responses types are marked experimental, so the docs' examples suppress the OPENAI001 warning. I kept HttpClient here because it shows exactly what goes over the wire, which helps when you're debugging a tool loop.
The request goes to:
POST https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/responses The model field takes your deployment name, not the model name.
Authentication has two options, and the sample supports both:
- API key: sent in the
api-keyheader. - Microsoft Entra ID: a bearer token for the scope
https://ai.azure.com/.default, fromDefaultAzureCredential. Locally,az loginis enough.
If you set an API key, the sample uses it. If you don't, the sample signs in with Entra ID. Use Entra ID for anything that runs in production. When the app runs in Azure, DefaultAzureCredential picks up its managed identity, so there is no secret to store at all.
Use the Responses API for tool calling too. Microsoft's reasoning models guide recommends it whenever you combine reasoning with function tools, because it returns reasoning items you can pass back between turns. It also documents a trap on the GPT-5.6 models: a Chat Completions request that sends tools fails unless reasoning_effort is none, because those models default to medium. The guide doesn't list that limit for Terra, but if you're moving an existing Chat Completions tool loop to a newer reasoning model, test the tool calls before you switch.
What it costs
Microsoft's published prices in USD per million tokens:
| Deployment | Context | Input | Cached input | Output |
|---|---|---|---|---|
| Global Standard | Short | $1.00 | $0.05 | $5.00 |
| Global Standard | Long | $2.00 | $0.10 | $7.50 |
| Data Zone Standard (US) | Short | $1.10 | $0.055 | $5.50 |
| Data Zone Standard (EU) | Short | $1.20 | $0.06 | $6.00 |
| Data Zone Standard (APAC) | Short | $1.20 | $0.06 | $6.00 |
The announcement lists Data Zone Standard for US, EU and APAC, so you can keep data in a region without a separate model. On short context, output tokens cost about five times input tokens, so a short answer is cheap and a long generated report is not. Reasoning tokens count as output, which is one more reason to set reasoning effort on purpose.
Watch the line between short and long context. On OpenAI's own API, a request with more than 272K input tokens is billed at the long-context rate for the whole request, not just the tokens past the line. One token over reprices the entire call. I haven't found that threshold in Microsoft's pricing for Foundry, so check your bill before you assume it works the same way. If an agent keeps adding screenshots to a long conversation, trim the history before it crosses the line.
Calling Terra from C
The sample is one console app with two examples:
- Read a screenshot. Terra looks at a PNG of a web form and says what the user is trying to do, what blocks them, and which control to use next.
- Review a PDF invoice. Terra reads the invoice, calls a C# function to check the supplier, and returns a structured result that deserializes into a C# record.
Both print token usage and elapsed time. The sample files, expense-form.png and invoice.pdf, are in the GitHub repo. Contoso, Fabrikam and everything on them are made up.
To skip the setup below, clone it and go straight to the settings:
git clone https://github.com/taswar/GPT-6-1-Terra-CSharp-Sample.git cd GPT-6-1-Terra-CSharp-Sample To build it from scratch instead, create the project on .NET 10 and add the packages:
dotnet new console -n GPT-6-1-Terra-CSharp-Sample cd GPT-6-1-Terra-CSharp-Sample dotnet add package Azure.Identity dotnet add package Microsoft.Extensions.Configuration.UserSecrets dotnet add package Microsoft.Extensions.Configuration.EnvironmentVariables dotnet user-secrets init Store the settings with user secrets. The endpoint is the base URL with no path. The API key line is optional. Leave it out to use Entra ID:
dotnet user-secrets set "AZURE_OPENAI_ENDPOINT" "https://YOUR-RESOURCE-NAME.openai.azure.com" dotnet user-secrets set "AZURE_OPENAI_DEPLOYMENT" "gpt-6.1-terra" dotnet user-secrets set "AZURE_OPENAI_API_KEY" "your-key-here" For Entra ID, run az login and make sure your account has access to call the model on the resource. Check the role name in the Foundry access settings for your resource. Then check what the app will read:
dotnet user-secrets list That command prints your API key in plain text, so don't paste its output into an issue, a log, or a screenshot.
The project file is GPT-6-1-Terra-CSharp-Sample.csproj. Keep the UserSecretsId that dotnet user-secrets init wrote into your own project file. If you copy someone else's, your secrets won't be found:
<Project Sdk="Microsoft.NET.Sdk"> <PropertyGroup> <OutputType>Exe</OutputType> <TargetFramework>net10.0</TargetFramework> <ImplicitUsings>enable</ImplicitUsings> <Nullable>enable</Nullable> <UserSecretsId>YOUR-USER-SECRETS-ID</UserSecretsId> </PropertyGroup> <ItemGroup> <PackageReference Include="Azure.Identity" Version="1.21.0" /> <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="10.0.12" /> <PackageReference Include="Microsoft.Extensions.Configuration.UserSecrets" Version="10.0.12" /> </ItemGroup> </Project> Then Program.cs:
using System.Diagnostics; using System.Net.Http.Headers; using System.Text; using System.Text.Json; using System.Text.Json.Nodes; using Azure.Core; using Azure.Identity; using Microsoft.Extensions.Configuration; // Pick the example from the command line: dotnet run -- 1, dotnet run -- 2, or dotnet run -- all. var choice = (args.Length > 0 ? args[0] : "all").TrimStart('-').ToLowerInvariant(); if (choice is not ("1" or "2" or "all")) { Console.WriteLine(""" Usage: dotnet run -- [1 | 2 | all] 1 Read a screenshot (expense-form.png) 2 Review a PDF invoice with a tool call and structured output (invoice.pdf) all Run both (the default) """); return 1; } var config = new ConfigurationBuilder() .AddUserSecrets<Program>() .AddEnvironmentVariables() .Build(); var endpoint = (config["AZURE_OPENAI_ENDPOINT"] ?? throw new InvalidOperationException( "Set AZURE_OPENAI_ENDPOINT with dotnet user-secrets, for example https://YOUR-RESOURCE-NAME.openai.azure.com")) .TrimEnd('/'); var deployment = config["AZURE_OPENAI_DEPLOYMENT"] ?? "gpt-6.1-terra"; // The API key is optional. Without one, the app signs in with Entra ID through az login. var apiKey = config["AZURE_OPENAI_API_KEY"]; using var http = new HttpClient { Timeout = TimeSpan.FromSeconds(120) }; using var cts = new CancellationTokenSource(TimeSpan.FromMinutes(5)); var terra = new TerraClient(http, endpoint, apiKey, new DefaultAzureCredential(), deployment); if (choice is "1" or "all") { await ScreenshotExample.RunAsync(terra, "expense-form.png", cts.Token); } if (choice is "2" or "all") { await InvoiceAgentExample.RunAsync(terra, "invoice.pdf", cts.Token); } return 0; // Example 1: image analysis. Terra reads a screenshot of a web form and says what blocks the user. static class ScreenshotExample { public static async Task RunAsync(TerraClient terra, string imagePath, CancellationToken cancellationToken) { Console.WriteLine("=== Example 1: read a screenshot ==="); if (!File.Exists(imagePath)) { throw new FileNotFoundException("Run from the project folder, where the sample files are.", imagePath); } var imageBase64 = Convert.ToBase64String(await File.ReadAllBytesAsync(imagePath, cancellationToken)); var body = new JsonObject { ["model"] = terra.Deployment, ["input"] = new JsonArray { new JsonObject { ["role"] = "user", ["content"] = new JsonArray { new JsonObject { ["type"] = "input_text", ["text"] = """ This is a screenshot of a web app. In four short lines: 1. What is the user trying to do? 2. Which values are already filled in? 3. What is stopping them from submitting? 4. Which control should they use next? Give its exact label. """ }, new JsonObject { ["type"] = "input_image", ["image_url"] = $"data:{MimeTypeFor(imagePath)};base64,{imageBase64}", // high reads small text such as field hints; low is cheaper for a rough look. ["detail"] = "high" } } } }, ["reasoning"] = new JsonObject { ["effort"] = "low" }, ["text"] = new JsonObject { ["verbosity"] = "low" } }; var stopwatch = Stopwatch.StartNew(); var usage = new Usage(); using var response = await terra.PostAsync(body, cancellationToken); stopwatch.Stop(); usage.Add(response.RootElement); Console.WriteLine(TerraClient.ReadOutputText(response.RootElement)); Console.WriteLine(); Console.WriteLine($"[terra] {usage} elapsed={stopwatch.Elapsed.TotalSeconds:0.0}s"); Console.WriteLine(); } // The data URL needs the image's real type. PNG, JPEG, WebP and non-animated GIF are supported. static string MimeTypeFor(string path) => Path.GetExtension(path).ToLowerInvariant() switch { ".png" => "image/png", ".jpg" or ".jpeg" => "image/jpeg", ".webp" => "image/webp", ".gif" => "image/gif", _ => throw new NotSupportedException($"Unsupported image type: {path}") }; } // Example 2: an invoice agent. PDF input, one tool call, and a structured result in a C# record. static class InvoiceAgentExample { const string Instructions = """ You review supplier invoices for accounts payable. Read the attached invoice. Always call check_supplier with the supplier name exactly as printed. Set requires_approval to true if the total is over 5000, or if the supplier is not on file or not active. List anything a reviewer should look at in issues, such as math that doesn't add up or a missing PO number. Use an empty list when there is nothing to flag. """; public static async Task RunAsync(TerraClient terra, string pdfPath, CancellationToken cancellationToken) { Console.WriteLine("=== Example 2: review a PDF invoice ==="); if (!File.Exists(pdfPath)) { throw new FileNotFoundException("Run from the project folder, where the sample files are.", pdfPath); } var pdfBase64 = Convert.ToBase64String(await File.ReadAllBytesAsync(pdfPath, cancellationToken)); var body = new JsonObject { ["model"] = terra.Deployment, ["instructions"] = Instructions, ["input"] = new JsonArray { new JsonObject { ["role"] = "user", ["content"] = new JsonArray { new JsonObject { ["type"] = "input_file", ["filename"] = Path.GetFileName(pdfPath), ["file_data"] = $"data:application/pdf;base64,{pdfBase64}" }, new JsonObject { ["type"] = "input_text", ["text"] = "Review this invoice." } } } } }; AddToolsAndFormat(body); var stopwatch = Stopwatch.StartNew(); var usage = new Usage(); var response = await terra.PostAsync(body, cancellationToken); usage.Add(response.RootElement); // The tool loop: run every function call Terra asks for, then send the results back. // previous_response_id chains the turns on the service, including the reasoning items. for (var round = 1; round <= 5; round++) { var outputs = await RunToolCallsAsync(response.RootElement); if (outputs.Count == 0) { break; } var next = new JsonObject { ["model"] = terra.Deployment, ["previous_response_id"] = response.RootElement.GetProperty("id").GetString(), ["input"] = outputs }; AddToolsAndFormat(next); response.Dispose(); response = await terra.PostAsync(next, cancellationToken); usage.Add(response.RootElement); } stopwatch.Stop(); var json = TerraClient.ReadOutputText(response.RootElement); response.Dispose(); var review = JsonSerializer.Deserialize<InvoiceReview>(json, new JsonSerializerOptions { PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseLower }) ?? throw new InvalidOperationException($"The model returned no invoice review: {json}"); Console.WriteLine(); Console.WriteLine($"Supplier: {review.SupplierName} (on file: {review.SupplierOnFile})"); Console.WriteLine($"Invoice: {review.InvoiceNumber}, dated {review.InvoiceDate}, PO {review.PoNumber}"); Console.WriteLine($"Total: {review.Total:N2} {review.Currency}"); Console.WriteLine($"Needs approval: {review.RequiresApproval}"); foreach (var issue in review.Issues) { Console.WriteLine($"Issue: {issue}"); } Console.WriteLine(); Console.WriteLine($"[terra] {usage} elapsed={stopwatch.Elapsed.TotalSeconds:0.0}s"); } // Runs each function_call in the response and returns the function_call_output items to send back. static async Task<JsonArray> RunToolCallsAsync(JsonElement root) { var outputs = new JsonArray(); foreach (var call in root.GetProperty("output").EnumerateArray() .Where(item => item.GetProperty("type").GetString() == "function_call")) { var name = call.GetProperty("name").GetString(); var arguments = JsonNode.Parse(call.GetProperty("arguments").GetString() ?? "{}")!; Console.WriteLine($"[tool] {name}({arguments.ToJsonString()})"); var result = name switch { "check_supplier" => await CheckSupplierAsync(arguments["supplier_name"]?.GetValue<string>() ?? ""), _ => $$"""{"error": "Unknown tool {{name}}"}""" }; Console.WriteLine($"[tool] -> {result}"); outputs.Add(new JsonObject { ["type"] = "function_call_output", ["call_id"] = call.GetProperty("call_id").GetString(), ["output"] = result }); } return outputs; } // A stand-in for your ERP or vendor master. Replace it with a real lookup. static Task<string> CheckSupplierAsync(string supplierName) { var suppliers = new Dictionary<string, (string Id, ...