create-agent-python

Files (2)

• REFERENCE.md
• SKILL.md

SKILL.md (first lines)

# Create a Python Agent Application

## Overview

This skill describes how to create a durable AI agent application in Python. Two paths are supported:

- **Native** — the [`dapr-agents`](https://github.com/dapr/dapr-agents) SDK. This is the Dapr Agents framework proper; it is Python-only. Its `DurableAgent` runs on Dapr Workflow, reaches the LLM through a Dapr conversation component, and keeps the conversation of each run in a Dapr state store.
- **Framework wrappers** — the [`diagrid`](https://pypi.org/project/diagrid/) distribution, which runs an agent you have already written in another framework (LangGraph, CrewAI, Strands, …) on Dapr Workflow so that each node / LLM call / tool call becomes a durable activity. One distribution, one extra per framework. `diagrid` is BUSL-1.1 licensed (with an Additional Use Grant, converting to Apache-2.0 on its Change Date) and its runners send one anonymous usage event per process; the generated README says both (see `REFERENCE.md`). `dapr-agents` is Apache-2.0.

Single agent or coordinator + specialists, either way. With wrappers, the coordinator is a native `dapr-agents` agent that dispatches to wrapper specialists through the agent registry (a **mixed** project); wrappers that only exchange events over pub/sub are the event-driven variant.

## Execution Order

You MUST follow these phases in strict order:
1. **Check specification** — Check if the user specified what needs to be built.
2. **Check optional tools** — Check whether the Diagrid Dapr Dev Dashboard is installed and remember the result. Never stop, ask or install for this.
3. **Project Setup** — Create all files and folders.
4. **Verify** — Verify that the project builds.
5. **Create README.md** — Create a readme that summarizes what is built and how to run & test the application. Do not provide instructions at the end of this phase.
6. **Show final message** — Your LAST output MUST be EXACTLY the message defined in the `## Show final message` section: the closing sentence followed by the Dev Dashboard recommendation. Do NOT add any other text, summary, or commentary.

## Check specification

If you don't have enough context what to build, ask the user the following clarifying questions one by one using an interview style:

1. What is the purpose of the agent (or agent team)? This becomes the agent's `role` and `instructions`.
2. Topology: a single agent, or a coordinator + N specialists? For wrappers, coordinator + specialists means a native coordinator with wrapper specialists; offer the event-driven pub/sub variant only if the user asks for event-driven agents.
3. Framework: `dapr-agents` (native, the default) or one of the `diagrid` wrapper extras. **Resolve the wrapper list at this point rather than reciting one** — see "Resolving the framework list" below.
4. Pattern (only if Q3 selected native `dapr-agents` AND Q2 selected single-agent): `augmented-llm` (default), `prompt-chaining`, `routing`, `parallelization`, `orchestrator-workers`, or `evaluator-optimizer`. **Skip this question entirely** if the user picked a wrapper extra — those frameworks define their own agent loop and the pattern concept does not apply.
5. Tool definitions: name, purpose, and argument schema for each tool the agent should expose.
6. LLM provider: OpenAI, Anthropic, Google Gemini, or local Ollama. Native `dapr-agents` routes this through a Dapr conversation component; wrappers let the wrapped framework call the provider directly with an API key from the environment, and most extras bundle only an OpenAI client (see "LLM provider (wrappers)" in `REFERENCE.md`).
7. Include observability by default? (**recommended: yes**, for both paths.)
8. Project name — used as the folder name. Don't use spaces.

### Resolving the framework list

The wrapper extras live in one place — the `[project.optional-dependencies]` table of [`diagridio/python-ai`'s `pyproject.toml`](https://github.com/diagridio/python-ai/blob/main/pyproject.toml) — and PyPI republishes that table verbatim as the distribution's `provides_extra` metadata. Read it instead of hardcoding it:

```shell
curl -s https://pypi.org/pypi/diagrid/json | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['info']['version']); print('\n'.join(e for e in d['info']['provides_extra'] if e not in ('agent-core','all','identity','holmesgpt')))"
```

Offer the user the extras that command prints. `agent-core` is the shared base every extra pulls in, `all` is a meta-extra and `identity` is a runtime helper — none is a framework choice. `holmesgpt` is filtered out because `diagrid[holmesgpt]` does not resolve from PyPI; if the user asks for HolmesGPT, tell them it is not supported for scaffolding and offer another framework.

If the command fails (no network), fall back to the snapshot in `REFERENCE.md` and **tell the user it is a snapshot with a date on it**, so a missing framework is understood as staleness rather than as unsupported.

## Prerequisites

The following must be installed by the user before this skill can run:

- [Python](https://www.python.org/downloads/) `>=3.11,<3.14` — the bound both `dapr-agents` and `diagrid` declare
- [uv](https://docs.astral.sh/uv/getting-started/installation/) (Astral)
- [Docker](https://www.docker.com/products/docker-desktop/) or [Podman](https://podman.io/docs/installation)
- [Dapr CLI](https://docs.dapr.io/getting-started/install-dapr-cli/) (version 1.18+)
- At least one LLM provider env var (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY`) or a local [Ollama](https://ollama.com/) instance

Additional runtime dependencies (handled during project setup):

- Python package: `dapr-agents>=1.0.9` (native, and the coordinator of a mixed project) **or** `diagrid[<extra>]>=0.5.3` (wrappers). These are floors, not pins — the exact resolved set is captured in `uv.lock` during Verify. See `REFERENCE.md`.

Optional, for inspecting workflow runs locally:

- Optional: the [Diagrid Dapr Dev Dashboard](https://github.com/diagridio/dev-dashboard) for inspecting workflow runs locally. The skill only checks whether it is installed (see `## Check optional tools`); it never installs it and never stops without it.

## Check optional tools

Check once whether the optional [Diagrid Dapr Dev Dashboard](https://github.com/diagridio/dev-dashboard) is installed by following the **Check** section of [`../dapr-shared/dev-dashboard.md`](../dapr-shared/dev-dashboard.md) (`diagrid-dev-dashboard --version`). Remember the result (`DevDashboardInstalled`) for the final message. This check never stops the skill: do not ask the user about it, do not install anything, and continue with the next step whether or not the dashboard is installed.

## Project Setup

Create the project root folder inside the current location where the terminal is open:

```shell
mkdir <ProjectRoot>
cd <ProjectRoot>
```

The <ProjectName> should start with the <ProjectRoot> and end with `-agent`: <ProjectRoot>-agent.

### Folder structure (single agent)

```
<ProjectRoot>/
├── .gitignore
├── dapr.yaml
├── local.http
├── docker-compose.observability.yaml    # (if observability enabled)
├── observability/                        # (if observability enabled)
├── resources/
│   ├── agent-workflow.yaml
│   ├── llm-provider.yaml                 # (native only — see "Resources per flavor")
│   └── tracing.yaml                      # (if observability enabled)
└── <ProjectName>/
    ├── pyproject.toml
    ├── main.py
    ├── tools.py
    └── logging_config.py                 # (if observability enabled)
```

### Folder structure (coordinator + specialists)

```
<ProjectRoot>/
├── .gitignore
├── dapr.yaml
├── local.http
├── docker-compose.observability.yaml    # (if observability enabled)
├── observability/                        # (if observability enabled)
├── resources/
│   ├── agent-workflow.yaml
│   ├── agent-pubsub.yaml                 # (native only — see "Resources per flavor")
│   ├── agent-registry.yaml
│   ├── llm-provider.yaml                 # (native and mixed — see "Resources per flavor")
│   └── tracing.yaml                      # (if observability enabled)
├── coordinator/                          # native dapr-agents, also in a mixed project
│   ├── pyproject.toml
│   ├── main.py
│   ├── tools.py
│   └── logging_config.py              # (if observability enabled)

From diagrid-labs/dapr-skills, MIT.

More from diagrid-labs/dapr-skills