docs: add local agent framework guidance #164
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,57 @@ | ||
| --- | ||
| name: build-dotnet-agent-service | ||
| description: Build a local-first F# or C# Semantic Kernel agent service with explicit tools, model capability checks, evaluation fixtures, and draft-before-write promotion. | ||
| license: Apache-2.0 | ||
| compatibility: Designed for Codex and compatible Agent Skills clients working with F#, C#, ASP.NET Core, and the dotnet CLI on macOS or other supported .NET environments. | ||
| metadata: | ||
| owner: gaelic-ghost | ||
| repo: socket | ||
| category: dotnet-agent-service | ||
| allowed-tools: Read Bash(rg:*) Bash(git:*) Bash(dotnet:*) | ||
| --- | ||
|
|
||
| # Build .NET Agent Service | ||
|
|
||
| Use this skill when Semantic Kernel's plugin/function orchestration solves a | ||
| real .NET application need. Preserve F# and C# equality: ask for the language | ||
| when a new project has no established choice, and do not add C# only to host an | ||
| agent. | ||
|
|
||
| ## Source Check | ||
|
|
||
| - Semantic Kernel: <https://learn.microsoft.com/en-us/semantic-kernel/overview/> | ||
| - .NET: <https://learn.microsoft.com/dotnet/> | ||
| - ASP.NET Core: <https://learn.microsoft.com/aspnet/core/> | ||
|
|
||
| ## Workflow | ||
|
|
||
| 1. Establish the deterministic baseline, typed input/output, chosen language, | ||
| exact model endpoint/model, tool permissions, and no-op result. | ||
| 2. Use Semantic Kernel only for a named plugin/function, planning, or | ||
| orchestration requirement. Keep domain logic in F# modules or C# domain | ||
| types rather than embedding it in prompt or endpoint code. | ||
| 3. Start with narrow read-only functions. The host validates authorization, | ||
| schemas, timeouts, and output independently of model responses. | ||
| 4. Prove valid tool-call JSON, structured output, no-call behavior, malformed | ||
| call recovery, maximum-step stopping, and grounded observations on the exact | ||
| local/self-hosted server and model; HTTP compatibility alone is insufficient. | ||
| 5. Add memory, planners, background work, or an ASP.NET endpoint only when the | ||
| application requires it. Name retention, restart, and failure behavior. | ||
| 6. Add fake-plugin tests, structured-result tests, denied-write tests, and | ||
| opt-in local-model smoke tests. External writes remain draft-only until an | ||
| exact `auto-with-escalation` approval gate is satisfied. | ||
|
|
||
| ## Validation | ||
|
|
||
| Run the repository's narrowest `dotnet build` and `dotnet test` commands. | ||
| Separate fake-tool behavior from model-adapter smoke evidence, and report | ||
| attempted versus executed side effects. | ||
|
|
||
| ## Guardrails | ||
|
|
||
| - Do not add Semantic Kernel to a library or service that only needs one direct | ||
| model request. | ||
| - Do not store secrets, local endpoint credentials, prompts, or traces in | ||
| source control. | ||
| - Do not start a background agent, schedule, or public endpoint by default. | ||
| - Do not use model output as permission to call a destructive plugin. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
|
@@ -2,20 +2,41 @@ | |||||||||||||
|
|
||||||||||||||
| ## Dated Maturity And Availability Snapshot | ||||||||||||||
|
|
||||||||||||||
| Official sources checked 2026-07-28. These are routing gates, not permanent guarantees; record the exact source revision or release and re-check before implementation. | ||||||||||||||
|
|
||||||||||||||
| | Surface | Maturity at check | Availability gate to verify | | ||||||||||||||
| | --- | --- | --- | | ||||||||||||||
| | [Core AI models](https://github.com/apple/coreai-models), [coreai-torch](https://github.com/apple/coreai-torch), and [coreai-optimization](https://github.com/apple/coreai-optimization) | New, actively developing Apple open-source stack | `coreai-models` runtime integration currently states macOS/iOS 27+ and Xcode 27+; verify device, operator, compiler, and package requirements | | ||||||||||||||
| | [Core ML Tools](https://github.com/apple/coremltools) and Core ML | Established Apple conversion and deployment route | Verify the selected `coremltools` release, deployment target, operator coverage, compute units, state/cache support, and Swift API availability | | ||||||||||||||
| | [MLX](https://github.com/ml-explore/mlx), [MLX Swift](https://github.com/ml-explore/mlx-swift), and [MLX LM](https://github.com/ml-explore/mlx-lm) | Active Apple-silicon research/runtime ecosystem | Verify Apple-silicon/Metal platform support, language/package version, model architecture, quantization, and target-device memory | | ||||||||||||||
| | [LM Studio](https://lmstudio.ai/docs/developer/rest) local server | Local inference server and model-management control plane | Use `http://localhost:1234/v1` only for OpenAI-compatible client APIs; use native `/api/v1` for model lifecycle, stateful chats, authentication, and MCP control. Keep loopback-only unless an explicit authenticated exposure decision exists. | | ||||||||||||||
| | [ExecuTorch Core ML backend](https://github.com/pytorch/executorch/tree/main/backends/apple/coreml) | Documented ExecuTorch Apple backend | Verify the pinned ExecuTorch release, Apple deployment target, partition coverage, fallback, state, and packaging requirements | | ||||||||||||||
| | [ExecuTorch MLX delegate](https://github.com/pytorch/executorch/tree/main/backends/mlx) | Experimental and under active development | Current upstream targets Apple Silicon M1+ and requires a full Xcode Metal compiler; verify exact revision, build/platform support, partition/operator coverage, portable-runtime fallback, parity, and performance | | ||||||||||||||
| | Apple Foundation Models framework and [Python Apple FM SDK](https://github.com/apple/python-apple-fm-sdk) | Apple system-model SDK plus Apple-owned Python bridge | Current Python SDK states macOS 26+, Xcode 26+, Python 3.10+, a compatible Apple-silicon Mac, and Apple Intelligence availability; re-check all requirements | | ||||||||||||||
| | [Foundation Models utilities](https://github.com/apple/foundation-models-utilities) | Emerging/experimental utilities around the system model | Pin the revision and verify each utility against the current Foundation Models SDK; do not treat it as a stable arbitrary-weight runtime | | ||||||||||||||
|
|
||||||||||||||
| Core AI and Core ML are distinct artifact and API lanes. MLX is a general array framework; MLX Swift and MLX LM are separate integration layers. Foundation Models exposes Apple's system model, not arbitrary user-supplied weights. | ||||||||||||||
|
|
||||||||||||||
| ## LM Studio Local Server Gate | ||||||||||||||
|
|
||||||||||||||
| LM Studio is appropriate when a macOS developer needs to host a downloaded | ||||||||||||||
| model for a local client, agent framework, or developer tool. It is not a path | ||||||||||||||
| for compiling an `.aimodel`, shipping an iOS model, using Apple's system model, | ||||||||||||||
| or proving ANE use. | ||||||||||||||
|
|
||||||||||||||
| - Use the OpenAI-compatible `/v1/responses`, `/v1/chat/completions`, | ||||||||||||||
| `/v1/embeddings`, and `/v1/models` endpoints when an existing client needs a | ||||||||||||||
| compatible base URL; the documented default is `http://localhost:1234/v1`. | ||||||||||||||
| - Use native `/api/v1` endpoints when the workflow needs model download/load/ | ||||||||||||||
| unload, stateful chats, API-token authentication, MCP control, or server | ||||||||||||||
| lifecycle observation. | ||||||||||||||
|
Comment on lines
+30
to
+32
There was a problem hiding this comment. 🔒 Security & Privacy | 🟡 Minor | ⚡ Quick win 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -euo pipefail
echo "== candidate files =="
fd -a 'apple-model-tooling\.md|choose-apple-model-runtime' . | sed 's#^\./##'
echo "== target excerpt =="
file='plugins/model-lab-skills/skills/choose-apple-model-runtime/references/apple-model-tooling.md'
if [ -f "$file" ]; then
nl -ba "$file" | sed -n '1,80p'
fi
echo "== nearby references to /api/v1, /v1, API token =="
rg -n "(/api/v1|/v1|API token|API-key|authentication|auth)" plugins/model-lab-skills/skills/choose-apple-model-runtime plugins/model-lab-skills 2>/dev/null | head -200Repository: gaelic-ghost/socket Length of output: 573 🌐 Web query:
💡 Result: LM Studio provides both a native v1 REST API and compatibility endpoints (OpenAI and Anthropic), each with different authentication and endpoint patterns. Authentication By default, the LM Studio local server does not require authentication [1][2]. For enhanced security in shared or production environments, you can enable API token authentication via the "Server Settings" in the Developer tab of the LM Studio application [1][3]. When authentication is enabled: - You must generate an API token through the "Manage Tokens" section in the Server Settings [1]. - Every request must include the token in the HTTP Authorization header using the Bearer scheme: Authorization: Bearer $LM_API_TOKEN [1][2]. - For the LM Studio Python and TypeScript SDKs, the token can be provided via an environment variable (LM_API_TOKEN) or passed directly in the client configuration [4]. - Note that for OpenAI-compatible client libraries, you may still need to provide an arbitrary API key (e.g., "lm-studio") to satisfy the client's internal validation, even if LM Studio does not strictly require or validate it [5]. API Endpoints LM Studio supports two primary types of API structures: 1. Native v1 REST API (/api/v1/) The native v1 REST API provides features specific to LM Studio, such as stateful chats, MCP integration, and advanced model management [6]. Key endpoints include: - POST /api/v1/chat [6][7] - GET /api/v1/models [6][7] - POST /api/v1/models/load [6][7] - POST /api/v1/models/unload [6][7] - POST /api/v1/models/download [6][7] - GET /api/v1/models/download/status [6][7] 2. Compatibility Endpoints (/v1/) LM Studio also exposes OpenAI-compatible and Anthropic-compatible endpoints, which typically map to the /v1/ path [6][8]. Commonly used OpenAI-compatible endpoints include: - GET /v1/models [8] - POST /v1/chat/completions [8] - POST /v1/completions [8] - POST /v1/embeddings [8] - POST /v1/responses (used for Codex/completions) [8] To use these compatibility endpoints, you generally set your client's base URL to point to your local instance (e.g., http://localhost:1234/v1) [8]. Citations:
🏁 Script executed: #!/bin/bash
set -euo pipefail
echo "== target excerpt =="
python3 - <<'PY'
from pathlib import Path
p = Path('plugins/model-lab-skills/skills/choose-apple-model-runtime/references/apple-model-tooling.md')
lines = p.read_text().splitlines()
for i in range(min(80, len(lines))):
print(f"{i+1:4}\t{lines[i]}")
PY
echo "== nearby references to /api/v1, /v1, authentication, API-token =="
python3 - <<'PY'
from pathlib import Path
import re
root = Path('.')
for path in sorted(path for path in Path('.').rglob('*')
if '.git' not in path.parts and path.suffix in {'.md','.yaml','.json','.py','.sh'}):
try:
text = path.read_text(errors='replace')
except Exception:
continue
needle = re.compile(r'(/api/v1|/v1|API token|API-key|authentication|auth)', re.I)
matches = ((i+1, needle.findall(line.strip())) for i,line in enumerate(text.splitlines()) if needle.search(line))
if any(m[1] for m in matches):
print(f'-- {path} --')
for i,line in ((i,line) for i,line in enumerate(text.splitlines()) if needle.search(line)):
print(f'{i+1}: {line.strip()}')
PYRepository: gaelic-ghost/socket Length of output: 50376 🏁 Script executed: #!/bin/bash
set -euo pipefail
file='plugins/model-lab-skills/skills/choose-apple-model-runtime/references/apple-model-tooling.md'
python3 - <<'PY' "$file"
import sys
from pathlib import Path
p = Path(sys.argv[1])
lines = p.read_text().splitlines()
print("-- ", p, "--")
for i in range(min(80, len(lines))):
print(f"{i+1:4}\t{lines[i]}")
PY
echo "== targeted mentions in target file only =="
python3 - "$file" <<'PY'
import sys
from pathlib import Path
p=Path(sys.argv[1])
terms=['/api/v1','/v1','API-token authentication','API token','model download','load/unload','MCP']
lines=p.read_text().splitlines()
for i,line in enumerate(lines):
if any(t.lower() in line.lower() for t in terms):
print(f"{i+1}: {line}")
PYRepository: gaelic-ghost/socket Length of output: 7406 Do not require native API-token authentication applies to LM Studio’s API surface generally, while native-only routes are model lifecycle, stateful chats, and MCP control. Separating these avoids routing OpenAI-compatible Proposed wording-Use native `/api/v1` endpoints when the workflow needs model download/load/
- unload, stateful chats, API-token authentication, MCP control, or server
- lifecycle observation.
+Enable API-token authentication for any exposed API. Use native `/api/v1`
+ endpoints when the workflow needs model download/load/unload, stateful chats,
+ MCP control, or server lifecycle observation.📝 Committable suggestion
Suggested change
🤖 Prompt for AI Agents |
||||||||||||||
| - Keep the server loopback-only by default. LAN or public exposure requires an | ||||||||||||||
| explicit authentication, network, secret, and recovery decision. | ||||||||||||||
| - Before attaching tools or external writes, prove the exact model/server pair | ||||||||||||||
| returns schema-conforming structured output, makes valid and unnecessary | ||||||||||||||
| no-call decisions, recovers from malformed output, stops within its bound, | ||||||||||||||
| and handles tool calls only where the model genuinely supports them. | ||||||||||||||
|
|
||||||||||||||
| ## Implementation Handoffs | ||||||||||||||
|
|
||||||||||||||
| - Use Apple's `coreai-models` skills `working-with-coreai` and `model-authoring` for Core AI implementation details. | ||||||||||||||
|
|
||||||||||||||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Keep the root README catalog summary nontechnical.
These changed bullets add maintainer-level implementation details (
Semantic Kernel agent-service,local-first, and guidance handoffs). Move those details toROADMAP.mdor plugin documentation and keep this inventory to short, user-facing capability summaries.As per coding guidelines: Keep the root README short, nontechnical, and focused on end users or agents installing and using the Socket marketplace.
🤖 Prompt for AI Agents
Source: Coding guidelines