Model selection & granularity

• Match model capability to the agent role. Use smaller, cheaper models for high-volume routing/triage (e.g., mini/nano or equivalent) and larger, more capable models for specialist reasoning or multimodal work.
• Recent community signals show open models are viable for many agent tasks. LangChain’s analysis indicates some open models (e.g., GLM-5, MiniMax M2.7) now match closed models on core agent tasks like file ops and tool use; evaluate them on your workloads before committing (see LangChain: "Open Models have crossed a threshold" https://blog.langchain.com/open-models-have-crossed-a-threshold/).
• Consider model latency and token budget per hop; design the graph to minimize unnecessary round-trips (summarize between hops when appropriate).
• For long-running or deep tasks, prefer non-blocking subagent patterns (async subagents) so supervisors can continue interacting with users while background work completes. LangChain Deep Agents v0.5 formalizes async subagents and the task lifecycle (start/check/update/cancel/list) — adopt similar lifecycle semantics when implementing background tasks (https://blog.langchain.com/deep-agents-v0-5/).

Agent authorization and credentials

• Two common authorization patterns: per-user delegation (agents act using the end-user's credentials) and fixed-agent credentials (agents use a service account or fixed key). Choose per workload.
• Always explicitly include an auth/credential field in handoff metadata when routing to agents that will access protected resources.
• When passing user credentials, include scope-limited tokens and refresh/expiration metadata to enable safe short-lived access.

Handoff protocol

Handoffs transfer control from one agent to another. The handoff carries:

• target agent — which specialist to invoke
• context — accumulated conversation state (or pointer/token to external store)
• instructions — what the target should focus on
• metadata — routing reason, priority, constraints
• auth — credential or auth type required (e.g., "user-delegated" or "service-account")
• model_hint — optional preferred model or model class for the target

// Vendor-agnostic handoff definition (pattern)
const handoffPayload = {
  target: "code_agent",
  contextPointer: "redis://ctx:12345", // or inline context
  instructions: "Implement feature X using the research summary",
  metadata: { reason: "needs_implementation", priority: "high" },
  auth: { type: "service-account", tokenRef: "vault://tokens/agent-sa" },
  model_hint: "capability:reasoning-large",
};

Notes:

• Keep the schema vendor-agnostic (target, contextPointer, instructions, metadata, auth, model_hint) so routing logic can span multiple providers and platforms (OpenAI, Vercel AI Gateway, Anthropic/Claude deployments).
• Prefer pointers (contextPointer) for long-lived context to avoid token bloat; fetch and rehydrate only the slices the specialist needs.

State management patterns

┌─────────────┐     context      ┌─────────────────┐
│   Router     │ ──────────────> │  Specialist A    │
│   Agent      │                 │  (research)      │
└──────┬───── ┘                 └────────┬─────────┘
       │                                  │ result
       │    ┌─────────────────────────────┘
       ▼    ▼
┌─────────────┐     context      ┌─────────────────┐
│ Orchestrator │ ──────────────> │  Specialist B    │
│   (merge)    │                 │  (code)          │
└──────┬──────┘                 └────────┬─────────┘
       │                                  │ result
       ▼                                  ▼
┌─────────────────────────────────────────────────┐
│                 Guardrail Agent                   │
│            (validate final output)                │
└──────────────────────────────────────────────────┘

Shared state approaches:

• Pattern: prefer pointers (contextPointer) + on-demand retrieval for long-running chains to avoid token bloat.
• Use a dedicated vector DB and memory layer for agents that require personal or long-lived context; enforce access controls per-credential.

Async & long-running tasks

• New orchestration patterns support async (non-blocking) subagents that return a task ID immediately and execute in the background. Treat these tasks as first-class entities with a lifecycle (start, check, update, cancel, list) and store task IDs and status in your external state store. LangChain Deep Agents v0.5 documents this pattern and the accompanying management tools (https://blog.langchain.com/deep-agents-v0-5/).
• Design supervisors to avoid blocking on long-running subagents: allow the supervisor to continue interacting with the user, poll or subscribe to task completion events, and provide follow-up instructions to running tasks when necessary.
• Ensure idempotency and cancellation semantics for background tasks. Provide meaningful timeouts and resource limits; surfaced task metadata should include expected duration and resource class.

Async subagent primitives (reference implementation patterns):

from deepagents import AsyncSubAgent, create_deep_agent

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    subagents=[
        AsyncSubAgent(
            name="researcher",
            description="Performs deep research on a topic.",
            url="https://my-agent-server.dev",
            graph_id="research_agent",
        ),
    ],
)
# Async tools available on the main agent: start_async_task, check_async_task,
# update_async_task, cancel_async_task, list_async_tasks

• Multiple async subagents can run concurrently; supervisors should persist task IDs, expose status to users, and provide update/cancel hooks. Use a task lifecycle table in your external store (task_id, owner, status, started_at, expected_duration, provenance).
• Async subagents enable heterogeneous deployments: an orchestrator can delegate to remote agents that run different models, toolsets, or hardware. Implement strict authentication and encryption on Agent-Protocol endpoints and enforce runtime authorization checks on cross-host handoffs.

Skills, Fleet, and reuse

• Teams increasingly reuse "skills" (shareable, versioned behavior modules) across fleets of agents. Skills capture domain knowledge, tools, and test suites that you can attach to agents for consistent behavior (LangChain Fleet patterns: https://blog.langchain.com/march-2026-langchain-newsletter/).
• OpenAI's Custom GPTs (announced April 2026) provide another packaging pattern: purpose-built, customizable assistants that can encapsulate agent behavior, prompts, and tools for distribution or productization. Custom GPTs support tailored instructions, uploaded knowledge, and enabled tools (OpenAI Academy: "Using custom GPTs", Apr 10 2026 — https://openai.com/academy/custom-gpts).
• Treat skills and Custom GPTs as code: version them, include automated tests, and attach identity/permission metadata so they can be safely shared across teams.
• Agent identity and permissions: assign each agent an identity and an access policy (which skills it may use, which credentials it may request) and enforce at runtime. Enterprise platforms emphasize governance and permissions for company-wide agents.

Workflow

Step 0: Define evaluation and safety requirements before building

• Draft an agent evaluation checklist (routing accuracy, task completion, guardrail precision) and include both offline and online tests (LangChain agent evaluation checklist patterns).
• Specify telemetry, failure modes, and human escalation paths. Consider integrating safety bug-bounty signals and anomalous-behavior reports into your issue triage.

Step 1: Define your agent graph

Map out which agents exist and how control flows between them.

// Agent graph as config
const agentGraph = {
  entrypoint: "triage",
  agents: {
    triage: {
      handoffs: ["research", "code", "clarify"],
      model_hint: "mini/fast",
      authorization: "user-delegated",
    },
    research: {
      handoffs: ["code", "triage"],
      tools: ["web_search", "doc_retrieval"],
      model_hint: "reasoning-large",
    },
    code: {
      handoffs: ["review"],
      tools: ["file_write", "shell_exec", "test_run"],
      authorization: "service-account",
    },
    review: {
      handoffs: ["code", "triage"],
      tools: ["lint", "test_run"],
    },
  },
  guardrails: ["safety_check", "pii_redact"],
};

Step 2: Implement agents with focused instructions

• Keep instructions narrow and deterministic where possible. Provide explicit success/failure signals and named outputs (e.g., {status: "APPROVED"}).

const reviewAgent = new Agent({
  name: "review_agent",
  instructions: `You review code changes for:
1. Correctness
2. Security
3. Performance
4. Style

If issues found, return {status: "REVIEW_FAIL", comments: [...]}. If approved, return {status: "APPROVED"}.`,
  handoffs: [handoff(codeAgent)],
  tools: [lintTool, testRunTool],
});

Step 3: Run the orchestration loop — secure execution

• For agents that execute code, run untrusted code in isolated sandboxes. Use timeouts and resource limits.
• Signal streaming data with agent identity so consumers can attribute output to the correct agent.

async function orchestrate(userMessage: string) {
  const result = await run(triageAgent, userMessage, {
    maxTurns: 15,
    stream: true,
  });

  for await (const event of result) {
    if (event.type === "agent_handoff") {
      console.log(`Handoff: ${event.from} → ${event.to}`);
    }
    if (event.type === "tool_call") {
      console.log(`Tool: ${event.name}(${JSON.stringify(event.args)})`);
    }
    if (event.type === "message") {
      yield event.content;
    }
  }
}

Step 4: Add guardrails and safety processes

• Align guardrails with authoritative model behavior specifications and monitor for agentic vulnerabilities (prompt injection, hidden tool-use, and data exfiltration). The Model Spec emphasizes instruction precedence and treating untrusted data cautiously — apply these principles when composing multi-agent systems.
• Vendor guidance (OpenAI, Anthropic) and community safety patterns should inform guardrail ordering and policy enforcement.
• Participate in, or subscribe to, safety bug bounty channels to receive reports about agentic failures and prioritize fixes.

const safetyGuardrail: InputGuardrail = {
  name: "safety_check",
  execute: async (input) => {
    const result = await classifySafety(input);
    if (result.category === "unsafe") {
      return { blocked: true, reason: result.reason };
    }
    return { blocked: false };
  },
};

Tooling & libraries

• LangChain patterns: evaluation checklists, middleware for agent harness customization, Fleet for managing agent fleets and shareable skills, and Deep Agents for long-running orchestration. Deep Agents v0.5 adds async subagents and an Agent Protocol for cross-deployment interoperability; adopt task lifecycle patterns (start/check/update/cancel/list) and store task IDs in your state system (https://blog.langchain.com/deep-agents-v0-5/).
• Vercel provides sandboxed environments and has added CLI management for sandboxes (see Vercel changelog entry: "Use and manage Vercel Sandbox directly from the Vercel CLI", Apr 8 2026). Use Vercel Sandboxes or equivalent isolated environments to run untrusted agent workloads and tests; consult the changelog for exact CLI commands and requirements (https://vercel.com/changelog).
• Prefer a stable, vendor-agnostic handoff schema in your orchestration layer to minimize friction when SDKs change. Normalize vendor-specific fields in an adapter layer and implement provider adapters for OpenAI, Anthropic (Claude), Vercel AI Gateway, and any in-house agent servers.
• Use vector DBs, Redis, or managed memory layers that integrate with your agent harness. Monitor open-source model releases and evaluate them on your agent-specific tasks before committing to a vendor.

Examples

Example 1: Customer support pipeline

const supportTriage = new Agent({
  name: "support_triage",
  instructions: `Classify the support ticket:
- billing → billing_agent
- technical → tech_agent
- account → account_agent
- unknown → ask clarifying question`,
  handoffs: [
    handoff(billingAgent),
    handoff(techAgent),
    handoff(accountAgent),
  ],
});

const billingAgent = new Agent({
  name: "billing_agent",
  instructions: "Handle billing inquiries. You can look up invoices and issue refunds.",
  tools: [lookupInvoice, issueRefund, updateSubscription],
  authorization: "service-account",
});

Example 2: Code generation with review loop (with sandboxing)

async function codeWithReview(task: string) {
  let result = await run(codeAgent, task);
  let attempts = 0;

  while (attempts < 3) {
    const review = await run(reviewAgent, result.output);
    if (review.output.includes("APPROVED")) break;
    // Run fixes in a sandbox and re-run tests
    result = await run(codeAgent, `Fix these issues:\n${review.output}`);
    attempts++;
  }

  return result.output;
}

Example 3: Async background work with task lifecycle

// Supervisor launches a long-running research task
const taskId = await startAsyncTask({ target: "research_agent", input: { query } });
// Store taskId in Redis or DB; supervisor returns to user and continues

// Later: check status or retrieve result
const status = await checkAsyncTask(taskId);
if (status.done) {
  const result = await getAsyncTaskResult(taskId);
}

// Update or cancel when needed
await updateAsyncTask(taskId, { refine: "Focus on peer-reviewed sources only" });
await cancelAsyncTask(taskId);

Cross-vendor routing

• Vendors (Anthropic, OpenAI, Vercel, etc.) expose tools and router patterns. Keep the handoff payload vendor-agnostic and normalize vendor-specific fields in the adapter layer. Where possible, target Agent-Protocol-compliant endpoints for remote agents (LangChain Agent Protocol: https://github.com/langchain-ai/agent-protocol).

async function vendorAgentRouter(userMessage: string) {
  const routerPrompt = `You are a router. Analyze the request and return a JSON handoff object with these fields: {agent, context, priority, routing_reason}. Do not call vendor tools directly from this prompt.`;

  const response = await callRouterModel({
    model: routerModel, // use a fast router model
    prompt: routerPrompt + "\n" + userMessage,
  });

  const handoff = JSON.parse(extractJson(response));
  // Normalize and dispatch using the vendor adapters
  await dispatchToAgent(handoff);
}

Decision tree

Is one LLM call enough?
├── Yes → Single agent with tools (no orchestration needed)
└── No
    ├── Is the flow linear (A → B → C)?
    │   ├── Yes → Pipeline pattern (chain agents sequentially)
    │   └── No
    │       ├── Does routing depend on input classification?
    │       │   ├── Yes → Router + Specialists pattern
    │       │   └── No
    │       │       ├── Do agents need to iterate (code → review → fix)?
    │       │       │   ├── Yes → Loop pattern with max iterations
    │       │       │   └── No → Parallel fan-out pattern
    │       │       └── Need human approval mid-flow?
    │       │           ├── Yes → Add approval gates between stages
    │       │           └── No → Fully autonomous pipeline
    └── Need guardrails?
        ├── Yes → Wrap entry/exit with guardrail agents and monitor per authoritative model-spec guidance
        └── No → Direct orchestration

Additional checks:
- Which model class for each agent? (fast/mini for routers, larger for specialists)
- Which authorization pattern is required? (user-delegated vs service-account)
- Do any agents execute code? If yes, run in sandboxes with resource limits (see Vercel changelog entry for CLI sandbox management)
- Where is state stored? Use pointers for long-lived context and vector DBs for retrieval memory
- Do you need shareable skills across teams? Consider Fleet + skills patterns for governance and reuse

Edge cases and gotchas

• Infinite loops: Always set maxTurns — agents handing off to each other can loop forever
• Context bloat: Each handoff passes the full conversation; for long chains, summarize before handoff
• Error propagation: If a specialist fails, the orchestrator must handle the error — don't let it silently drop
• Model mismatch: Router agents can use cheaper/faster models; specialists may need more capable ones
• Streaming across handoffs: The stream must indicate which agent is currently responding
• Tool overlap: If two specialists share a tool, ensure they don't conflict on shared state
• Latency multiplication: Each handoff adds a full LLM round-trip; budget 2-5s per hop where possible
• Guardrail ordering: Input guardrails run before the agent; output guardrails after — both can block
• Agentic vulnerabilities: Monitor for prompt injection, hidden tool-use, and data exfiltration; leverage safety bug bounty learnings and chain-of-thought monitoring where possible
• Long-running task hygiene: For async subagents and background tasks, enforce task TTLs, record provenance, and provide cancellation and idempotency hooks (LangChain Deep Agents async guidance: https://blog.langchain.com/deep-agents-v0-5/).

Evaluation criteria

• Run both offline evals (static datasets, unit tests) and online evals (shadow mode, canary traffic). Use LangChain evaluation patterns and vendor SDK testing tools to build reproducible agent tests.

Research-backed changes

• LangChain Deep Agents v0.5 (Apr 2026) introduces async (non-blocking) subagents, expanded multi-modal filesystem support, and an Agent Protocol for cross-deployment interoperability. It documents AsyncSubAgent usage patterns and the task-management tools (start_async_task, check_async_task, update_async_task, cancel_async_task, list_async_tasks) — adopt the lifecycle semantics for background tasks in your orchestrator (https://blog.langchain.com/deep-agents-v0-5/).
• OpenAI published guidance on Custom GPTs (Apr 10, 2026) that formalizes a packaging option for repeatable assistant/agent behaviors — Custom GPTs support tailored instructions, uploaded knowledge, and enabled tools (OpenAI Academy: "Using custom GPTs", Apr 10 2026 — https://openai.com/academy/custom-gpts).
• Vercel added explicit CLI support for managing sandboxes to run isolated workloads (see Vercel changelog entry: "Use and manage Vercel Sandbox directly from the Vercel CLI", Apr 8 2026 — https://vercel.com/changelog). Use sandboxed environments for untrusted code execution and validate CLI requirements from the changelog.
• Continue to monitor vendor changelogs, LangChain releases, and the Agent Protocol repo for protocol-level changes that affect cross-vendor routing and long-running orchestration.