SDK/API contract

Agent manifest.

The manifest is the first stable document Orchet reads for SDK/API agents. It identifies the agent, points to OpenAPI and health endpoints, and declares how users connect.

Where it lives.

Serve the manifest at /.well-known/agent.json from the same HTTPS deployment that serves the agent's tools.

TEXT

https://weather-demo.example.com/.well-known/agent.json
https://weather-demo.example.com/openapi.json
https://weather-demo.example.com/health
https://weather-demo.example.com/tools/get_forecast

Required fields.

Keep the first version small and explicit. One well-described read-only tool is better than ten vague actions.

Field	Purpose
agent_id	Stable lowercase id, 3-32 chars, globally unique.
version	Semver for behavior and schema changes.
display_name and one_liner	User and reviewer-facing catalog copy.
intents	Natural labels the planner uses for routing.
openapi_url	Canonical tool schema document.
health_url	Public health probe used by trust checks.
connect	none, oauth2, or orchet_user_jwt.
capabilities	SDK version, compound booking support, and cancellation support.

Minimal manifest.

This is the shape generated by the CLI template. OAuth client secrets are never embedded in the manifest; only environment variable names are declared.

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"],
  example_utterances: ["Will it rain in Tokyo tomorrow?"],
  openapi_url: `${BASE_URL}/openapi.json`,
  health_url: `${BASE_URL}/health`,
  ui: { components: [] },
  sla: {
    p50_latency_ms: 800,
    p95_latency_ms: 2500,
    availability_target: 0.99,
  },
  pii_scope: ["name", "email"],
  supported_regions: ["US"],
  connect: { model: "none" },
  capabilities: {
    sdk_version: "0.6.0",
    supports_compound_bookings: false,
    implements_cancellation: false,
  },
});