Skip to content
⚠️ Before You Start
Risk: Medium
Duration: 2-4 hours including the decision record
Last Validated: Not yet validated (draft)
Kind: Decision guide
Risk Note: Medium (a wrong choice forces a rewrite of state and tool code later)

Choose the agent template and runtime (LangGraph, Agent Framework or Foundry Agent Service)

Draft outline: not validated

Drafted with AI from official sources on 16 Oct 2026. Do not use on a live system until it is written, dry-run by someone other than the author and signed off (planned 2026-11-26). Author: James · dry-run: Sanjay Sarvesh · sign-off: Prasanna. Work items: AGT-01-T01, AGT-01-T02, AGT-01-T03, AGT-01-T04.

Catalog point to cover

The catalog maturity target is six templates; the outline names four types (task, planner, supervisor, tool). Agree the six with the pack owner or record the deviation.

1. Summary

At the start of any agentic build or when a client asks why we picked a framework. Also when an existing agent needs a different hosting model.

Risk: Medium (a wrong choice forces a rewrite of state and tool code later). Typical duration: 2-4 hours including the decision record.

2. When to use and when not to

Use it when: At the start of any agentic build or when a client asks why we picked a framework. Also when an existing agent needs a different hosting model.

Do not use it when: to be written by the author.

3. What you must know first

  • Task, planner, supervisor and tool agents differ in who owns the control loop
  • LangGraph gives explicit graphs, checkpointers and interrupts in Python and JavaScript
  • Microsoft Agent Framework is the successor to Semantic Kernel and AutoGen, with graph workflows and built-in orchestrations
  • Foundry Agent Service runs prompt agents and hosted agents with managed identity, tools and tracing
  • Durable state needs a production checkpointer, not an in-memory one

4. Options

Outline of the decision process; the author describes each option.

  1. Write the job of the agent in one sentence and list every tool and side effect
  2. Decide whether the control flow must be custom; if not, prefer a Foundry prompt agent
  3. If custom flow is needed, pick LangGraph for cloud-neutral Python or Agent Framework for Microsoft-first .NET or Python teams
  4. Pick the template type: task, planner, supervisor or tool agent
  5. Check limits that matter (tools per agent, hosted sessions) in the current Foundry quotas page
  6. Record the choice and the rejected options in the decision YAML
  7. Get agent lead sign-off for any deviation from the default
  8. Review the decision at the first production incident or after six months

Draft snippet: Template and runtime decision record

# docs/decisions/agent-template-choice.yaml
decision: agent-template-and-runtime
date: 2026-10-16
owner: agent-lead
context:
  needs_custom_control_flow: true
  needs_durable_human_approval: true
  client_cloud: azure
  team_language: python
options:
  - id: langgraph-on-aks
    template: task-agent
    runtime: LangGraph on AKS or Container Apps, PostgresSaver checkpointer
    pick_when: explicit graph, custom retry and termination, cloud-neutral code
  - id: agent-framework-workflow
    template: supervisor-agent
    runtime: Microsoft Agent Framework workflow, Cosmos DB checkpoint storage
    pick_when: Microsoft-first client, .NET or Python, built-in orchestrations
  - id: foundry-prompt-agent
    template: tool-agent
    runtime: Foundry Agent Service prompt agent
    pick_when: simple tool use, no custom loop, managed hosting preferred
chosen: langgraph-on-aks
deviation_needs_approval_from: agent-lead
review_by: 2027-04-16

Snippets to add:

  • snippets/docs/decisions/agent-template-choice.yaml: Decision record for template and runtime (yaml)
  • snippets/decision-table.md: Decision table one-pager (markdown)

5. Decision table

Situation Choose Why
to be written

To be written by the author from the outline above.

7. Known issues and fixes

Symptom Likely cause Fix
Team needs a human approval step that waits for days Picked a runtime without durable checkpoints Move to a template with a Postgres or Cosmos DB checkpointer before go-live
Semantic Kernel agent code no longer matches current samples Agent Framework replaced SK as the target for new agent work Follow the SK to Agent Framework migration guide for new templates; keep SK only for maintained code
Client security rejects the hosting model Hosting and identity were not part of the decision Add identity and network constraints to the context block before choosing

8. Monitoring and alerts

Signal Alert when Action
Count of agents in production not built from a library template Any new one in the monthly inventory Agent lead reviews and either adopts a template or records an exception

9. AWS and open-source equivalents

On AWS the managed equivalent is Amazon Bedrock AgentCore (Runtime, Memory, Gateway, Identity, Observability); Bedrock Agents is now classic and closed to new customers. LangGraph and OpenAI Agents SDK run on either cloud.

10. Validation record

Pending. Planned dry-run scenario: A second engineer takes two past use cases (one simple tool bot, one long-running approval flow), applies the guide blind and must reach the same template and runtime as the agent lead within 30 minutes each.

11. Sources