Give each role an explicit result contract

Learning objective

Design role-specific prompts with examples, constraints, and structured-output schemas.

Core idea

A specialist prompt defines a transformation: which input the agent receives, what decision it makes, what evidence it can use, and what result it returns. A persona such as “experienced analyst” supplies none of these contracts. In a multi-agent solution, ambiguity becomes another agent’s input and can propagate through the workflow.

Separate behavioral instructions from the result’s machine-readable shape. Examples demonstrate the intended decision, constraints narrow permitted behavior, and a schema defines the return interface. These mechanisms reinforce each other but cannot substitute for one another. A perfectly shaped answer can still be unsupported or outside the role’s responsibility.

See 1.1.4 for the broader behavioral contract and 0.3 for instruction, evidence, and output separation. Here you design the prompt that makes one specialist’s result usable by its next consumer.

How it works

Define the specialist’s transformation

For a Foundry prompt agent, PromptAgentDefinition.instructions carries the behavioral instructions, and project.agents.create_version() creates the agent version. The prompt-agent quickstart uses Azure AI Projects 2.x; its code is incompatible with the 1.x API. Treat the versioned instructions as part of the specialist’s interface, rather than a description attached after implementation.

Write the role as a bounded task. An invoice analyst extracts disputed line items and supporting passages. It does not authorize payment, invent missing amounts, or decide which employee can approve a refund. State the input contract, permitted evidence, completion condition, and what to return when evidence is absent. Make missing information a representable outcome instead of an invitation to guess.

Assign complementary roles. An extractor returns candidates with source identifiers; a reviewer checks those candidates against evidence. Giving both agents the same broad instruction to “resolve the case” obscures which output each owns. Their prompts should expose the different transformations even when they use the same model.

Use examples to demonstrate decisions

Microsoft’s prompt-engineering guidance describes few-shot examples as example user and assistant interactions in Chat Completions. Choose examples that distinguish outcomes, rather than several easy successes. An evidence-backed claim, an unsupported claim, and contradictory sources teach different decisions. Keep examples consistent with the written constraints and output contract.

A valid example should show why a specialist stops. For instance, an invoice with an illegible amount should produce a missing-value outcome, not a plausible reconstruction. A reviewer example should reject a candidate whose citation does not support its claim. The example’s result teaches the rule even when the surrounding prose says the same thing.

Examples consume context and can bias decisions toward their patterns. Evaluate their selection and order as prompt changes; see 2.1.4. Do not treat an example as a source for the live request. Label demonstrations separately from request evidence, and use invented identifiers that cannot be confused with real case records.

Put the shape in the supported API

Microsoft Agent Framework supplies structured-output controls for code-based specialists. In Python, pass a Pydantic model or JSON schema mapping through agent.run(..., options={"response_format": ...}), or configure default_options at agent creation. A Pydantic result appears as a model instance in response.value; a schema mapping produces parsed JSON there. Support depends on the underlying chat client’s capabilities, so verify the specialist’s selected client rather than assuming every agent supports the option.

In .NET, RunAsync<T>() returns a typed result, while AgentRunOptions.ResponseFormat = ChatResponseFormat.ForJsonSchema<T>() configures the schema. ChatClientAgent supports structured outputs with compatible chat clients. Choose the typed result when the consumer needs a known return type; use the response-format mechanism when working with a raw schema or a collaboration interface.

See 0.3 for Azure OpenAI’s request locations and strict-schema subset. Its structured-outputs documentation excludes Foundry Agent Service, while the Agent Framework page names Foundry Agent among agents that can accept initialization-time ResponseFormat. Those statements do not establish universal support: this lesson uses a compatible Azure OpenAI chat client through Agent Framework and does not promise schema enforcement from a schema placed in Agent Service instructions. JSON mode establishes valid JSON, not schema adherence.

For a tool-using specialist on the Azure OpenAI path, structured outputs do not support parallel function calls; set parallel_tool_calls to false. This constraint concerns function calling, not permission to execute a tool.

The following is an illustrative Chat Completions response_format fragment for an evidence reviewer:

{
  "type": "json_schema",
  "json_schema": {
    "name": "claim_review",
    "strict": true,
    "schema": {
      "type": "object",
      "properties": {
        "decision": {
          "type": "string",
          "enum": ["supported", "unsupported", "needs_review"]
        },
        "source_id": { "type": ["string", "null"] }
      },
      "required": ["decision", "source_id"],
      "additionalProperties": false
    }
  }
}

Both fields are required; null represents the absence of a source. The enum constrains the decision vocabulary. It does not verify that the cited source exists or supports the decision.

Validate meaning after shape

Use the required-field, nullable-value, and closed-object rules described in 0.3 when defining the specialist’s contract. The claim_review example keeps both fields required and makes absence explicit instead of allowing an omitted field to mean different things to different consumers.

The subset does not support constraints such as string pattern or numeric minimum and maximum. Enforce those rules in application validation rather than assuming the inference schema applies them. Check source membership, evidence support, amount ranges, and consistency between fields before forwarding a result. See 0.10 for validation mechanics.

A schema violation and a valid needs_review decision are different outcomes. The first means the interface failed; the second can be the correct result for incomplete evidence. Keeping them separate prevents “successful JSON” from becoming the definition of task success.

Key distinctions and trade-offs

The three prompt mechanisms serve different purposes:

A richer schema can simplify downstream processing but increases coupling. Adding a required field changes every producer and consumer. Prefer the smallest contract that preserves the decision and its evidence. Handle execution permissions independently; see 1.1.7.

Architecture / decision scenario

A dispute workflow has an extractor and a reviewer. The extractor’s instructions require disputed line items and source identifiers, with a missing-value outcome for unreadable amounts. Its examples include a complete invoice and a partially unreadable invoice. The reviewer receives the extracted claims plus authorized evidence and returns supported, unsupported, or needs_review.

The reviewer uses a Microsoft Agent Framework Python agent backed by a compatible Azure OpenAI chat client. The application supplies the JSON schema from claim_review through agent.run(..., options={"response_format": ...}) and consumes the parsed result in response.value. It then checks that any source_id belongs to the request’s evidence and supports the decision. The Foundry prompt agent coordinating the workflow does not inherit schema enforcement from that code-based specialist.

An unsupported claim cannot become payable because its JSON parses. The workflow sends needs_review to the designated review path and leaves payment authorization outside both prompts. A proposed extra result field triggers a contract review and regression comparison, not an informal prompt edit.

Common exam traps

• Treating a professional persona as a bounded specialist task.
• Using examples whose successful answers contradict written constraints.
• Confusing JSON mode’s valid JSON with schema adherence.
• Assuming a schema in Agent Service instructions enables structured outputs.
• Assuming every Agent Framework chat client supports response_format.
• Treating a valid source identifier as proof that its passage supports the answer.

What to remember

Define the role’s transformation, demonstrate hard decisions, and constrain the result through the supported interface. Use required nullable fields for missing information, then validate meaning separately. Schema adherence makes an answer consumable; evidence and policy checks make it usable.

Knowledge check

References

• Microsoft, Prompt engineering techniques
• Microsoft, Quickstart: Create a prompt agent
• Microsoft, How to use structured outputs with Azure OpenAI in Microsoft Foundry Models
• Microsoft, Structured outputs