Atelier Agentic SDK

Put an Atelier AI agent in the decision path of your existing code. The agent can observe, allow, deny, or modify the payload of an API call, a DB write, or any function call — so you can agentify a legacy codebase one call site at a time.

This repo holds the official client SDKs in two languages:

Package	Language	Install	Docs
@atelier/agentic	Node / TypeScript (18+)	npm install @atelier/agentic	node/README.md
atelier-agentic	Python (3.9+)	pip install atelier-agentic	python/README.md

Both packages expose the same surface — pick the one that matches your stack.

What it does

• guard(action, payload) — ask the agent for a verdict and apply it inline. deny throws/raises, modify returns a new payload, allow returns the original.
• decide(action, payload) — get the verdict without applying it (inspect decision, reason, confidence, changed).
• wrap / @intercept — wrap a function so its payload argument is guarded before it runs.
• installFetch / install_requests — auto-instrument outbound HTTP so JSON bodies are guarded.
• emit(event, payload) — fire-and-forget an application event; Atelier runs whatever server-side workflows match it (each picks its own agent).
• trigger(event) — run a full agent turn for an event; the agent reacts through its own tools.

At a glance

# Python
from atelier_agentic import AtelierClient
atelier = AtelierClient(agent_id=12, api_key="ate-...", mode="enforce")

order   = atelier.guard("db.update", order, mutable_fields=["status"])   # decide + apply
verdict = atelier.decide("http.post", body, schema=ORDER_SCHEMA)         # inspect only

@atelier.intercept("fn.charge", mutable_fields=["amount"])               # guard a function
def charge(payload): return gateway.charge(payload)

atelier.emit("todo.completed", {"todos": todos})                         # fire-and-forget event
summary = atelier.trigger("todo.completed", context={"todos": todos})    # full agent turn

// Node / TypeScript
import { AtelierClient, wrap } from "@atelier/agentic";
const atelier = new AtelierClient({ agentId: 12, apiKey: "ate-...", mode: "enforce" });

const order   = await atelier.guard("db.update", order, { mutableFields: ["status"] });  // decide + apply
const verdict = await atelier.decide("http.post", body, { schema: ORDER_SCHEMA });        // inspect only

const charge  = wrap(atelier, "fn.charge", (p) => gateway.charge(p), { mutableFields: ["amount"] });

await atelier.emit("todo.completed", { todos });                                          // fire-and-forget event
const summary = await atelier.trigger("todo.completed", { context: { todos } });          // full agent turn

Each method is documented in full in the per-language READMEs linked above.

Modes (roll out safely)

mode	behaviour
observe	never changes anything — returns the original payload (shadow logging)
suggest	returns the original payload; the verdict is available via decide()
enforce	applies the verdict: deny throws/raises, modify returns the new payload

Start in observe, watch the verdicts in your Atelier traces, then graduate specific call sites to enforce.

Configuration

Both SDKs read the same environment variables (constructor options take precedence):

Variable	Purpose
ATELIER_API_KEY	API key (required)
ATELIER_BASE_URL	Atelier server URL (defaults to http://localhost:8000)
ATELIER_WORKSPACE_ID	Workspace to scope events/workflows to

Safety rails (enforced server-side)

• The agent may only change keys listed in mutableFields / mutable_fields (unset = any, empty = none).
• If a JSON schema is supplied, a modified payload that fails validation is reverted.
• Network/timeout errors fail open (return the original payload) unless disabled.
• Every decision is recorded in your Atelier traces.

The Atelier platform

These SDKs are clients for Atelier, a full-stack AI agent orchestration platform (agent builder, multi-agent workflows, tool integrations, memory, and observability).

• Main project: https://github.com/hiwcode/atelier
• Documentation: https://ai.gethowitworks.com/docs

License

MIT — see the individual package manifests.