Foundry Agent Starter Kit

Build, test, and deploy Microsoft Foundry agents from Python repos.

This package collects the reusable Copilot guidance for Foundry agents. It is named for the user job, not for the SDK. Castia remains the Python package underneath the flow.

What is included

Install

Install from the Castia marketplace in Copilot App when that marketplace is available to your environment:

1. Open Customize.
2. Open Plugins.
3. Add the sethjuarez/castia marketplace if it is not listed.
4. Install Foundry Agent Starter Kit.

For command line setup, install the plugin from the repository subdirectory:

copilot plugin marketplace add sethjuarez/castia
copilot plugin install foundry-agent-starter-kit@castia

This is Copilot plugin distribution, not Agency distribution. Do not use Agency plugin commands or Agency marketplaces for the public Castia path.

The packaged canvas is the only supported Foundry Agent Playground. Do not copy the extension into a scenario repository; installing or updating this plugin keeps the playground implementation and its action contract consistent across projects.

If a scenario repository already contains .github\extensions\agent-playground, remove that directory and install or update this plugin instead. The supported canvas ID is now foundry-agent-playground; update saved canvas references that still use the old agent-playground ID.

Canvas-only testing

Use this when you need to test or share the canvas before the plugin marketplace path is available. The canvas folder is:

plugins\foundry-agent-starter-kit\com.github.copilot\extensions\foundry-agent-playground

Open it as Foundry Agent Playground after installing the extension through Copilot App's extension sharing/install flow.

Build

The plugin directory is the installed product payload referenced by the Castia marketplace. Browser assets that the canvas serves must be committed under this directory so copilot plugin install and copilot plugin update receive a self-contained plugin.

After changing renderer source, rebuild the committed browser asset:

Push-Location plugins\foundry-agent-starter-kit
npm ci
npm run build
npm test
Pop-Location

CI runs the same build, checks the generated com.github.copilot\extensions\foundry-agent-playground\renderer\dist\playground-client.js asset is fresh, and fails if the committed plugin payload is stale.

Manual repo setup

Use this only when you want the prompts and skills committed to a scenario repo instead of installed as a plugin:

New-Item -ItemType Directory -Force .github\prompts, .github\skills
Copy-Item ..\castia\plugins\foundry-agent-starter-kit\prompts\*.prompt.md .github\prompts\
Copy-Item ..\castia\plugins\foundry-agent-starter-kit\skills\* .github\skills\ -Recurse

Use

1. Open a scenario repo in Copilot App.
2. Ask Copilot to build a Foundry agent for that repo.
3. Open Foundry Agent Playground.
4. Click Start local. If the repo has no project endpoint yet, the canvas opens its in-canvas endpoint dialog, then saves non-secret derived values into gitignored local .env files and starts the agent.
5. Check readiness before sending a prompt. The Playground discovers the selected agent's supported protocols and exposes a protocol toggle for Responses, Activity, and Invocations when endpoints are available. Activity Protocol testing posts Bot Framework Activities and captures local connector egress so replies, typing, reactions, updates, and deletes render in the transcript instead of appearing as a bare 200 ack. Agent answers can include fenced mermaid blocks. The committed browser asset bundles Mermaid for selected safe diagram families (flowchart/graph, sequenceDiagram, stateDiagram, classDiagram, and erDiagram) and sanitizes the returned SVG before insertion. Mermaid init/config directives, raw HTML labels, interactive callbacks/links, and scriptable URLs are disabled. Unsupported, oversized, or failed diagrams fall back to the existing escaped source view or the safe flowchart renderer, so the original Markdown remains available for copy/export.
6. When Copilot drives or validates the Playground, it must focus the same open canvas instance and call its canvas actions (set_target when needed, health_check, set_protocol, send_response, send_activity, send_invocation, get_protocol_state, get_transcript_state) so the side-panel transcript and operation log update for the user. Do not use Playwright, browser navigation, or direct canvas URL automation for Playground smoke, layout, or collaboration validation; those paths do not exercise the shipped side-panel canvas.
7. If the Copilot app or extension process restarts, the Playground restores safe session-scoped state from its saved canvas snapshot: selected agent, target/protocol, non-secret Foundry metadata, hosted discovery, transcript, and completed activity/operation history. It intentionally resets local process state, active operations, raw logs, prompts, and readiness; click Start local or run health_check again to verify current runtime state.
8. Deploy or publish only after explicit approval.

Runtime storage and updates

Treat the installed plugin directory as immutable product payload. The Playground serves committed browser assets from the plugin folder, but runtime assets are cached in memory after first read and runtime state is written outside the install directory under %USERPROFILE%\.copilot\plugin-data\foundry-agent-starter-kit, with legacy session snapshots still readable from Copilot session storage. Local agent, azd, and .env operations run against the selected workspace agent root, not the installed plugin folder.