Docs

Quickstart

Build your first Orchet agent.

This guide builds a small Weather agent. The agent is developer-hosted: you deploy it, own its provider API keys and data, and expose a contract Orchet can review and invoke.

0. Create an account and developer key.

Sign in at /developer, then create a CLI key at /developer/keys. The token is shown once, so put it in your shell or CI secret store.

SHELL

export ORCHET_DEVELOPER_TOKEN=orchet_dev_...
export ORCHET_CONTACT_EMAIL=you@example.com

Lifecycle.

Create account -> create developer key -> scaffold agent -> deploy agent -> submit manifest -> review -> approval -> users connect from chat. The contract you publish is what Orchet uses at runtime.

Deploy lifecycle

Build → publish → operate

DeveloperOrchet runtimeUser

01

Create key

/developer/keys

Generate ORCHET_DEVELOPER_TOKEN.

02

Build locally

orchet-agent init

Scaffold a Next.js agent with the SDK.

03

Deploy

HTTPS endpoints

Manifest + OpenAPI + health are public.

04

Submit manifest

POST /marketplace/submissions

Trust checks run inline (sync).

05

Review + approval

Orchet reviewer

Scopes + contract + runtime listing.

06

Connect from chat

user asks for capability

Connect card → OAuth → ready.

1. Scaffold.

The CLI creates a Next.js app with manifest, OpenAPI, health, and tool routes already wired.

SHELL

npx create-orchet-agent init weather-demo
cd weather-demo
npm install
orchet-agent dev

TEXT

app/
  .well-known/agent.json/route.ts
  health/route.ts
  openapi.json/route.ts
  tools/<tool>/route.ts
lib/
  manifest.ts
  openapi.ts
  vendor-client.ts
  auth.ts

2. Implement a tool.

Tools are plain HTTP routes. Validate the JSON body, call your provider or database, then return structured JSON. Orchet will validate model-generated arguments before this route is called.

TS

// app/tools/get_forecast/route.ts
export async function POST(req: Request): Promise<Response> {
  const body = await req.json().catch(() => null);
  const city = typeof body?.city === "string" ? body.city.trim() : "";

  if (!city) {
    return Response.json(
      {
        error: {
          code: "invalid_input",
          message: "city is required",
          retryable: false,
        },
      },
      { status: 400 },
    );
  }

  return Response.json({
    summary: `Partly cloudy in ${city}.`,
    temperature: 22,
    units: "C",
  });
}

3. Declare manifest and OpenAPI.

The manifest tells Orchet who the agent is. OpenAPI tells Orchet which operations are callable tools and what input is valid.

TS

// lib/manifest.ts
export const manifest = defineManifest({
  agent_id: "weather-demo",
  version: "0.1.0",
  domain: BASE_URL,
  display_name: "Weather Demo",
  one_liner: "Current conditions and forecasts for any city.",
  intents: ["weather", "forecast", "rain"],
  openapi_url: `${BASE_URL}/openapi.json`,
  health_url: `${BASE_URL}/health`,
  connect: { model: "none" },
  capabilities: {
    sdk_version: "0.6.0",
    supports_compound_bookings: false,
    implements_cancellation: false,
  },
});

YAML

paths:
  /get_forecast:
    post:
      operationId: weather_get_forecast
      summary: Get a forecast for a city.
      description: Use when the user asks about weather, rain, or temperature.
      x-orchet-tool: true
      x-orchet-requires-confirmation: false
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [city]
              properties:
                city:
                  type: string
                  description: City name, such as Tokyo or Chennai.
                units:
                  type: string
                  enum: [metric, imperial]

4. Validate and deploy.

Localhost-only agents cannot pass review. Deploy to an HTTPS host and make the three discovery URLs public.

SHELL

orchet-agent validate

ORCHET_AGENT_BASE_URL=https://weather-demo.example.com npm run build

curl -fsS https://weather-demo.example.com/.well-known/agent.json
curl -fsS https://weather-demo.example.com/openapi.json
curl -fsS https://weather-demo.example.com/health

orchet-agent validate \
  --manifest-url https://weather-demo.example.com/.well-known/agent.json

5. Submit to Orchet Store.

You can submit from the developer portal or CLI. The default SDK/API path is hosted-first: Orchet fetches your manifest, OpenAPI, and health URL, then stores the normalized agent contract for review.

SHELL

ORCHET_DEVELOPER_TOKEN=... orchet-agent submit \
  --manifest-url https://weather-demo.example.com/.well-known/agent.json \
  --openapi-url https://weather-demo.example.com/openapi.json \
  --health-url https://weather-demo.example.com/health \
  --contact-email developer@example.com

orchet-agent status <submission_id>

Verified and official releases can also attach an advanced signed bundle, but a bundle is no longer required for a hosted SDK/API submission.

The guided UI lives at /developer/marketplace/new.

6. Test from chat.

Once approved, users should discover the agent by asking for the capability. If OAuth is required, Orchet shows the connect card in the conversation, completes authorization, and resumes the request.

TEXT

Install weather-demo.
What's the weather in Tokyo tomorrow?
Will it rain in Chennai this weekend?

Need the deeper contract rules?

Read the manifest, OpenAPI, and testing references before submitting a real provider integration.

Agent contract →