Orchestrator

The orchestrator is the brain of AnyaSelf. It manages stateful Missions — agentic conversational tasks where a Vertex AI Reasoning Engine coordinates internal tools to search wardrobes, find commerce offers, prepare carts, and control browsers.

Agent Architecture

graph TB
  subgraph Orchestrator
    LLM["Vertex AI<br/>Reasoning Engine"]
    TOOLS["Tool Registry"]
    STATE["Mission State<br/>Machine"]
  end

  LLM --> TOOLS
  TOOLS --> W["wardrobe<br/>list_wardrobe"]
  TOOLS --> C["commerce<br/>search_commerce"]
  TOOLS --> CP["cartprep<br/>prepare_cart"]
  TOOLS --> HB["hyperbeam<br/>create_hyperbeam_session"]
  STATE --> AA["artifacts-audit"]

The agent is instantiated with the Vertex AI SDK:

agent = reasoning_engines.LangchainAgent(
    model=settings.vertex_model,
    tools=[search_commerce, list_wardrobe, prepare_cart, create_hyperbeam_session],
    system_instruction="You are ANYASELF, a high-end personal fashion assistant...",
)

Endpoints

Method	Path	Description	Auth
`POST`	`/api/v1/households/{id}/orchestrator/missions`	Start a new mission	JWT
`GET`	`/api/v1/households/{id}/orchestrator/missions/{mId}`	Get mission state + history	JWT
`POST`	`/api/v1/households/{id}/orchestrator/missions/{mId}/chat`	Send message, trigger agent reasoning turn	JWT
`POST`	`/api/v1/households/{id}/orchestrator/missions/{mId}/events`	Record typed client event	JWT
`POST`	`/api/v1/internal/hyperbeam/events`	Receive bridge events from Hyperbeam	`X-Internal-Token`

Create Mission

// POST /households/{id}/orchestrator/missions
{
  "mission_type": "STYLE",        // STYLE | POLL | CARTPREP | INTERACTIVE
  "initial_message": "Help me pick a spring outfit under $200"
}

Chat Turn

// POST /households/{id}/orchestrator/missions/{mId}/chat
{
  "message": "Show options under $120"
}

MissionView Response (returned by create, get, and chat endpoints):

{
  "mission_id": "msn_abc123",
  "household_id": "h_abc123",
  "owner_id": "usr_abc123",
  "mission_type": "STYLE",
  "state": "RUNNING",
  "history": [
    {
      "id": "msg_abc123def456",
      "role": "user",
      "content": "Help me pick a spring outfit under $200",
      "created_at": "2026-03-08T10:00:00+00:00",
      "tool_calls": null
    },
    {
      "id": "msg_xyz789ghi012",
      "role": "model",
      "content": "I found 3 great options from your wardrobe...",
      "created_at": "2026-03-08T10:00:05+00:00",
      "tool_calls": [
        { "tool": "list_wardrobe", "args": { "category": "TOP" }, "result": "..." }
      ]
    }
  ],
  "plan": [
    { "step": "Search wardrobe", "status": "DONE" },
    { "step": "Find matching commerce offers", "status": "IN_PROGRESS" }
  ],
  "artifacts": [],
  "created_at": "2026-03-08T10:00:00+00:00",
  "updated_at": "2026-03-08T10:00:05+00:00"
}

Client Event Acknowledgement:

// Response from POST /missions/{mId}/events
{
  "accepted": true,
  "missionId": "msn_abc123",
  "eventType": "USER_LIKED_ITEM"
}

For error responses, see the Error Reference → Orchestrator.

Client Events

Events allow the frontend to signal user actions back into the mission context:

// POST /households/{id}/orchestrator/missions/{mId}/events
{
  "eventType": "USER_LIKED_ITEM",   // See ClientEventType enum
  "offerId": "offer_123",
  "reason": null,
  "metadata": {}
}

Supported event types:

Event Type	Description
`USER_LIKED_ITEM`	User liked a commerce offer
`USER_DISLIKED_ITEM`	User disliked an offer (with optional reason)
`USER_TAKEOVER_START`	User took control of Hyperbeam session
`USER_TAKEOVER_END`	User released Hyperbeam session control
`USER_APPROVED_REQUEST`	User approved a purchase request
`USER_CONFIRMED_FINAL_CHECKOUT`	User completed final checkout

Agent Tools

Tool	Target Service	Description
`list_wardrobe`	wardrobe	Fetches household wardrobe items
`search_commerce`	commerce	Searches offers with constraints
`prepare_cart`	headless-cartprep	Dispatches a cart automation job
`create_hyperbeam_session`	hyperbeam-bridge	Creates an interactive browser session

Mission State Machine

See Data Models → Mission Lifecycle for the full state diagram.

Configuration

Variable	Default	Description
`APP_ENV`	`dev`	Runtime environment
`AUTH_JWT_SECRET`	`dev-secret-change-me`	Shared JWT secret
`ORCHESTRATOR_GCP_PROJECT_ID`	—	GCP project (fallback: `GCP_PROJECT_ID`)
`ORCHESTRATOR_GCP_LOCATION`	`us-central1`	Vertex AI region
`ORCHESTRATOR_VERTEX_MODEL`	`gemini-1.5-pro`	LLM model identifier
`ORCHESTRATOR_VERTEX_STAGING_BUCKET`	—	Optional staging bucket
`ORCHESTRATOR_REQUIRE_VERTEX_AGENT`	`false`	Crash on boot if GCP config missing
`PERSISTENCE_BACKEND`	`inmemory`	`firestore` or `inmemory`
`API_GATEWAY_BASE_URL`	`http://localhost:8080/api/v1`	Gateway URL for internal calls
`WARDROBE_BASE_URL`	`http://localhost:8081/api/v1`	Wardrobe service URL
`COMMERCE_BASE_URL`	`http://localhost:8002/api/v1`	Commerce service URL
`CARTPREP_BASE_URL`	`http://localhost:8005/api/v1`	CartPrep service URL
`HYPERBEAM_BASE_URL`	`http://localhost:8006/api/v1`	Hyperbeam Bridge URL
`INTERNAL_API_TIMEOUT_SECONDS`	`10.0`	Timeout for inter-service calls
`ORCHESTRATOR_INTERNAL_TOKEN`	`dev-internal-token`	Shared secret for internal bridge
`REQUIRE_INTERNAL_EVENT_TOKEN`	`true` (staging/prod)	Require token on `/internal/` routes
`ARTIFACTS_AUDIT_BASE_URL`	`http://artifacts-audit:8007/api/v1`	Audit service URL
`ARTIFACTS_AUDIT_ENABLED`	`true`	Enable artifact persistence

[!WARNING] In production, set ORCHESTRATOR_REQUIRE_VERTEX_AGENT=true. Without this, the service silently falls back to stubbed responses instead of real LLM reasoning.

Orchestrator

On this page