awesome-copilot/skills/agent-architecture/references/architecture-selection.md

Architecture Selection and Interaction Contract

Read when choosing or revisiting the execution approach. Apply delegation and long-running interaction sections only to relevant tasks. Build the decision card from available context; resolve material unknowns under discovery-protocol.md without turning it into a questionnaire.

1. Choose by task properties

Property	Selection consequence
Inputs and rules are defined	Ordinary automation may suffice; an LLM is needed only for ambiguous interpretation
All data is available before answering	Consider one call with output validation
Order and permitted transitions are known	A predefined workflow with necessary LLM steps
New observations determine the next step	A bounded agent loop; identify the uncertainty it resolves
Independent workstreams or required context/permission isolation exist	Compare one agent with delegation; sequential dependencies limit parallelism's benefit
Shared mutable state and external effects exist	Assign change and integration owners; more workers increase coordination cost
Long work, pauses, events, or streams	An interaction and recovery contract is needed, not automatically another agent
Team, environment, or model capabilities are constrained	Account for the existing runtime, available tools, and support; demonstrate model suitability on the task

For a material decision, compare the baseline and one or two plausible alternatives: option → requirements covered → expected benefit → cost/risks → why selected or rejected → check → reconsideration trigger. An obvious small task needs only a brief rationale, without an artificial table. If the user specified a topology as a requirement, preserve it and show tradeoffs.

Compare topologies on the same tasks, data access, criteria, and aggregate budget for every worker, retry, and integration step. An equal per-worker limit does not mean an equal system budget. Account for final output quality, latency, cost per accepted task, and human labor. Without measurements, benefit remains a hypothesis; deliver a conditional architecture and comparison plan now. An experiment is not a prerequisite for the first design. Do not import scaling thresholds from someone else's benchmark.

From functions to agent boundaries

First derive functions from working cases, with input, output, method, state, owner, and permissions. Then choose an execution form, and only afterward boundaries of persistent components. A profession name or separate API does not itself create an agent boundary.

Form	Sufficient selection rationale
Deterministic process	Rules define transitions; an individual LLM step does not require model control of the whole process
Tool	A bounded operation with a contract and permissions; its caller owns the goal and result acceptance
Skill/instruction	A repeatable domain method with specified input, context, steps, and verifiable result; an instruction alone does not require a separate runtime
Temporary subagent	A bounded subtask; separate context, parallelism, or permissions provide a verifiable benefit; the parent accepts and integrates the result
Persistent agent/profile	Independent responsibility and a justified execution boundary; explicit state and lifecycle owners, reason for isolation, and coordination cost

For a persistent component, check a stable output/decision class, state between runs, independent start/pause/recovery, and separation rationale: permissions, data, context, load, or failure domain. These are decision factors, not a universal formula: isolation or scaling can justify a stateless worker, and a shared owning service may own state. Unknowns do not prove complexity necessary. Identify a simpler alternative and a condition for merging components again.

Coordination is a separate decision: who owns the overall result, dependencies, resources, and conflicts? An ordinary scheduler/router handles fixed transitions. Justify a model coordinator by an actual need for contextual selection and validation of its decisions. Multiple profiles do not automatically need an orchestrator; an agent planner may select tools without persistent child profiles. Do not generalize platform definitions into universal prohibitions.

Select the management interface and storage separately, based on human work and data. First check capabilities of the existing chat, Jira, CLI, or API. Justify a new dashboard by a concrete need for a shared queue, structured confirmations, search/comparison, or different permissions. Choose storage for durability, concurrent writes, transactions, search, retention, and available support; files/SQLite/PostgreSQL are options, not a mandatory ladder. Semantic search needs its own task, not merely the presence of agents.

2. If delegation exists

Populate one real handoff contract, then identify other roles' differences:

owner/recipient → goal and boundaries → inputs, versions, and permitted sources → required artifact and readiness criterion → permissions → share of total budget/deadline → stopping and partial output → evidence/provenance → validation and integration.

Separately identify the owner of the final decision and shared resources. Define who resolves conflicting results, prevents duplicate effects, and accepts partial results. Delegating specific work and unrestricted peer-to-peer messaging have different coordination rules; do not substitute one for the other. A2A, a queue, a graph, and a supervisor service are not mandatory.

Check transfer of constraints, recursion and nested budgets, lost/duplicate delivery, conflicting shared writes, expiry, and late results after cancellation. Trace assigned → accepted → completed/partial/rejected → verified → integrated in one example. Child authority does not exceed what the parent was granted. Several identical model conclusions from shared context are not independent evidence; the integrator checks grounds and contradictions, not just vote counts.

3. If interaction continues over time

Choose according to need: synchronous response, background task, event/schedule, streaming, or voice. Describe observable behavior: task acceptance, progress, waiting, partial result, error, cancellation, and final result. Without background work, the corresponding states are inapplicable.

Link task, conversation, individual run, and external action identities. Resume may create a new run while retaining links to the task and prior effects; verify specific SDK fields in current documentation. Define handling of late and duplicate events.

When the user changes the goal, mark the boundary between old and new intent: which unstarted actions stop, which were already sent and require reconciliation, what partial result is retained, and which parameters/permissions must be recalculated. Cancellation does not undo completed actions and must not allow new effects under an obsolete goal. Do not request still-valid permission again without a scope change.

Streamed text before validation is provisional. If a requirement prohibits disclosing certain data, a final post-streaming validator is too late: control is required before releasing those fragments. Show normal completion and one cancellation/correction scenario, not merely a state list.