agent-framework-choice

name

agent-framework-choice

description

Use when choosing or implementing agent runtimes: LangGraph workflows, Pi / pi-ai / embedded Pi harness agents, thin provider SDK loops, model API wire protocol (Chat Completions vs Responses vs Messages), or "which agent framework" decisions. Scene-based defaults — not a mandate to use Pi or LangGraph. Prefer Chat Completions for multi-model. Prefer docs lookup (Context7/official). Do NOT use for ordinary CRUD with no agent runtime.

Agent Framework Choice

Advisory decision aid. Pick what fits the product surface. Do not force Pi SDK or LangGraph into every "agent" mention.

First: name the scene

Scene	Typical product	Runtime bias
A. Web FE/BE / SaaS API	Next/Vue + API, multi-user cloud app	Server-side agent code: thin SDK, or LangGraph if you need durable workflow/HITL graphs. Pi SDK is usually a poor default here.
B. Local harness agent	Electron/desktop agent, repo workspace agent, computer-use style	Pi ecosystem: Pi SDK, pi-ai, or embed/integrate a Pi agent — choose per docs and packaging needs
C. Explicit business workflow graph	Approvals, bid pipelines, multi-day stateful processes	LangGraph (+ langgraph skills/docs)
D. Minimal tool chat	Few tools, little state	Provider official SDK loop first — no heavy framework

If unsure: state 2 options with scene fit, recommend one, let the user pick for irreversible choices.

Decision tree (soft)

What is shipping?
  Web FE/BE product without a local agent shell
    → do NOT default to Pi SDK
    → need durable graph / HITL / branching business process? LangGraph
    → else thin server-side LLM + tools SDK

  Local / desktop / workspace harness agent
    → Pi SDK or pi-ai or embedded Pi agent (read current docs)
    → not LangGraph unless you truly need a durable business graph

  Pure multi-step workflow product (cloud)
    → LangGraph first

  Tiny prototype
    → thinnest thing that works (ponytail)

LangGraph path

When scene C (or A with real workflow needs):

1. Prefer langgraph-docs / langgraph-agent-patterns when available
2. Else Context7 / official docs before coding
3. Model state, nodes, edges, persistence, HITL explicitly
4. Do not load LangGraph skills for non-LangGraph work

Pi / local harness path

When scene B:

1. Read current Pi / pi-ai docs (Context7 or official) — APIs change
2. Choose packaging deliberately:
   • Pi SDK — when you need the SDK integration model the docs describe
   • pi-ai — when that package matches the stack
   • Embed / shell out to Pi agent — when product should host or wrap the agent rather than re-implement the loop
3. Do not cargo-cult LangGraph graphs onto Pi
4. Do not recommend this path as default for ordinary web FE/BE

Thin SDK path

When scene D or early spike: official OpenAI/Anthropic/etc. SDK + tools. Promote to LangGraph/Pi only when pain appears (state, permissions, multi-agent, long sessions).

Model API protocol (wire format) — default preference

When building agent products or provider adapters (not when merely using Claude Code/Codex as the IDE):

Protocol	Prefer?	Notes
OpenAI Chat Completions POST /v1/chat/completions	Default first choice for multi-model / gateway / local / Pi-compat	Widest support; Pi uses openai-completions for this; Ollama, vLLM, OpenRouter, most mid-proxies speak it
OpenAI Responses /v1/responses	When targeting OpenAI-native agent features and ecosystem is OK being narrower	Codex may use this as a client; don't force it as the only server protocol you implement
Anthropic Messages /v1/messages	When product is Claude-native	Fine as a second path or dedicated provider
Legacy /v1/completions	Avoid for new work	Obsolete for chat/tools agents

Rules of thumb (advisory):

1. New agent backends / multi-provider support → implement and test Chat Completions first.
2. Pi / pi-ai custom providers → prefer api: "openai-completions" unless docs say otherwise for that host.
3. Adding Responses or Messages is OK as extra adapters after Completions works — not instead of it, unless the product is single-vendor by design.
4. Don't confuse tool/MCP protocol (how agents call tools) with model wire protocol (how you call LLMs). This section is only the latter.

Docs habit (strong suggestion, not a jail)

Before writing non-trivial framework code, do at least one fresh docs lookup this session for the APIs you will call. If you skip (spike / user said go), note that.

Output before coding

## Scene (A/B/C/D)
## Runtime choice
## Model API protocol (default: Chat Completions unless single-vendor reason)
## Why this fits
## Why not the others (esp. if rejecting Pi or LangGraph)
## Docs consulted
## Risks if wrong

Anti-patterns

• "Harness agent → must Pi SDK" on a cloud web app
• "Agent → must LangGraph" for a 2-tool chatbot
• Mixing Pi + LangGraph in P0 without a boundary
• Coding from memory on fast-moving agent APIs
• Building only Responses-API support when the product needs multi-model / OpenAI-compat gateways
• Using legacy /v1/completions for new tool-calling agents

Related

• stack-defaults, product-bootstrap, multi-agent-deliberation