Agent framework choice
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.From its SKILL.md
npx -y skills add AVIDS2/avid-skill --skill agent-framework-choiceAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
5.4 KB, as published. Nobody here has run it
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):
- Prefer langgraph-docs / langgraph-agent-patterns when available
- Else Context7 / official docs before coding
- Model state, nodes, edges, persistence, HITL explicitly
- Do not load LangGraph skills for non-LangGraph work
Pi / local harness path
When scene B:
- Read current Pi / pi-ai docs (Context7 or official) — APIs change
- 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
- Do not cargo-cult LangGraph graphs onto Pi
- 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):
- New agent backends / multi-provider support → implement and test Chat Completions first.
- Pi / pi-ai custom providers → prefer
api: "openai-completions"unless docs say otherwise for that host. - Adding Responses or Messages is OK as extra adapters after Completions works — not instead of it, unless the product is single-vendor by design.
- 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/completionsfor new tool-calling agents
Related
stack-defaults,product-bootstrap,multi-agent-deliberation