---

description: Understand a generated LangStitch Python project: application configuration, graph modules, node implementations and environment files.

Project structure

langstitch new generates a conventional layout where every concept gets its own package. A single import app wires up the whole application.

my-agent/
  application.yaml     # application config (or precompiled application.json)
  env.yaml             # runtime environment variables (gitignored in real projects)
  pyproject.toml       # depends on langstitch; your package is "app"
  app/
    __init__.py        # imports submodules so decorators register on import
    graphs/            # @graph — main graph (main.py) + subgraphs
    nodes/             # @graph_node — node handlers (state -> dict)
    skills/            # @skill
    guardrails/        # @input_guardrail / @output_guardrail
    policies/          # @business_policy
    personas/          # @persona
    tools/             # @tool
    agents/            # @worker_agent
    mcp/               # @langstitch_mcp_server + @mcp_tool/resource/prompt
    config.py          # @configuration — typed application.yaml sections
    state.py           # graph state schema (TypedDict)
    main.py            # @langstitch_graph_server — server + bootstrap()
  tests/               # smoke tests

How registration works

Decorators record a spec on a process-global registry at import time. app/__init__.py imports every submodule, so a single import app wires up the whole application.

# app/__init__.py
from . import graphs, nodes, skills, guardrails, policies
from . import personas, tools, agents, mcp, config

Keep decorated modules import-safe

Don't do network or file I/O at module scope. Registration should be cheap and deterministic so import app stays fast — the actual work happens when a node runs, not when the module imports.

The two config files

File	Purpose
application.yaml	Declarative app configuration (app metadata, model, graph, server, custom sections). Precompile to application.json for production.
env.yaml	Runtime environment variables exported into os.environ at startup. Nested keys flatten to UPPER_SNAKE (openai.api_key → OPENAI_API_KEY). Keep it out of version control.

See Configuration & secrets for the full model.

Next: Decorators