English | 简体中文

Atelier is a lightweight agent harness for building professional, design-oriented AI agents. It is not a thin chat wrapper around a model API. It is a controllable runtime foundation where agents can understand a request, plan work, call tools, persist context, request human approval, spawn sub-agents, and stream the execution process back to the user in real time.

The current release focuses on the general-purpose runtime layer. It is suitable as the foundation for design agents, research workspaces, local automation assistants, and multi-agent systems that need predictable execution, tool governance, persistent sessions, and observable long-running work.

• Web, CLI, and API entry points: use the browser workspace, run an interactive local CLI, or integrate through REST and WebSocket APIs.
• Long-running agent runtime: a ReAct-style loop supports multiple model rounds, tool execution, cancellation, recovery, and final response generation.
• Provider abstraction: OpenAI-compatible and Anthropic-style providers can be configured through config.yaml and environment variables.
• Extensible tool system: built-in tools cover file operations, search, shell and PowerShell, web search, web fetch, image generation/editing, planning, memory, background tasks, and sub-agent creation.
• Persistent sessions: SQLite-backed storage keeps messages, metadata, plans, memory entries, checkpoints, and parent-child session relationships.
• Approval and permission controls: high-risk tools can require user approval, and personas can restrict the tools available to a session.
• Personas, skills, and commands: reusable roles, procedures, and project commands are loaded from .myharness/.
• Context management: prompt caching and automatic compression help long sessions continue as context grows.
• Multi-agent collaboration: parent sessions can spawn sub-agents for research, planning, implementation, review, documentation, or other specialized roles.
• Runtime observability: the frontend can display model rounds, tool calls, tool results, plan changes, approval prompts, recovery events, and streamed state updates.

Atelier is designed for teams and researchers who need more than a single-turn assistant:

• Build agents for design research, visual production, critique, prototyping, and artifact-oriented workflows.
• Run local AI workspaces where agents can read and edit project files under controlled permissions.
• Explore multi-agent collaboration, interruptible execution, human approval, context compression, and resumable tasks.
• Integrate existing model gateways, MCP servers, internal tools, or design-specific services into one tool registry.
• Reuse the same backend runtime across a web workspace, CLI, and custom product interfaces.

The repository includes selected full-resolution design run packages under example_outputs/runs/. These examples are copied from local run outputs while keeping the working outputs/ directory ignored. Each package preserves the exported final/ folder, including the gallery page, generated images, research files, planning files, and critique records.

Images below use the original exported PNG files. The README only constrains display width so the source images remain available at full resolution in each case folder.

A cultural merchandise system inspired by Peking opera facial makeup, covering product overview, packaging, collectible details, and visual specification boards.

Open final package ? Open artifact gallery

Product system	Packaging	Series overview
Detail close-up	Lifestyle use	Cultural palette

A lab-oriented merchandise case for IDVX, showing how a research identity can become bags, notebooks, badges, and campus-use visuals.

Open final package ? Open artifact gallery

Tote hero	Tote detail	Notebook cover
Notebook spread	Badge system	Campus scene

A product concept for older adults living alone, covering the hero render, three-view form lock, home usage scenarios, interaction details, CMF, and form language.

Open final package ? Open artifact gallery

Hero render	Three-view	Bedroom scene
Interaction detail	CMF board	Form language

A visitor-center concept for Zhujiajiao ancient town, covering site relationship, zoning, circulation, section perspective, key interior moments, facade study, material-light strategy, and accessibility analysis.

Open final package ? Open artifact gallery

Site context	Zoning	Circulation
Entry hall	Facade	Material and light

A conference promotion system covering a main poster, key visual, typography hierarchy, color rules, social media adaptations, badge/lanyard, and presentation template.

Open final package ? Open artifact gallery

Main poster	Key visual	Type hierarchy
Social post	Badge and lanyard	PPT template

A campus-facing communication and merchandise system with bilingual posters, social cards, merch mockups, and moodboards.

Open final package ? Open artifact gallery

Logo poster	Chinese poster	English poster
Announcement card	Merch mockup	Moodboard

Atelier is organized into five runtime layers:

A typical task runs as follows:

1. The user sends a request from the Web UI, CLI, or API.
2. The engine assembles the system prompt, persona, skill descriptions, memory, plan state, and conversation history.
3. The model either responds directly or requests one or more tool calls.
4. Tool calls pass through the configured approval mode before execution.
5. Tool results are written back into the session and streamed to the frontend over WebSocket.
6. The engine continues for another model round when more work is required, or returns the final answer.

.
|-- api/                    # FastAPI REST and WebSocket server
|-- harness/                # Agent runtime, tools, storage, LLM providers
|   |-- engine/             # Main loop, state machine, compression, prompt cache
|   |-- tools/              # Built-in tools and execution layer
|   |-- storage/            # SQLite and in-memory backends
|   |-- llm/                # Provider abstraction and implementations
|   |-- mcp/                # MCP bridge and transports
|   `-- commands/           # Built-in and project command system
|-- static/                 # Browser frontend
|-- .myharness/             # Personas, skills, commands, transcripts
|-- tests/                  # Unit and integration tests
|-- cli.py                  # Interactive CLI entry point
|-- config.yaml             # Runtime configuration
|-- pyproject.toml          # Python package metadata
`-- README.md

• Python 3.11 or newer
• A model provider:
  • OpenAI-compatible Chat Completions API, or
  • Anthropic-compatible provider
• Optional: Serper or Brave Search API key for full web search
• Optional: image generation/editing endpoint for image_generate and image_edit

pip install -e ".[dev]"

Create a local environment file:

cp .env.example .env

Fill in the provider credentials you want to use. Example for the default OpenAI-compatible route:

OPENAI_HUB_API_KEY=your-api-key
OPENAI_HUB_BASE_URL=https://your-openai-compatible-endpoint/v1
OPENAI_HUB_MODEL=gpt-4o
HARNESS_DEFAULT_PROVIDER=openai-hub

For full web search:

SERPER_API_KEY=your-serper-key
BRAVE_SEARCH_API_KEY=your-brave-key

For image generation and editing:

DESIGN_IMAGE_API_KEY=your-image-api-key
DESIGN_IMAGE_BASE_URL=https://your-image-endpoint/v1
DESIGN_IMAGE_MODEL=gpt-image-2
DESIGN_IMAGE_ENDPOINT=https://your-image-endpoint/v1/images/generations
DESIGN_IMAGE_EDIT_ENDPOINT=https://your-image-endpoint/v1/images/edits
DESIGN_IMAGE_DEFAULT_SIZE=1024x1024

uvicorn api.rest:app --port 8000

Open:

http://localhost:8000

Avoid --reload for long-running or file-writing agent tasks. File changes can restart the server and interrupt the active session.

python cli.py
python cli.py --persona builder
python cli.py --provider openai-hub
python cli.py --question-mode question

Common CLI commands:

The main runtime configuration is stored in config.yaml.

config.yaml supports environment-variable expansion. Keep API keys and secrets in .env, not in source control.

Project-local behavior is configured under .myharness/:

.myharness/
|-- personas/       # Agent roles such as builder, planner, reviewer
|-- skills/         # Reusable procedural knowledge; each skill has SKILL.md
|-- commands/       # Project commands
`-- transcripts/    # Runtime transcripts

A persona defines an agent's role, system prompt, default provider, approval mode, and allowed tools. Typical roles include:

• builder: implementation and delivery
• planner: decomposition and task planning
• reviewer: quality review and risk identification
• researcher: source gathering and synthesis
• docs-writer: documentation writing

Skills capture reusable procedures. At session startup, the engine injects skill names and descriptions into the prompt. Full skill content is loaded only when the agent calls use_skill, keeping the prompt compact while still enabling specialized workflows.

Commands define project-level shortcuts for repeatable tasks. They can be exposed through the CLI or Web UI and reused as task templates.

The Web Workspace is backed by FastAPI and WebSocket events. It supports:

• Creating, restoring, switching, renaming, pinning, archiving, and deleting sessions.
• Selecting provider, persona, approval mode, and question mode.
• Viewing messages, tool calls, tool results, state changes, and runtime errors in real time.
• Expanding tool-call details to inspect what the agent actually did.
• Editing a historical user message and regenerating from that point.
• Viewing and editing project skills, personas, and runtime configuration.

Atelier supports two session-level question modes:

CLI example:

python cli.py --persona builder --question-mode question

REST example:

curl -X PATCH http://localhost:8000/sessions/{session_id}/mode \
  -H "Content-Type: application/json" \
  -d '{"question_mode": "question"}'

Common REST endpoints:

WebSocket events include tokens, messages, state snapshots, tool results, and question asked/resolved events. Frontends should treat the backend as the source of truth.

Atelier is a local research harness. It includes practical safety controls, but production or multi-user deployment requires additional review.

Built-in controls include:

• High-risk tools such as Shell and PowerShell can require human confirmation.
• Personas can restrict the tools available to a session.
• Tool outputs are capped to reduce context-overflow risk.
• Secrets are injected through environment variables.
• The web-fetch tool includes basic SSRF protection.
• Runtime state transitions are controlled by an explicit state machine.

Before exposing Atelier to untrusted users:

• Use least-privilege personas.
• Disable shell-like tools when they are not required.
• Run the service inside a controlled network.
• Add authentication, rate limits, and audit logging.
• Review access permissions for .env, the SQLite database, and generated artifact directories.

Run the full test suite:

pytest

Useful focused tests:

pytest tests/test_engine.py
pytest tests/test_tools.py
pytest tests/test_storage.py
pytest tests/test_streaming.py
pytest tests/test_question_mode.py

Count lines of code:

python scripts/loc.py

• .env.example covers required configuration; real .env is not committed.
• config.yaml default provider matches the documented environment variables.
• High-risk tools are listed in tools.confirm_tools.
• The Web UI starts with uvicorn api.rest:app --port 8000.
• The CLI starts with python cli.py --persona builder.
• Core tests pass.
• README image links, commands, and endpoint descriptions match the current code.
• The license file is present and appropriate for release.

• Design-domain tools for asset research, visual analysis, layout critique, and brand-system generation.
• Richer artifact workflows for briefs, design batches, critique records, and final export packages.
• More granular permissions by directory, tool, provider, and session.
• A more capable Web UI with runtime traces, file previews, artifact galleries, and sub-agent views.
• Better memory management for project preferences, long-term constraints, and editable memory.
• Production deployment support: authentication, multi-user isolation, queues, audit logs, and monitoring.

Why does startup report that a provider does not exist?

Check the provider names in config.yaml and make sure .env points HARNESS_DEFAULT_PROVIDER to one of those names.

Why does web search return no useful results?

Without SERPER_API_KEY or BRAVE_SEARCH_API_KEY, web_search falls back to a limited DuckDuckGo instant-answer mode. Configure Serper or Brave for full web search.

Why should I avoid uvicorn --reload?

Agents may write files during a task. --reload watches file changes and can restart the server, interrupting the active session.

What should I do if a skill is not invoked automatically?

Check whether .myharness/skills/<skill-name>/SKILL.md has a clear description of when the skill should be used. You can also invoke it manually with /<skill-name>.

How can I make an agent session safer?

Set allowed_tools in the persona and disable unnecessary tools in config.yaml. Keep shell-like tools behind approval.

Atelier is an evolving research-oriented product foundation. The general agent runtime, tool system, persistent sessions, Web/CLI entry points, and basic multi-agent capabilities are implemented. Design-domain tooling, artifact management, permission hardening, and production deployment are still under active development.

Atelier is released under the MIT License.