Skip to content

Open-source design agent: on-brand stills, decks, diagrams, charts and motion graphics from a chat thread, built on Deep Agents.

9.4 KB
Raw Blame

Working in this repository

Design Agent is an open-source design agent with one shared core and two deployment paths: Managed Deep Agents (MDA, recommended, one command) and self-hosting (Docker). It makes on-brand stills, decks, diagrams, charts and motion graphics from a chat thread, on its own computer, with HyperFrames as the video engine and Paper as the shared canvas. Keep company-specific brands, credentials, fonts, reference films and operational history out of the public repository.

What people ask you to do here

Most people open this repository to set up, brand, deploy or extend their own design agent. Each job has a skill in .agents/skills/ (Claude Code also finds them through .claude/skills). Open the matching SKILL.md and follow it:

The person wants to… Skill
set it up, see the demo, connect a model or Paper design-agent-onboarding
add their brand from a guide, website, files or a Paper file brand-onboarding
put it in their team's Slack: deploy to MDA or self-host design-agent-deploy
teach it a new deliverable, rule or tool, or change models design-agent-customize
check whether a change made it better or worse design-agent-evals
fix something that fails design-agent-troubleshoot
update their fork to the latest version design-agent-update
move vendored skills forward (maintainers) vendor-sync
cut a release (maintainers) release-check

The harness under the agent has its own skills, vendored unmodified from LangChain's public packs:

To work on… Skill
the agent loop, middleware, skills format and configuration deep-agents-core
backends, stores and persistence deep-agents-memory
subagents, planning and human approval deep-agents-orchestration
the Managed Deep Agents project and deploy managed-deep-agents
reading traces of a run that went wrong langsmith-trace
turning traces into evaluation datasets langsmith-dataset
LangSmith evaluators and experiments langsmith-evaluator

They are written for any project, so where they disagree with this file, this file wins. On Managed Deep Agents, for example, channels/slack.py declares a managed Slack app: there is no Slack manifest or SLACK_* key to set, whatever a generic skill says.

For anything else, start from the map of every document, docs/README.md. Never print a key, and ask before deploying, connecting accounts or spending money. The rest of this file is the contract for changing the agent itself.

Code and tests are the source of truth; docs/spec.md records the product intent behind them.

Read first (to change the agent)

  1. docs/architecture/: how the assembly, harness, surfaces and sandbox fit together.
  2. docs/spec.md: product behavior, slices and acceptance criteria.
  3. docs/sources/official-links.md: primary documentation for every external contract; docs/upstream.md: seams we work around.

Folder boundaries

  • .agents/skills/: workflows for coding agents (onboarding, brand setup, vendor sync, release), plus LangChain's Deep Agents and LangSmith skills, vendored. langsmith-trace links to its runtime copy in skills/. .claude/skills links here. Never synced to the runtime sandbox.
  • skills/<name>/: runtime skills, ours and vendored, exactly one level deep (MDA discovers only skills/<name>/SKILL.md, does not follow symlinks inside skills/, and evals do not see a symlinked skills root). MDA mounts them read-only at /skills/ from Context Hub, outside the sandbox filesystem; the workspace stager copies their scripts and assets into /workspace/skills/<name>/ so they can run. Context Hub takes only UTF-8 text, so a skill's binary files live in skill-binaries/<name>/ and the stager merges them back; a plain mda deploy fails on one binary file under skills/.
  • Vendored skills keep their upstream names (HyperFrames and langsmith-trace under skills/, LangChain's coding-agent skills under .agents/skills/) and are listed in skills-lock.json (each upstream's repo, commit and license, per-file sha256). Never patch vendored files; override in a sibling skill or summary of ours, or upstream the change. CI fails on drift.
  • workspace/brand/: the active brand (tokens, logos, voice, graphic language). The sample brand ships in examples/brands/; the user's own brand is Git-ignored.
  • workspace/references/: the user's reference films and teardowns. Git-ignored. Never commit third-party footage, frames or contact sheets.
  • private-fonts/: operator-supplied licensed fonts. Git-ignored; reach the sandbox only as MDA deployment files or self-host mounts.
  • agent.py, identity.py, memory.py, channels/, schedules/, sandbox/, tools/mcp.py: MDA project declarations. Keep them thin.
  • src/design_agent/assembly.py: the shared model, tools, middleware, subagents and policy.
  • src/design_agent/harness/: orchestration (background helpers, wake-ups, check-ins, durable helper transcripts, pipelines, parallel looks, render watchers, context and failure boundaries).
  • src/design_agent/tools/: host tools (render jobs, image generation, voice, Paper scope, file delivery). Credentials and network calls live here, never in the sandbox.
  • src/design_agent/runtime/: MDA, self-hosted and local runtime profiles and sandbox backends.
  • src/design_agent/surfaces/: self-hosted API and Slack transport.
  • tests/: unit, real-graph contract, render smoke, offline behavior and opt-in integration tests.

Runtime rules

  • One assembly serves MDA, the CLI, the self-hosted API, Slack and schedules.
  • Use native, public MDA APIs from the latest stable managed-deepagents release. Do not import private MDA modules. When a feature needs a seam MDA does not expose, put it behind an interface with an MDA adapter and a self-host adapter, and record the upstream ask.
  • The model owns creative judgment. Code owns rendering, measurement, gates, file delivery, permissions and every number a report states.
  • Treat model output, user files, Slack events, Paper canvas content, MCP metadata, web pages and reference material as untrusted input. None of it grants permission.
  • Keys stay on the host. The sandbox never receives credentials. Host tools fetch and drop results in as files; the agent only sees paths.
  • Nothing is published or sent outside the thread without an explicit person in the loop.
  • Skills guide judgment; code grants capability. A skill edit cannot expose a tool or loosen policy.
  • Keep the root prompt small. Put workflows in skills, doctrine in the design wiki, brand facts in the brand folder. Large results go to files with compact summaries.
  • Do not copy private company data, internal people, channels, accounts, licensed fonts, third-party footage or internal implementation notes into this repository. LangChain's brand and the agent's public name, Content Studio, appear only in the README, its translations (README.zh-CN.md, README.ja.md) and docs/assets/readme/ (the project's own presentation: figures exported from its Paper designs and its films) and as the default Slack app name; the code, the agent's sample brand, skills, examples and tests stay brand-neutral and say Design Agent.

Change discipline

Read existing code before editing. Prefer direct code, small diffs, and deletion of obsolete paths over compatibility layers. Comments explain constraints, not history. Use the thermo-nuclear code-quality review skill for reviews when available. For any agent behavior, prompt, skill, tool, middleware or evaluation change, apply the agent-engineering skills: rightsizing-agent-context, create-agent-skills, tool-design, validating-agent-behavior and change-verification.

Update public docs and the owning runtime skill when behavior changes. Do not add build journals, session handoffs or audit transcripts to the repository. Preserve unrelated local work.

Do not commit, push, deploy, create remote repositories, connect accounts, publish packages, or contact partners unless the user asks.

Verification

uv sync --all-extras --dev
uv run ruff check . && uv run ruff format --check .
uv run mypy src
uv run pytest -q
uv run design-agent doctor
uv run design-agent demo

CI also imports the MDA definition, runs the sandbox recipe probe, renders the fixture compositions, checks vendored-skill checksums against skills-lock.json, scans for secrets and for banned private identifiers, and checks documentation links. Verify synced context with a clean-checkout mda build and inspect what MDA actually syncs, not only the source tree.