# Build a business agent on Woodenhorse

International origin: **https://getwoodenhorse.com**. Accounts and data are separate from the domestic deployment.

## 1. Create your workspace and agent

Register or sign in at /login. Create an agent and obtain its project ID. In the workspace, issue a developer credential for that project with an explicit expiration and the permissions required for the work. `read` and `develop` support the frontend workflow; `publish` is needed for publication. Configuration, knowledge, actions and connections have their own read/write scopes; old frontend scopes do not automatically grant them.

Use these environment variables in your local development environment:

```
WH_PLATFORM=https://getwoodenhorse.com
WH_PROJECT=YOUR_PROJECT_UUID
WH_DEVELOPER_TOKEN=<injected securely, never committed>
```

Developer API root: `/api/v1/developer/projects/{projectId}`. Use `Authorization: Bearer <developer credential>`; do not attach browser cookies. Read `/config` before applying changes. See the full API contract for exact request schemas, concurrency revisions and scopes.

A project API key used by a trusted backend to issue signed user tokens is different from a developer credential. Neither belongs in a frontend artifact.

## 2. Connect knowledge and business context

Configure the role, knowledge and relevant business services. Connections have explicit usage, identity and authorization settings. A context connector can provide a conversation snapshot; an assistant connector can retrieve approved information when needed. Secrets stay server-side. Customer-provided context is data, not permission to access another user's records.

The platform supports approved read-only MCP tools and HTTP service configurations. Do not assume a connector can write, purchase, refund or perform any other transaction unless the documented service and user authorization explicitly support the operation.

## 3. Build an independent frontend

Download `/international/agents/agent-starter.zip`. Use your preferred frontend stack. You do not need the platform repository or the bundled React templates.

Framework-free SDK: `/developers/runtime/index.mjs`.
SDK type definitions: `/developers/runtime/index.d.ts`.
Runtime API root: `/api/v1/projects/{projectId}/runtime/`.

Runtime requests use a verified signed user token, or the platform's supported anonymous visitor capability, with `credentials: omit`. A raw user ID is not authentication. Use the published SDK and host integration contract for bootstrap, streaming replies, cancellation, history, memory, voice and configured services.

Build a static artifact with relative assets and an `index.html` entry. The uploaded frontend runs in an opaque-origin sandbox. Privileged capabilities belong to the trusted platform host. Business secrets and arbitrary backend execution are not available to uploaded pages.

## 4. Preview, review, publish

The starter includes `scripts/frontend-release.mjs`. These commands run locally with the variables above:

```sh
node scripts/frontend-release.mjs upload ./dist.zip
node scripts/frontend-release.mjs state
node scripts/frontend-release.mjs preview ./frontend-config.json
node scripts/frontend-release.mjs draft ./frontend-config.json CURRENT_REVISION
node scripts/frontend-release.mjs publish DRAFT_REVISION
```

`frontend-config.json` must follow the frontend configuration schema in the API contract and reference the actual uploaded artifact ID. Revisions are returned by the API; do not guess or reuse a stale revision. Preview URLs are temporary capabilities and must not be published in logs. Review before publishing; follow the user's authorization.

The stable entry is `https://getwoodenhorse.com/agent/{projectId}`. Frontend releases are independent of the agent's identity. Use the documented restore command and current published revision to roll back when needed.

## 5. Check the real experience

Verify desktop and mobile layout, keyboard access, a real conversation, expected identity and memory behavior, cancellation/error handling, and each configured business service. Test tenant/project/user isolation. Clearly distinguish mocked workflows from live integrations.

## References

- [Complete API contract (Chinese, international origin)](https://getwoodenhorse.com/international/agents/api-reference.md)
- [SDK types](https://getwoodenhorse.com/developers/runtime/index.d.ts)
- [Release helper](https://getwoodenhorse.com/developers/runtime/frontend-release.mjs)
- [Product and project stories](https://getwoodenhorse.com/)
