Skip to content

5.6.1 Introduction

moochat is the system responsible for the agents, their tools and their conversations with Organization users and staff. One runtime serves every agent: MooChat for Organizations and the assistant of the Console are two definitions with different tools and model profiles. It belongs to the Intelligence domain of the platform. Every interface it offers follows Choosing an Interface.

Proposal for review

The contracts of this system are a proposal, not confirmed design: endpoints, events and calls were written from the refined requirements, the data model and the flows, and wait for review. What needs a decision is collected in Open Decisions.

5.6.1.1 Host Names

Environment Host
Prod moochat.moonitoring.com
Stage stage-moochat.moonitoring.com, behind IAP

The names follow the host name rule; on a developer's computer each service answers on a local port (Running Locally). Each domain below is a path on these hosts, followed by its version: https://moochat.moonitoring.com/<domain>/v1.

5.6.1.2 Domains

Each domain of moochat is one API, with its own contract and its own version.

  • 5.6.2.1 Agents

    The configuration of the agents: definitions, the model profiles the AI gateway calls, the tools published by the systems' MCP servers and which tools each agent may use. /agents/v1

  • 5.6.2.2 Conversations

    Threads between a user and an agent: conversations, their messages and the tool calls of each turn. /conversations/v1

5.6.1.3 How It Is Used

Organization conversation

  1. The Organization Dashboard sends the user's message with the user's Access token, so the message is authorized as its sender.
  2. The Conversations domain filters available tools by the sender's capabilities and the Organization's entitlements.
  3. MooChat asks ai-gateway for a completion with the prompt's data class.
  4. The runtime calls a product system's MCP server with the user's token when it needs current facts, then streams the answer over the live socket.

Tool call that writes

  1. The agent identifies that a tool would change data rather than only read it.
  2. MooChat stops the turn and asks the user to confirm the proposed write.
  3. The confirmation message authorizes the tool call, which is then sent to the owning system with the user's authorization.

Staff administration

  1. A staff member uses the Console to manage agent definitions, tools, or model profiles.
  2. The Agents domain applies staff authorization and records the change as an audit event through Access.
  3. The runtime refreshes its configuration without holding provider keys or reading another system's database.
flowchart LR user{{Organization user}} -->|REST and live socket| moochat[MooChat API] staff{{Staff member}} -->|REST administration| moochat moochat -->|gRPC completions| gateway[AI Gateway] moochat -->|MCP and gRPC facts| systems[Product systems] systems -->|events| moochat
  • Called by: Console (REST); Organization Dashboard (REST); access (gRPC CatalogService); farm (gRPC CatalogService).
  • Calls: access (gRPC OrganizationsService); ai-gateway (gRPC BatchesService, gRPC CompletionsService); every system (gRPC CatalogService); farm (gRPC EntitlementsService).
  • Publishes events consumed by: ai-gateway (1 event type).
  • Consumes events of: access (2 entries), ai-gateway (1 entry), farm (3 entries).
  • Reads no other system's database: everything above goes through a contract on this page or an event.

5.6.1.4 Synchronous Calls Between Systems

None served. It calls CompletionsService of ai-gateway, EntitlementsService.Check of farm and CatalogService of every system; it speaks MCP to the systems' MCP servers, as the guidelines describe (D14).

5.6.1.5 Events

Events are facts in the past tense, published through the outbox and delivered at least once on the topic moochat.events.v1; the envelope and the guarantees are in common/v1/events.yaml. Events marked outside reach the Pub/Sub subscriptions an Organization registers in Webhooks, pushed to its HTTPS endpoint or pulled by its own service account.

Publishes (contract: events/v1/asyncapi.yaml):

Event Published when Consumers Outside
agent_definition.changed.v1 An agent was created, changed, paused, resumed or archived. none yet no
agent_model_profile.changed.v1 A model profile was created, changed or retired. ai-gateway refreshes the routing it derives from profiles. ai-gateway no
conversation.turn.completed.v1 The assistant finished a turn: its message and tool calls are stored. Every moochat instance receives it and forwards it to the live connections of that conversation. none yet no

Consumes:

Event From Why
organization.*.v1, membership.*.v1, delegation.*.v1 access Authorizes each message as its sender and offers tools by the sender's capabilities.
entitlement.*.v1, feature_usage.limit_reached.v1 farm Offers agents and tools by the Organization's features; degrades or blocks at the limit.
staff_membership.changed.v1, staff_role.updated.v1 access Authorizes staff agents.
data_issue.opened.v1, resolved_event.published.v1, animal.*.v1 farm Lets an agent mention what changed since the user last asked; optional.
provider.degraded.v1 ai-gateway Falls back to another profile of the same tier.
erasure_request.executed.v1 farm Erases the Organization's conversations.