step01 · Basic Foundry Provider

What this lesson demonstrates

This is the same one-shot Joker agent you meet in the very first tutorial, but viewed from the provider angle. The whole point is the three moving parts the Azure AI Foundry provider needs — a project endpoint, a credential, and a model deployment name — and how foundryprovider.NewAgent turns them into an agent.Agent. A tiny logging middleware rides along so you can watch each run print in the console.

The provider is three inputs

The construction is deliberately factored out of main into a newAgent helper so the offline test can build the identical, middleware-wired agent with a fake credential:

func newAgent(endpoint, model string, cred azcore.TokenCredential, mw agent.Middleware) *agent.Agent {
    return foundryprovider.NewAgent(
        endpoint,
        cred,
        foundryprovider.ModelDeployment(model),
        foundryprovider.AgentConfig{
            Instructions: "You are good at telling jokes.",
            Config: agent.Config{
                Name:        "Joker",
                Middlewares: []agent.Middleware{mw}, // wraps every run
            },
        },
    )
}

The target argument here is foundryprovider.ModelDeployment(model). That selects project Responses API mode: you address a deployed model by its name against a Foundry project endpoint (…services.ai.azure.com). The other target, ServerAgent, points at an existing server-side agent instead, and with that one the service owns the instructions.

What to notice

AgentConfig embeds agent.Config. Provider-specific fields — Instructions, DisableStoreOutput, OpenAIOptions — sit alongside the embedded config, which carries the cross-provider bits like Name and Middlewares. That split is the mental model for the whole provider family: provider knobs on the outer struct, portable knobs on the embedded one.

The gotcha worth internalizing: the credential is lazy. The demo’s DefaultAzureCredential doesn’t contact Azure until the first request, so building the agent never touches the network. That is exactly what makes the structural test possible — it constructs the agent with a dummy endpoint and a fake credential and asserts a.Name() == "Joker" with no az login.

In main, RunText(...).Collect() runs to completion and drains the ResponseStream into a single Response before printing.

How it maps to Foundry

Under the hood ModelDeployment mode issues POST {endpoint}/openai/v1/responses with a bearer token from your az login session — the OpenAI-compatible Responses API that Foundry projects expose. Every later lesson in this provider family (sessions, tools, structured output, observability) layers on top of this same three-input wiring, so it pays to have it cold.

Run it

go run ./tutorial/02-agents/providers/foundry/step01_basic

The tests build and pass offline; the live model call is gated behind AF_LIVE=1 (which needs az login and FOUNDRY_PROJECT_ENDPOINT).

Next: 02 · Multi-turn (sessions)