Skip to content
MfGo

Microsoft Agent Framework (Go) — Providers

Every model provider in the Go SDK: OpenAI Responses and Chat Completions, OpenAI-compatible servers, Azure OpenAI, Microsoft Foundry model deployments and server-side agents, Anthropic (including Claude on Bedrock, Vertex AI and Foundry), Google Gemini and Vertex AI, the GitHub Copilot SDK, embeddings, credentials, per-run native parameters and writing your own provider.

In the Go SDK a provider is a constructor that returns an ordinary *agent.Agent. There is no separate chat-client type to wrap: openaiprovider.NewAgent, anthropicprovider.NewAgent and the rest each take a client from the vendor’s own Go SDK plus an AgentConfig, and hand back the same agent type. Everything else in the framework (sessions, tools, middleware, context providers, workflows) works with any of them, so changing provider changes one constructor.

This page goes through each provider: how to construct it, which credentials and environment variables it reads, what it sends on the wire, and what it does not support. The comprehensive guide covers runs, streaming and structured output; tools covers function tools and hosted tools in detail.

Every program below compiles with go vet and go build against github.com/microsoft/agent-framework-go v0.3.1 (Go 1.26). The OpenAI (the stand-in answers background requests inline), OpenAI-compatible, Anthropic, Gemini, embedding and custom-provider programs were also run against a local stand-in for each wire API, reached through the vendor SDKs’ base-URL environment variables. The Azure OpenAI program was run with an API key against an HTTPS stand-in. The Foundry behaviour described here (URLs, token audience, headers, session pinning) was checked with a stub credential against the same stand-in, but the Foundry program itself, and the Bedrock, Vertex AI and Copilot programs, were only compiled.

ProviderConstructorClient it takesWire APIConversation historyHosted toolsStructured output
OpenAI Responsesopenaiprovider.NewAgent, NewResponsesAgentopenai.Client (github.com/openai/openai-go/v3)POST /responsesservice-side by default, local with DisableStoreOutputweb search, file search, code interpreter, hosted MCPtext.format JSON schema
OpenAI Chat Completionsopenaiprovider.NewChatCompletionsAgentopenai.ClientPOST /chat/completionslocal (in the session)web search (web_search_options)response_format JSON schema
OpenAI-compatible serverNewChatCompletionsAgent + option.WithBaseURLopenai.Client/chat/completionslocaldepends on the serverdepends on the server
Azure OpenAIeither OpenAI constructoropenai.Client + azure.WithEndpoint and azure.WithTokenCredential or azure.WithAPIKey/openai/responses or /openai/deployments/{d}/chat/completionsas OpenAIas OpenAIas OpenAI
Microsoft Foundryfoundryprovider.NewAgentbuilt for you from the project endpoint and an azcore.TokenCredential{project}/openai/v1/responses, or the agent’s own endpointservice-side by defaultas OpenAI Responsesas OpenAI Responses
Anthropicanthropicprovider.NewAgentanthropic.Client (github.com/anthropics/anthropic-sdk-go)POST /v1/messageslocalweb search, code executionoutput_config.format
Google Geminigeminiprovider.NewAgent*genai.Client (google.golang.org/genai)generateContent / streamGenerateContentlocalGoogle Search, code execution, file searchresponseJsonSchema
GitHub Copilotcopilotprovider.NewAgent*copilot.Client (github.com/github/copilot-sdk/go)the Copilot CLI over JSON-RPCin the Copilot sessionCopilot’s own toolsnot supported
Remote A2A agenta2aprovider.NewAgent...an A2A clientA2A JSON-RPC or HTTP+JSONon the remote agentn/an/a

A rough guide to choosing:

  • OpenAI or Azure OpenAI, new code: the Responses constructors. They support every hosted tool, return reasoning summaries, can run in the background, and by default keep the conversation on the service so a long session does not resend its history.
  • Any server that claims OpenAI compatibility (Ollama, vLLM, LM Studio, LiteLLM, OpenRouter): NewChatCompletionsAgent with a base URL. Few of them implement the Responses API.
  • Microsoft Foundry projects: foundryprovider.NewAgent. It is the Responses agent with Foundry’s URL, audience and extra headers already set, and it can also call an agent that already exists in the project.
  • Claude: anthropicprovider.NewAgent. The same constructor serves Claude on Amazon Bedrock, Google Vertex AI and Microsoft Foundry, because those are options on the Anthropic client.
  • Gemini: geminiprovider.NewAgent, for both the Gemini API and Vertex AI.

There is no dedicated Ollama, Amazon Bedrock (Converse), Mistral or Foundry Local provider in v0.3.1. Use the OpenAI-compatible route where the server offers one. Calling a remote A2A agent is covered on the hosting and A2A page.

Each provider package has its own AgentConfig, and each one embeds agent.Config. The embedded fields (Name, Description, Tools, Middlewares, FunctionMiddlewares, ContextProviders, HistoryProvider, Logger, RunOptions and the rest) are set the same way whatever the provider. The provider-specific fields are few:

FieldOpenAIFoundryAnthropicGeminiCopilot
Modelmodel ID, or Azure deployment namethe target argument insteadmodel IDmodel IDset in SessionConfig
Instructionsyesyes (ignored for ServerAgent)yesyesappended to the Copilot system message
ToolAutoCall *toolautocall.Configyesyesyesyesno (Copilot runs tools itself)
DisableStoreOutputResponses onlyyesnonono
ProviderNameyes, default "openai"fixed to "microsoft.foundry"fixed to "anthropic"fixed to "gcp.gemini"fixed to "copilot"
OpenAIOptionsnoper-agent OpenAI client optionsnonono
SessionConfig *copilot.SessionConfignonononoyes

Instructions is turned into an agent.WithInstructions run option and prepended to RunOptions, so instructions passed per run are added to it rather than replacing it. All providers join multiple instruction values with a newline.

The OpenAI, Foundry, Anthropic and Gemini providers install the toolautocall middleware, which runs function tools and loops until the model stops asking for them; ToolAutoCall tunes it. When the field is nil the defaults apply (40 rounds, three consecutive failing rounds, serial calls), and the agent’s Logger and LogSensitiveData are passed through. A non-nil ToolAutoCall replaces that whole configuration, so set Logger on it yourself if you want tool logs. The tools page has the details.

Each provider also has one escape hatch, a run option that carries the vendor SDK’s own request type. Anything the framework does not map can be set there:

ProviderRun optionType
OpenAI Responses, Foundryopenaiprovider.ResponsesNewParams(p)responses.ResponseNewParams
OpenAI Chat Completionsopenaiprovider.ChatCompletionNewParams(p)openai.ChatCompletionNewParams
Anthropicanthropicprovider.MessageNewParams(p)anthropic.MessageNewParams
Geminigeminiprovider.GenerateContentConfig(c)genai.GenerateContentConfig

The framework starts from the struct you pass and fills in what it owns: messages, tools, tool choice, instructions, the response format, and the model when yours is empty. A Model set in the native parameters wins over AgentConfig.Model (Gemini has no model field in GenerateContentConfig, so there it is always AgentConfig.Model). Put a native option in AgentConfig.RunOptions to apply it to every run, or pass it to one run. Single-valued options are looked up from the end of the option list, and agent-level RunOptions are prepended to each run’s options, so a native-parameters option passed to a run replaces the agent-level one entirely. The two structs are not merged.

openaiprovider.NewAgent currently calls NewResponsesAgent; the package documents that the API behind NewAgent may change, so call NewResponsesAgent when you depend on Responses behaviour. openai.NewClient() reads OPENAI_API_KEY, OPENAI_BASE_URL, OPENAI_ORG_ID and OPENAI_PROJECT_ID from the environment; pass option.WithAPIKey and friends to set them in code.

package main
import (
"context"
"fmt"
"log"
"github.com/microsoft/agent-framework-go/agent"
"github.com/microsoft/agent-framework-go/message"
"github.com/microsoft/agent-framework-go/provider/openaiprovider"
"github.com/openai/openai-go/v3"
)
func main() {
ctx := context.Background()
// openai.NewClient reads OPENAI_API_KEY (and OPENAI_BASE_URL, if set).
a := openaiprovider.NewResponsesAgent(openai.NewClient(), openaiprovider.AgentConfig{
Model: "gpt-6.1-sol",
Instructions: "You are a concise assistant.",
Config: agent.Config{Name: "Helper"},
})
session, err := a.CreateSession(ctx)
if err != nil {
log.Fatal(err)
}
resp, err := a.RunText(ctx, "Name a prime number.", agent.WithSession(session)).Collect()
if err != nil {
log.Fatal(err)
}
fmt.Println(resp)
// The service stored the response; the session now holds its ID.
fmt.Println("service ID:", session.ServiceID())
fmt.Println("response ID:", resp.ID, "finish reason:", resp.FinishReason)
usage := resp.Usage()
fmt.Printf("tokens: in=%d out=%d\n", usage.InputTokenCount, usage.OutputTokenCount)
// Streaming: each update carries part of the text.
for update, err := range a.RunText(ctx, "And another?", agent.WithSession(session), agent.Stream(true)) {
if err != nil {
log.Fatal(err)
}
for _, c := range update.Contents {
if t, ok := c.(*message.TextContent); ok {
fmt.Print(t.Text)
}
}
}
fmt.Println()
}

What the agent sends, per run:

Framework inputResponses request field
AgentConfig.Model, unless the native params set onemodel
Instructions and every agent.WithInstructionsinstructions, joined with newlines
messages (history, context, your input)input items
function toolstools[] of type function, with the tool’s JSON schema as parameters
agent.WithToolModetool_choice (auto, none, required, or a named function)
agent.WithStructuredOutput / WithResponseFormattext.format of type json_schema
session service ID starting conv_conversation
any other session service IDprevious_response_id
agent.AllowBackgroundResponses(true)background: true
DisableStoreOutput: truestore: false, plus include: ["reasoning.encrypted_content"]
agent.Stream(true)stream: true

By default the Responses API stores each response, and the agent records the response ID in the session as its service ID. The next run on that session sends only the new message with previous_response_id, not the whole history. With DisableStoreOutput: true the request says store: false, the session gets no service ID, and the agent keeps the transcript itself in the session through its history provider. That keeps the whole conversation local and portable, at the cost of resending it on every turn. Sessions and memory explains both modes and how to use an OpenAI Conversations object instead.

When output storage is off, the agent also asks for reasoning.encrypted_content, so reasoning items from a reasoning model can be sent back on the next turn without the service holding them. Pass openaiprovider.ResponsesIncludeReasoningEncryptedContent(false) to stop that, for example for a model that rejects the include. Setting Store in ResponsesNewParams overrides DisableStoreOutput in either direction.

Reasoning effort and summaries are set through the native parameters. Summaries come back as *message.TextReasoningContent, separate from the answer text, and reasoning tokens are counted in UsageDetails.ReasoningTokenCount:

package main
import (
"context"
"fmt"
"log"
"github.com/microsoft/agent-framework-go/message"
"github.com/microsoft/agent-framework-go/provider/openaiprovider"
"github.com/openai/openai-go/v3"
"github.com/openai/openai-go/v3/responses"
"github.com/openai/openai-go/v3/shared"
)
func main() {
a := openaiprovider.NewResponsesAgent(openai.NewClient(), openaiprovider.AgentConfig{
Model: "gpt-6.1-sol",
Instructions: "Think carefully, then answer in one sentence.",
})
reasoning := openaiprovider.ResponsesNewParams(responses.ResponseNewParams{
Reasoning: shared.ReasoningParam{
Effort: shared.ReasoningEffortMedium,
Summary: shared.ReasoningSummaryAuto,
},
MaxOutputTokens: openai.Int(2000),
})
resp, err := a.RunText(context.Background(),
"A train covers 180 miles at 60 mph. How long does it take?", reasoning).Collect()
if err != nil {
log.Fatal(err)
}
for c := range resp.Contents() {
if r, ok := c.(*message.TextReasoningContent); ok && r.Text != "" {
fmt.Println("[reasoning]", r.Text)
}
}
fmt.Println(resp)
fmt.Println("reasoning tokens:", resp.Usage().ReasoningTokenCount)
}

NewChatCompletionsAgent takes the same client and the same AgentConfig, but talks to /chat/completions. Instructions become a leading system message. History is always local: Chat Completions has no stored-response concept, DisableStoreOutput is ignored, and the session carries the transcript. Native parameters go through ChatCompletionNewParams:

package main
import (
"context"
"fmt"
"log"
"github.com/microsoft/agent-framework-go/agent"
"github.com/microsoft/agent-framework-go/provider/openaiprovider"
"github.com/openai/openai-go/v3"
)
func main() {
ctx := context.Background()
a := openaiprovider.NewChatCompletionsAgent(openai.NewClient(), openaiprovider.AgentConfig{
Model: "gpt-6-luna",
Instructions: "Answer in British English.",
Config: agent.Config{
Name: "Chat",
// Applied to every run of this agent.
RunOptions: []agent.Option{
openaiprovider.ChatCompletionNewParams(openai.ChatCompletionNewParams{
Temperature: openai.Float(0.2),
Seed: openai.Int(7),
}),
},
},
})
session, err := a.CreateSession(ctx)
if err != nil {
log.Fatal(err)
}
for _, q := range []string{"My name is Ada.", "What is my name?"} {
resp, err := a.RunText(ctx, q, agent.WithSession(session)).Collect()
if err != nil {
log.Fatal(err)
}
fmt.Println(resp)
}
// No service ID: the history lives in the session.
fmt.Printf("service ID: %q\n", session.ServiceID())
}

A long reasoning task can outlast an HTTP request. With agent.AllowBackgroundResponses(true) the Responses API runs it in the background: a non-streaming run returns at once with resp.ContinuationToken set, and you poll by running again with agent.WithContinuationToken(token) and no messages until the token comes back empty. A streaming run streams as usual, and each update carries a token, so an interrupted stream can be resumed from the last one. Background runs require a session; without one the run fails with “a session must be provided when AllowBackgroundResponses is enabled”. Other providers ignore the option and answer inline.

package main
import (
"context"
"fmt"
"log"
"time"
"github.com/microsoft/agent-framework-go/agent"
"github.com/microsoft/agent-framework-go/provider/openaiprovider"
"github.com/openai/openai-go/v3"
)
func main() {
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Minute)
defer cancel()
a := openaiprovider.NewResponsesAgent(openai.NewClient(), openaiprovider.AgentConfig{
Model: "gpt-6-astra",
Instructions: "You are a thorough research assistant.",
})
session, err := a.CreateSession(ctx)
if err != nil {
log.Fatal(err)
}
resp, err := a.RunText(ctx, "Compare three approaches to rate limiting, with trade-offs.",
agent.WithSession(session), agent.AllowBackgroundResponses(true)).Collect()
if err != nil {
log.Fatal(err)
}
for resp.ContinuationToken != "" {
select {
case <-ctx.Done():
log.Fatal(ctx.Err())
case <-time.After(3 * time.Second):
}
// Polls carry the token and no messages.
resp, err = a.Run(ctx, nil, agent.WithSession(session), agent.WithContinuationToken(resp.ContinuationToken)).Collect()
if err != nil {
log.Fatal(err)
}
}
fmt.Println(resp)
}

Use Responses for OpenAI and Azure OpenAI unless you have a reason not to. It is the only OpenAI path with file search, code interpreter, hosted MCP, background responses and server-held conversations, and reasoning summaries are only returned there. Use Chat Completions for servers that implement nothing else, and when you want the agent, not the service, to hold the transcript without having to remember DisableStoreOutput.

Input other than text goes in message.Content parts on a message passed to RunMessage or Run. message.NewDataContent(bytes, mediaType), NewDataContentFromFile(path, "") and NewDataContentFromReader carry inline data (sent base64-encoded); message.NewURIContent(url, "") references something the service can fetch, inferring the media type from the URL when you pass an empty one. A HostedFileContent refers to a file already uploaded to the provider. Every provider accepts images, inline or by URL. Chat Completions also sends inline audio as input_audio, other inline data (a PDF, say) as a file part, and a HostedFileContent as a file ID, but it silently drops non-image content given by an http(s) URL, since the API has no way to fetch it. Responses and Gemini accept files inline, by URL and by hosted ID. Anthropic accepts images and PDFs inline or by URL, and rejects hosted file IDs with an error.

package main
import (
"context"
"encoding/base64"
"fmt"
"log"
"github.com/microsoft/agent-framework-go/message"
"github.com/microsoft/agent-framework-go/provider/openaiprovider"
"github.com/openai/openai-go/v3"
)
// A 1x1 red PNG, so the sample needs no file on disk.
const redPixel = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8DwHwAFBQIAX8jx0gAAAABJRU5ErkJggg=="
func main() {
png, err := base64.StdEncoding.DecodeString(redPixel)
if err != nil {
log.Fatal(err)
}
inline, err := message.NewDataContent(png, "image/png")
if err != nil {
log.Fatal(err)
}
remote, err := message.NewURIContent("https://go.dev/images/gophers/ladder.svg", "")
if err != nil {
log.Fatal(err)
}
fmt.Println("remote media type:", remote.MediaType)
a := openaiprovider.NewChatCompletionsAgent(openai.NewClient(), openaiprovider.AgentConfig{
Model: "gpt-6.1-sol",
})
msg := message.New(
&message.TextContent{Text: "What colour is this pixel?"},
inline,
)
resp, err := a.RunMessage(context.Background(), msg).Collect()
if err != nil {
log.Fatal(err)
}
fmt.Println(resp)
}

Point the OpenAI client at another server with option.WithBaseURL and use NewChatCompletionsAgent. ProviderName changes the name the agent reports (a.ProviderName()) and the gen_ai.provider.name recorded by the OpenTelemetry middleware; it has no effect on the request. Ollama, for example, serves the OpenAI API under /v1/ and ignores the key:

package main
import (
"cmp"
"context"
"fmt"
"log"
"os"
"github.com/microsoft/agent-framework-go/provider/openaiprovider"
"github.com/openai/openai-go/v3"
"github.com/openai/openai-go/v3/option"
)
func main() {
baseURL := cmp.Or(os.Getenv("LOCAL_LLM_BASE_URL"), "http://localhost:11434/v1/")
client := openai.NewClient(
option.WithBaseURL(baseURL),
option.WithAPIKey("unused"), // Ollama ignores the key, but the client needs one
)
a := openaiprovider.NewChatCompletionsAgent(client, openaiprovider.AgentConfig{
Model: cmp.Or(os.Getenv("LOCAL_LLM_MODEL"), "llama3.2"),
Instructions: "You are a helpful assistant.",
ProviderName: "ollama",
})
fmt.Println("provider:", a.ProviderName())
resp, err := a.RunText(context.Background(), "Say hello in French.").Collect()
if err != nil {
log.Fatal(err)
}
fmt.Println(resp)
}

Whether tools, streaming and structured output work depends on the server and the model. If a server rejects response_format with a JSON schema, leave out WithStructuredOutput and parse the reply yourself.

Azure OpenAI uses the same two constructors, with the OpenAI client configured by two options from github.com/openai/openai-go/v3/azure: azure.WithEndpoint(endpoint, apiVersion) with the resource endpoint (https://<resource>.openai.azure.com), and either azure.WithAPIKey(key) or azure.WithTokenCredential(cred). Model is then your deployment name, not the model ID.

package main
import (
"cmp"
"context"
"fmt"
"log"
"os"
"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
"github.com/microsoft/agent-framework-go/provider/openaiprovider"
"github.com/openai/openai-go/v3"
"github.com/openai/openai-go/v3/azure"
"github.com/openai/openai-go/v3/option"
)
func main() {
endpoint := os.Getenv("AZURE_OPENAI_ENDPOINT") // https://my-resource.openai.azure.com
deployment := os.Getenv("AZURE_OPENAI_DEPLOYMENT_NAME") // the deployment, not the model
apiVersion := cmp.Or(os.Getenv("AZURE_OPENAI_API_VERSION"), "2025-04-01-preview")
var auth option.RequestOption
if key := os.Getenv("AZURE_OPENAI_API_KEY"); key != "" {
auth = azure.WithAPIKey(key)
} else {
cred, err := azidentity.NewDefaultAzureCredential(nil)
if err != nil {
log.Fatal(err)
}
auth = azure.WithTokenCredential(cred) // scope https://cognitiveservices.azure.com/.default
}
client := openai.NewClient(azure.WithEndpoint(endpoint, apiVersion), auth)
responsesAgent := openaiprovider.NewResponsesAgent(client, openaiprovider.AgentConfig{
Model: deployment,
Instructions: "You are a helpful assistant.",
})
chatAgent := openaiprovider.NewChatCompletionsAgent(client, openaiprovider.AgentConfig{
Model: deployment,
Instructions: "You are a helpful assistant.",
})
ctx := context.Background()
r1, err := responsesAgent.RunText(ctx, "Summarise RBAC in one line.").Collect()
if err != nil {
log.Fatal(err)
}
r2, err := chatAgent.RunText(ctx, "Summarise ABAC in one line.").Collect()
if err != nil {
log.Fatal(err)
}
fmt.Println(r1, "\n", r2)
}

azure.WithEndpoint adds the api-version query to every request and routes deployment-scoped calls: Chat Completions goes to /openai/deployments/{deployment}/chat/completions, and Responses to /openai/responses. Both Azure authentication options require it. The upstream Azure samples instead pass the v1 URL with option.WithBaseURL and azure.WithTokenCredential; with openai-go v3.79.0, the version the framework requires, that combination fails on the first request with azure: authentication requires azure.WithEndpoint. (Foundry’s provider sets this up correctly for its own endpoints.) Authenticated requests must use HTTPS; azure.WithUnsafeAllowHTTP() allows plain HTTP to a loopback address for local testing only.

azure.WithTokenCredential takes any azcore.TokenCredential. DefaultAzureCredential is convenient on a developer machine; in production use a specific credential such as azidentity.NewManagedIdentityCredential, which avoids probing a chain of sources on every cold start. To use a non-default scope, pass azure.WithTokenCredentialScopes(...) as an option to WithTokenCredential.

foundryprovider.NewAgent(endpoint, credential, target, config) takes the project endpoint (https://<resource>.services.ai.azure.com/api/projects/<project>), an azcore.TokenCredential, and a target. The provider builds the OpenAI client itself: it appends /openai/v1/ to the project endpoint, requests tokens for the https://ai.azure.com/.default audience, and removes the api-version query that the Azure option would otherwise add. The constructor panics if the endpoint is not an absolute URL, the credential is nil, or the target name is blank, and the Azure SDK refuses to send a bearer token over plain HTTP.

There are two targets:

TargetWhat runsWho owns the instructions and tools
foundryprovider.ModelDeployment("name")your Go agent definition, calling a model deployment in the project through its Responses endpointyour code: Instructions, Tools, middleware
foundryprovider.ServerAgent("name")an agent that already exists in the project, called through {project}/agents/{name}/endpoint/protocols/openai/responses?api-version=v1the service; AgentConfig.Instructions is ignored, and ID and Name default to the agent’s name
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
"github.com/microsoft/agent-framework-go/agent"
"github.com/microsoft/agent-framework-go/provider/foundryprovider"
"github.com/microsoft/agent-framework-go/tool"
"github.com/microsoft/agent-framework-go/tool/hostedtool"
)
func main() {
endpoint := os.Getenv("FOUNDRY_PROJECT_ENDPOINT")
cred, err := azidentity.NewDefaultAzureCredential(nil)
if err != nil {
log.Fatal(err)
}
ctx := context.Background()
// 1. A Go-defined agent on a model deployment in the project.
local := foundryprovider.NewAgent(endpoint, cred,
foundryprovider.ModelDeployment(os.Getenv("FOUNDRY_MODEL")),
foundryprovider.AgentConfig{
Instructions: "You answer with current information and cite sources.",
Config: agent.Config{
Name: "Researcher",
Tools: []tool.Tool{&hostedtool.WebSearch{}},
},
},
)
resp, err := local.RunText(ctx, "What changed in Go 1.26?",
foundryprovider.WithClientHeader("x-client-request-source", "docs-sample"),
).Collect()
if err != nil {
log.Fatal(err)
}
fmt.Println(resp)
if model, ok := resp.AdditionalProperties["ServedModel"]; ok {
fmt.Println("served by:", model) // from the x-ms-served-model response header
}
// 2. An agent defined in the Foundry project, addressed by name.
triage := foundryprovider.NewAgent(endpoint, cred,
foundryprovider.ServerAgent("support-triage"),
foundryprovider.AgentConfig{},
)
session, err := triage.CreateSession(ctx)
if err != nil {
log.Fatal(err)
}
resp, err = triage.RunText(ctx, "My invoice is wrong.", agent.WithSession(session)).Collect()
if err != nil {
log.Fatal(err)
}
fmt.Println(triage.Name(), "says:", resp)
}

Foundry-specific options and helpers:

APIPurpose
AgentConfig.DisableStoreOutputas for OpenAI: store: false, history kept locally
AgentConfig.OpenAIOptionsextra option.RequestOptions for the per-agent OpenAI client (an HTTP client, retries, middleware). Foundry’s own endpoint, authentication and protocol options are applied after them and win
WithClientHeader(name, value), WithClientHeaders(map)per-run x-client-* headers. Names that do not start with x-client- panic
WithHostedAgentUserIdentity(id)sends x-ms-user-identity for a hosted agent, per run
WithHostedAgentSessionID(id), SetHostedAgentSessionID(session, id), HostedAgentSessionID(session)pins a hosted agent’s sandbox session (agent_session_id). The ID the service returns is stored in the agent session and sent again on later runs; a run option that disagrees with the stored ID fails the run
resp.AdditionalProperties["ServedModel"]the model that actually served the request, when the service reports one
NewOpenAIClient(endpoint, cred, opts...)a plain openai.Client for a Foundry resource or project, with the right base URL and audience
NewEmbeddingGenerator(endpoint, cred, cfg)embeddings from a Foundry resource (see Embeddings)
NewMemoryProvider(...)a context provider over Foundry memory stores (see sessions and memory)

Creating or deploying agents in a Foundry project is not implemented in Go. Define the agent in the portal or with another SDK, then call it with ServerAgent.

anthropicprovider.NewAgent takes an anthropic.Client. anthropic.NewClient() reads ANTHROPIC_API_KEY (or ANTHROPIC_AUTH_TOKEN) and ANTHROPIC_BASE_URL. Instructions and any system-role messages are sent as system text blocks; history is always local.

package main
import (
"context"
"fmt"
"log"
"github.com/anthropics/anthropic-sdk-go"
"github.com/microsoft/agent-framework-go/agent"
"github.com/microsoft/agent-framework-go/provider/anthropicprovider"
)
type Verdict struct {
Answer string `json:"answer"`
Confidence float64 `json:"confidence" jsonschema:"between 0 and 1"`
}
func main() {
ctx := context.Background()
a := anthropicprovider.NewAgent(anthropic.NewClient(), anthropicprovider.AgentConfig{
Model: "claude-sonnet-5-5",
Instructions: "You are a careful assistant.",
Config: agent.Config{Name: "Claude"},
})
// Plain text, with a larger output budget than the 4096-token default.
resp, err := a.RunText(ctx, "Explain context.Context in two sentences.",
anthropicprovider.MessageNewParams(anthropic.MessageNewParams{MaxTokens: 1024}),
).Collect()
if err != nil {
log.Fatal(err)
}
fmt.Println(resp)
// Structured output uses Anthropic's native JSON output format.
var v Verdict
if _, err := a.RunText(ctx, "Is 97 prime?", agent.WithStructuredOutput(&v)).Collect(); err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", v)
}

Behaviour to know about:

  • max_tokens defaults to 4096. The Messages API requires a value, so the provider fills one in when MessageNewParams does not. Raise it for long answers, and keep it above any thinking budget.
  • Structured output goes in output_config.format as a JSON schema, which current Claude models honour natively. A non-object result type is wrapped in a data property on the wire and unwrapped for you, as on the other providers.
  • Extended thinking is enabled with MessageNewParams{Thinking: anthropic.ThinkingConfigParamOfEnabled(budget)}. Thinking comes back as *message.TextReasoningContent; redacted thinking arrives with empty Text and the signature in ProtectedData, which must be kept in history for the next turn (the session does this).
  • Hosted tools: &hostedtool.WebSearch{} becomes the web_search_20250305 tool, and &hostedtool.CodeInterpreter{} becomes code_execution_20250825. File search and hosted MCP are not mapped.
  • Files: DataContent and URIContent images and PDFs are sent inline or by URL. A HostedFileContent (a provider file ID) is rejected with an error.
package main
import (
"context"
"fmt"
"log"
"github.com/anthropics/anthropic-sdk-go"
"github.com/microsoft/agent-framework-go/message"
"github.com/microsoft/agent-framework-go/provider/anthropicprovider"
)
func main() {
a := anthropicprovider.NewAgent(anthropic.NewClient(), anthropicprovider.AgentConfig{
Model: "claude-sonnet-5-5",
Instructions: "Reason it through, then reply with only the final answer.",
})
thinking := anthropicprovider.MessageNewParams(anthropic.MessageNewParams{
MaxTokens: 8000,
Thinking: anthropic.ThinkingConfigParamOfEnabled(4000), // must be below MaxTokens
})
resp, err := a.RunText(context.Background(),
"A bat and a ball cost 1.10 in total. The bat costs 1.00 more than the ball. How much is the ball?",
thinking,
).Collect()
if err != nil {
log.Fatal(err)
}
for c := range resp.Contents() {
if r, ok := c.(*message.TextReasoningContent); ok {
switch {
case r.Text != "":
fmt.Println("[thinking]", r.Text)
case r.ProtectedData != "":
fmt.Println("[thinking redacted]")
}
}
}
fmt.Println(resp)
}

The Anthropic Go SDK reaches Claude on other clouds through client options, and anthropicprovider.NewAgent accepts the resulting client unchanged. The model name follows each platform’s convention.

package main
import (
"context"
"fmt"
"log"
"os"
"github.com/Azure/azure-sdk-for-go/sdk/azcore/policy"
"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
"github.com/anthropics/anthropic-sdk-go"
"github.com/anthropics/anthropic-sdk-go/bedrock"
"github.com/anthropics/anthropic-sdk-go/foundry"
"github.com/anthropics/anthropic-sdk-go/vertex"
"github.com/microsoft/agent-framework-go/agent"
"github.com/microsoft/agent-framework-go/provider/anthropicprovider"
)
func main() {
ctx := context.Background()
var a *agent.Agent
switch os.Getenv("CLAUDE_PLATFORM") {
case "bedrock":
// AWS credentials and region from the default chain (env, profile, role).
a = anthropicprovider.NewAgent(
anthropic.NewClient(bedrock.WithLoadDefaultConfig(ctx)),
anthropicprovider.AgentConfig{Model: "us.anthropic.claude-sonnet-5-5-v1:0"},
)
case "vertex":
// Application Default Credentials; region and project are required.
a = anthropicprovider.NewAgent(
anthropic.NewClient(vertex.WithGoogleAuth(ctx, "us-east5", os.Getenv("GOOGLE_CLOUD_PROJECT"))),
anthropicprovider.AgentConfig{Model: "claude-sonnet-5-5"},
)
default:
// Claude deployed in a Microsoft Foundry resource, with Entra ID.
cred, err := azidentity.NewDefaultAzureCredential(nil)
if err != nil {
log.Fatal(err)
}
fc, err := foundry.NewClient(foundry.ClientConfig{
Resource: os.Getenv("ANTHROPIC_FOUNDRY_RESOURCE"),
AzureADTokenProvider: func(ctx context.Context) (string, error) {
tok, err := cred.GetToken(ctx, policy.TokenRequestOptions{Scopes: []string{foundry.EntraIDScope}})
return tok.Token, err
},
})
if err != nil {
log.Fatal(err)
}
// foundry.Client carries the options; anthropic.NewClient turns them into a full client.
a = anthropicprovider.NewAgent(anthropic.NewClient(fc.Options...),
anthropicprovider.AgentConfig{Model: "claude-sonnet-5-5"}) // the deployment name
}
resp, err := a.RunText(ctx, "Hello from Go.").Collect()
if err != nil {
log.Fatal(err)
}
fmt.Println(resp)
}

All three options switch off the SDK’s environment defaults, so a first-party ANTHROPIC_API_KEY is never sent to another cloud.

geminiprovider.NewAgent takes a *genai.Client and panics if it is nil. genai.NewClient reads GEMINI_API_KEY or GOOGLE_API_KEY for the Gemini API; for Vertex AI set Backend: genai.BackendVertexAI with a project and location, or the GOOGLE_GENAI_USE_VERTEXAI, GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_LOCATION variables. History is always local.

package main
import (
"context"
"fmt"
"log"
"os"
"github.com/microsoft/agent-framework-go/agent"
"github.com/microsoft/agent-framework-go/message"
"github.com/microsoft/agent-framework-go/provider/geminiprovider"
"google.golang.org/genai"
)
type City struct {
Name string `json:"name"`
Country string `json:"country"`
}
func main() {
ctx := context.Background()
cfg := &genai.ClientConfig{APIKey: os.Getenv("GEMINI_API_KEY"), Backend: genai.BackendGeminiAPI}
if project := os.Getenv("GOOGLE_CLOUD_PROJECT"); project != "" && os.Getenv("GEMINI_API_KEY") == "" {
cfg = &genai.ClientConfig{Backend: genai.BackendVertexAI, Project: project, Location: "europe-west2"}
}
client, err := genai.NewClient(ctx, cfg)
if err != nil {
log.Fatal(err)
}
a := geminiprovider.NewAgent(client, geminiprovider.AgentConfig{
Model: "gemini-3.8-flash",
Instructions: "You are a geography tutor.",
Config: agent.Config{Name: "Gemini"},
})
// Native generation settings, including thought summaries.
settings := geminiprovider.GenerateContentConfig(genai.GenerateContentConfig{
Temperature: genai.Ptr[float32](0.3),
ThinkingConfig: &genai.ThinkingConfig{IncludeThoughts: true},
})
resp, err := a.RunText(ctx, "Why is London foggy?", settings).Collect()
if err != nil {
log.Fatal(err)
}
for c := range resp.Contents() {
if r, ok := c.(*message.TextReasoningContent); ok && r.Text != "" {
fmt.Println("[thought]", r.Text)
}
}
fmt.Println(resp)
var city City
if _, err := a.RunText(ctx, "Which city is the capital of Scotland?", agent.WithStructuredOutput(&city)).Collect(); err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", city)
}

Instructions are appended to systemInstruction. Function tools are sent as one genai.Tool holding every function declaration, with each tool’s JSON schema in parametersJsonSchema and its return schema in responseJsonSchema. Hosted tools each become their own genai.Tool: WebSearch as Google Search, CodeInterpreter as code execution, and FileSearch with its HostedVectorStoreContent inputs as file-search store names. Structured output sets responseMimeType: application/json and responseJsonSchema. agent.WithToolMode(tool.ToolModeRequired) becomes function-calling mode ANY, and tool.RequireTool(name) also sets allowedFunctionNames.

copilotprovider.NewAgent drives the GitHub Copilot CLI through the Copilot Go SDK. Unlike the other providers, Copilot runs its own agent loop: it has built-in tools (shell, file edits), it executes your function tools itself, and it asks for permission through SessionConfig.OnPermissionRequest rather than returning ToolApprovalRequestContent. The agent’s Name and Description default to “GitHub Copilot Agent” and “An AI agent powered by GitHub Copilot”.

package main
import (
"bufio"
"context"
"fmt"
"log"
"os"
"strings"
copilot "github.com/github/copilot-sdk/go"
"github.com/github/copilot-sdk/go/rpc"
"github.com/microsoft/agent-framework-go/agent"
"github.com/microsoft/agent-framework-go/provider/copilotprovider"
)
func askUser(req copilot.PermissionRequest, _ copilot.PermissionInvocation) (rpc.PermissionDecision, error) {
fmt.Printf("\nCopilot wants to: %s. Allow? (y/n) ", req.Kind())
line, _ := bufio.NewReader(os.Stdin).ReadString('\n')
if strings.EqualFold(strings.TrimSpace(line), "y") {
return &rpc.PermissionDecisionApproveOnce{}, nil
}
return &rpc.PermissionDecisionReject{}, nil
}
func main() {
ctx := context.Background()
// Uses the bundled Copilot CLI, or COPILOT_CLI_PATH. Sign in with the CLI first.
client := copilot.NewClient(nil)
if err := client.Start(ctx); err != nil {
log.Fatal(err)
}
defer func() { _ = client.Stop() }()
a := copilotprovider.NewAgent(client, copilotprovider.AgentConfig{
Instructions: "Keep answers short.",
SessionConfig: &copilot.SessionConfig{OnPermissionRequest: askUser},
})
session, err := a.CreateSession(ctx)
if err != nil {
log.Fatal(err)
}
for update, err := range a.RunText(ctx, "List the Go files in this directory.",
agent.WithSession(session), agent.Stream(true)) {
if err != nil {
log.Fatal(err)
}
fmt.Print(update)
}
fmt.Println()
}

The Copilot session ID becomes the agent session’s service ID, so a later run with the same agent.Session resumes the Copilot session. Function tools are registered as Copilot tools; tools wrapped with tool.ApprovalRequiredFunc are gated with a pre-tool-use hook that answers “ask”, unless you supply your own SessionConfig.Hooks.OnPreToolUse, in which case the framework logs a warning and leaves gating to you. Structured output, tool modes and the ToolAutoCall settings do not apply.

Two providers also produce text embeddings, for the vector-backed memory and retrieval providers or your own use. Both return an embedding.Generator[string, *embedding.Of[float32]]:

ConstructorNotes
openaiprovider.NewEmbeddingGenerator(client, EmbeddingGeneratorConfig{Model, Dimensions})any OpenAI or Azure OpenAI client; requests base64 encoding by default
foundryprovider.NewEmbeddingGenerator(endpoint, cred, EmbeddingGeneratorConfig{Model, Dimensions, OpenAIOptions})a Foundry project or resource endpoint; Model (the deployment) must not be blank, and invalid arguments panic
package main
import (
"context"
"fmt"
"log"
"github.com/microsoft/agent-framework-go/embedding"
"github.com/microsoft/agent-framework-go/provider/openaiprovider"
"github.com/openai/openai-go/v3"
)
func main() {
ctx := context.Background()
gen := openaiprovider.NewEmbeddingGenerator(openai.NewClient(), openaiprovider.EmbeddingGeneratorConfig{
Model: "text-embedding-3-small",
Dimensions: new(256),
})
// A batch: one embedding per input, in input order.
out, err := gen.Generate(ctx, []string{"tents", "sleeping bags"}, nil)
if err != nil {
log.Fatal(err)
}
for i, e := range out.Embeddings {
fmt.Printf("%d: %d dimensions\n", i, e.Dimensions())
}
if out.Usage != nil {
fmt.Println("tokens:", out.Usage.InputTokenCount)
}
// One value, as a plain []float32, with a per-request override.
vec, err := embedding.GenerateVector(ctx, gen, "waterproof jacket",
&embedding.Options{Dimensions: new(64)})
if err != nil {
log.Fatal(err)
}
fmt.Println("single vector:", len(vec))
}

Dimensions: new(256) uses Go 1.26’s new(expr). An empty batch returns an error without making a request. embedding.Bind(gen) turns a typed generator into the *embedding.BoundGenerator that the vector stores expect; sessions and memory shows it in use.

The framework itself reads no credentials. Each vendor client does, and the upstream samples use a few more variables for their own settings:

ProviderRead by the clientUsed by the samples
OpenAIOPENAI_API_KEY, OPENAI_BASE_URL, OPENAI_ORG_ID, OPENAI_PROJECT_ID, OPENAI_CUSTOM_HEADERSOPENAI_CHAT_MODEL_NAME
Azure OpenAInone (pass azure.WithEndpoint with azure.WithAPIKey or azure.WithTokenCredential); azidentity reads the usual AZURE_* variablesAZURE_OPENAI_ENDPOINT, AZURE_OPENAI_DEPLOYMENT_NAME
Foundryazidentity credentialsFOUNDRY_PROJECT_ENDPOINT, FOUNDRY_MODEL, FOUNDRY_EMBEDDING_MODEL
AnthropicANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_BASE_URL; ANTHROPIC_FOUNDRY_* for Claude on Foundry
GeminiGEMINI_API_KEY, GOOGLE_API_KEY, GOOGLE_GEMINI_BASE_URL; Vertex AI: GOOGLE_GENAI_USE_VERTEXAI, GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATIONGEMINI_MODEL
GitHub CopilotCOPILOT_CLI_PATH

The OpenAI and Foundry adapters add the SDK’s identity and a feature-usage bitmask to the User-Agent header, but only on approved Azure and Foundry HTTPS hosts. AGENT_FRAMEWORK_FEATURE_MASK_DISABLED=1 drops the bitmask and AGENT_FRAMEWORK_USER_AGENT_DISABLED=1 drops the framework’s whole contribution.

Retries and timeouts are the vendor clients’ business too: see middleware.

A provider is an agent.ProviderConfig passed to agent.New. Only Run is required; it receives the prepared messages (history and context already added) and the run options, and returns a stream of *agent.ResponseUpdate.

ProviderConfig fieldPurpose
ProviderNamereturned by a.ProviderName() and used in telemetry
Runfunc(ctx, messages, ...agent.Option) iter.Seq2[*agent.ResponseUpdate, error]; read options with agent.GetOption and agent.AllOptions
Middlewaresrun after history and context providers, around every call to Run. Add toolautocall.New(...) here if your Run returns function calls and you want the framework to execute them
ManagesToolExecutionset when Run executes tools itself (as Copilot does), so the agent’s function middleware is applied to the tools in the options. Pass agent.WithFuncCallID(ctx, callID) as the context of each Call so function middleware sees the call ID
Format, Unmarshalsupport agent.WithStructuredOutput: build a ResponseFormat for a Go value, and decode the reply into it. jsonformat.ForType and jsonformat.FromResponseFormat do the work
CreateSessionset up provider-specific session state when CreateSession is called, or when a run creates a throwaway session

Treat the message and option slices as read-only; clone before changing them. Set ConversationID on an update only if the service now holds the history, because the agent then stops storing it locally.

The testing page uses this to build a scripted fake model. A more practical use is composition. The provider below wraps two existing agents and falls back to the second when the first fails before producing any output, which is a common way to ride out a regional outage:

package main
import (
"context"
"fmt"
"iter"
"log"
"os"
"github.com/microsoft/agent-framework-go/agent"
"github.com/microsoft/agent-framework-go/agent/harness/toolautocall"
"github.com/microsoft/agent-framework-go/message"
"github.com/microsoft/agent-framework-go/provider/openaiprovider"
"github.com/openai/openai-go/v3"
"github.com/openai/openai-go/v3/option"
)
// stateless strips the session so an inner agent neither reads nor writes history:
// the outer agent has already added the history to the messages.
func stateless(opts []agent.Option) []agent.Option {
out := make([]agent.Option, 0, len(opts))
for _, o := range opts {
if _, isSession := agent.GetOption([]agent.Option{o}, agent.WithSession); !isSession {
out = append(out, o)
}
}
return out
}
// fallback tries each agent in turn. Once one has yielded an update, its errors are final.
func fallback(agents ...*agent.Agent) agent.RunFunc {
return func(ctx context.Context, msgs []*message.Message, opts ...agent.Option) iter.Seq2[*agent.ResponseUpdate, error] {
return func(yield func(*agent.ResponseUpdate, error) bool) {
var lastErr error
for _, a := range agents {
started := false
failed := false
for update, err := range a.Run(ctx, msgs, stateless(opts)...) {
if err != nil && !started {
lastErr, failed = fmt.Errorf("%s: %w", a.Name(), err), true
break
}
started = true
if !yield(update, err) || err != nil {
return
}
}
if !failed {
return
}
}
yield(nil, lastErr)
}
}
}
func main() {
// Function tools must not be run twice, so the inner agents only return tool calls
// and the outer agent's toolautocall middleware executes them.
noLoop := &toolautocall.Config{MaximumIterationsPerRequest: new(0)}
primary := openaiprovider.NewChatCompletionsAgent(
openai.NewClient(option.WithBaseURL("http://127.0.0.1:1/v1/"), option.WithMaxRetries(0)),
openaiprovider.AgentConfig{Model: "gpt-6.1-sol", ToolAutoCall: noLoop, Config: agent.Config{Name: "primary"}},
)
secondary := openaiprovider.NewChatCompletionsAgent(openai.NewClient(),
openaiprovider.AgentConfig{Model: "gpt-6-luna", ToolAutoCall: noLoop, Config: agent.Config{Name: "secondary"}},
)
a := agent.New(agent.ProviderConfig{
ProviderName: "fallback",
Run: fallback(primary, secondary),
Middlewares: []agent.Middleware{toolautocall.New(toolautocall.Config{})},
}, agent.Config{
Name: "Resilient",
RunOptions: []agent.Option{agent.WithInstructions("You are a helpful assistant.")},
})
ctx := context.Background()
session, err := a.CreateSession(ctx)
if err != nil {
log.Fatal(err)
}
resp, err := a.RunText(ctx, "Hello!", agent.WithSession(session)).Collect()
if err != nil {
fmt.Fprintln(os.Stderr, "both providers failed:", err)
os.Exit(1)
}
fmt.Println(resp.Messages[0].AuthorName, "->", resp)
}

Two details make this work. The inner agents run without a session, so their default in-memory history provider stays out of the way and the outer agent alone stores the conversation. And tool execution happens once, in the outer agent: the inner agents have their tool loop switched off with MaximumIterationsPerRequest: new(0), so they pass function calls straight back. With the primary unreachable, the program prints secondary -> ...: an agent stamps its name on updates only when they carry no author yet, so the inner agent’s name survives and tells you which provider answered.

  • One agent type. Python and .NET wrap a chat client (OpenAIChatClient, IChatClient) in an agent. Go has no public chat-client abstraction: each provider constructor returns an *agent.Agent, and agent.ProviderConfig is the extension point.
  • Vendor SDKs, not framework clients. You construct openai.Client, anthropic.Client and *genai.Client yourself, so their options (base URL, retries, HTTP client, cloud platform) are available directly.
  • Native options instead of a common options type. Temperature, max tokens, seed and similar settings are set through each provider’s native-parameters run option, not a shared ChatOptions.
  • Not in Go: Ollama, Bedrock Converse, Mistral, Foundry Local and Copilot Studio providers, the Claude Agent SDK agent, and creating Foundry agents. Python’s providers page lists what it has.