Skip to content

Configuration & secrets

Two YAML files at the project root drive an app. load_config() runs once at bootstrap and becomes the active in-memory store.

  • application.yaml — application configuration (app metadata, model, graph, server, custom sections).
  • env.yaml — runtime environment variables, exported into os.environ (existing values win unless override=True). Nested keys flatten to UPPER_SNAKE (openai.api_key → OPENAI_API_KEY).
from langstitch import load_config

cfg = load_config()          # loads env.yaml then application config
print(cfg.name, cfg.get("server.port"))

Example application.yaml

app:
  name: my_agent
  version: 0.1.0
  description: Support agent built with LangStitch.

model:
  provider: openai          # passed to LangChain init_chat_model
  name: gpt-4o-mini
  temperature: 0.2

server:
  host: 0.0.0.0
  port: 8000

http:
  timeout: 30               # default for get_http_client() (no service)

external_services:          # see External services
  billing:
    serverUrl: https://api.billing.com
    basePath: /v1
    propagate_headers: [x-request-id, authorization]
    auth:
      type: bearer
      token: ${BILLING_TOKEN}

Reading config with JSON-path

At startup load_config() parses the application config once into an in-memory object (the runtime store). Use get_config(path) with a JSON-path-lite syntax (dotted keys, [index], optional leading $):

from langstitch import get_config

get_config()                                    # whole AppConfig (cached)
get_config("server.port")                       # -> 8000  (scalar)
get_config("model")                             # -> {...} (nested object)
get_config("external_services.payments.auth.type")
get_config("items[0].name")                     # array index (negatives allowed)
get_config("missing.key", default="fallback")   # safe default
get_config("server", as_json=True)              # -> '{"host": ...}'  (JSON string)

Precompiled config for fast startup

If you keep the config as application.json it loads directly (no YAML→JSON conversion) and takes precedence over application.yaml. Precompile once:

langstitch compile           # application.yaml -> application.json
langstitch get server.port   # resolve a path from the CLI

Both server decorators accept properties= to pin the config file loaded at startup (relative to the project root, or absolute). When omitted, discovery is used (application.json preferred, else application.yaml):

@langstitch_graph_server(name="api", properties="application.yaml")   # pin YAML
class Server: ...

@langstitch_mcp_server(protocol="stdio")   # default: application.json then yaml
class MCPServer: ...

Typed config with @configuration

Bind a section of the config to a dataclass and get type-coerced values:

from dataclasses import dataclass
from langstitch import configuration

@configuration(section="server")
@dataclass
class ServerConfig:
    host: str = "0.0.0.0"
    port: int = 8000

# after load_config(): values are bound + type-coerced
cfg = ServerConfig._langstitch_instance   # ServerConfig(host="0.0.0.0", port=8000)

Secrets discipline

Never commit real secrets. Keep env.yaml out of version control (the scaffold gitignores it) and inject secrets through your platform/orchestrator in production. Use ${ENV_VAR} interpolation in application.yaml so the file references secrets without containing them.