/penguin-sdk

name: penguin-sdk
description: Use to build a standalone external program with an agent in it, or connect an external program to a Penguin agent. For an app inside PenguinHarness with its own Agent and workbench tab, use agent-initialization and penguin-plugin directly; no SDK/API question applies. A program reaches an agent in one of two ways, and the skill asks the user which before building — embedded with the Penguin Harness SDK (`@prismshadow/penguin-core`, no server), or over the Penguin server's Agent API (AMSP, with the `@prismshadow/amsp` client or curl). This is writing application code, not configuring an Agent State inside PenguinHarness. Covers self-contained projects, the createSession/run streaming loop with thinking and image messages, wiring the user's existing tools in as CLI commands, a complete RAG recipe that ingests documents into a knowledge base and answers with citations behind a web UI, and the Agent API client. Workbenches — the tabs and pages beside the chat that an Agent keeps for itself inside PenguinHarness — are the penguin-plugin skill's.
version: 2026.10.26.1

Penguin Harness SDK and Agent API

This skill builds programs that use a Penguin agent. A program reaches one in either of two ways, embedded with the SDK or through the Penguin server's Agent API, and the user picks which. Workbenches — pages and server code an Agent keeps inside PenguinHarness — are a third thing, and the penguin-plugin skill's.

To have an agent perform a task for you, use the `run_subagent` tool: both ways are for programs, not for handing off your own work.

Two ways to reach an agent

**The SDK: `@prismshadow/penguin-core`, embedded in the program.**

• *What it is.* The agent loop as a TypeScript library. The program creates its own Agent from a data directory inside the project and runs its Sessions in-process. No Penguin server is involved, at build time or at run time.
• *What you get.* The basic agent loop: the Agent State files (`AGENTS.md`, Skills, tools), the streamed AMSP records and an `approve` callback for every tool call, in a self-contained folder that runs wherever Node 24 does, on the program's own model key.
• *What you don't get.* No server-managed Sessions (the program keeps its own), no visibility in the Web App, no approvals UI (the program answers in code) and no cost center. The embedded agent belongs to the program: changes to an Agent inside PenguinHarness never reach it.
• *Choose it when* the program must stand alone: shipped to other machines or people, run where no Penguin server is, or with the agent built into the product.

**The API: Penguin's Agent API, over AMSP.**

• *What it is.* The program calls an Agent that lives in PenguinHarness, over HTTP. The Penguin server runs each turn and streams it back over AMSP as the Session's records, the ones its Trace holds, and the program continues a conversation by its Session id. TypeScript uses the `@prismshadow/amsp` client (`AgentClient`); any other language, or curl, speaks HTTP and SSE directly.
• *What you get.* The Agent as PenguinHarness runs it: its `AGENTS.md`, Skills and memory, on the Project's models and credentials, so the program holds no model key. The server keeps the conversations as archived chats (**Settings › Archived chats** in the Web App), where a person finds one and unarchives it to read it and answer its approvals, and their usage lands in the cost center.
• *What it requires.* A running Penguin server that the program can reach over the network; API access turned on for that Agent by the Project's owner, on the Agent's **API** tab; and a key created there, shown once. You never turn these on yourself (see *The API path*).
• *Choose it when* the Agent already exists in PenguinHarness or should be managed there, people need to see its conversations or costs, or the program is not written in TypeScript.

Ask which way first

Whenever the user asks to connect a program to an agent, or to build a program with an agent in it (an AI, agentic or RAG app, a bot, a service, a script), ask which way before you write anything, even when the request is otherwise concrete. It is the only question a concrete request gets: it overrides the no-follow-up-questions default of *Before you start* for this one question.

Do not ask when the way is already chosen:

• in the user's message: "use the SDK", "standalone", "without the Penguin server" or "embed the agent" chooses the SDK; "call it over the API", "through the Agent API", "with AMSP", "with `@prismshadow/amsp`" or "with curl" chooses the API;
• earlier in this conversation, for the same program.

Naming this skill does not choose a way. Workbenches (the penguin-plugin skill) take neither way and need no question; neither does connecting a Feishu, Telegram, QQ or WeChat bot to a conversation, which is the Web App's Remote control.

Ask with one sentence and this choice block, in the user's language, as the end of your reply. Mark one option `"recommended": true` only when the request leans that way: an Agent the user already has in PenguinHarness leans to the API, an app to ship to others leans to the SDK.

Your program can reach the agent in two ways: embedded with the SDK, or through the Penguin server's Agent API.

```a2ui
{
  "type": "choice",
  "id": "agent-access",
  "question": "How should the program reach the agent?",
  "options": [
    {
      "label": "SDK: embed the agent",
      "value": "Use the SDK: embed the agent in the program",
      "description": "Runs inside the program on its own model key. No Penguin server; nothing appears in the Web App."
    },
    {
      "label": "API: call a Penguin Agent",
      "value": "Use the Agent API: call a Penguin Agent over AMSP",
      "description": "Calls an Agent on your Penguin server. You turn on its API access and create a key; its conversations appear in the Web App."
    }
  ]
}

The Web App shows the block as two buttons; the CLI and