Built-in Service Overview
A structured guide to the built-in services registered by the Downcity runtime and how to read them from an SDK point of view
Built-in Service Overview
The current Downcity runtime registry includes five built-in services:
chatcontacttaskmemoryshell
This list comes from the runtime source of truth in code, not from a docs-only concept list.
How to read this from the SDK side
These five services are not all the same kind of public API.
From an SDK point of view, they split into two groups:
Explicit SDK-first path
ChatService
This is the most direct constructor-first service you can import and register into a local Agent today.
Runtime-shaped built-ins that still matter to SDK users
contacttaskmemoryshell
These are already real runtime services with long-lived ownership, lifecycle, actions, and system semantics. Even when they are not the first constructor example most SDK users start with, they are still the best references for understanding the service model.
What makes all five of them services
They all own some combination of:
- long-lived runtime state
- service lifecycle
- stable action surfaces
- service-level prompt or system behavior
That is why they belong in services, not in one-shot tools.
How the five services divide responsibility
| Service | Main responsibility | Long-lived ownership | Best mental model |
|---|---|---|---|
chat | chat ingress and reply delivery | channel state, queue worker, queue store | channel runtime |
contact | agent-to-agent reachability and exchange | contact graph, long-lived contact chat, inbox/received shares | collaboration runtime |
task | scheduling and background execution | cron engine, scheduler reload boundary | background automation runtime |
memory | durable memory retrieval and writes | memory runtime state and indexing lifecycle | memory domain runtime |
shell | short and long shell execution | shell session map and shell runtime binding | execution runtime |
Best reading order
1. Start with chat
chat is the easiest way to build intuition for a service that clearly owns runtime objects over time.
If you want the explicit SDK constructor view, read ChatService next to the built-in chat page.
2. Then read shell
shell makes the service boundary very obvious:
- session ownership matters
- lifecycle matters
- one-shot calls and long-lived stateful calls both exist
It is one of the clearest examples of why a capability should not be modeled as a plain function.
3. Then read memory
memory shows a domain service that owns prompt semantics plus durable indexing and retrieval behavior.
4. Then read task
task is the background scheduler example. It is the best reference when you need a service that survives beyond one session and manages recurring work.
5. Finally read contact
contact is the most collaboration-oriented built-in. It is less likely to be the first constructor you try, but it is a strong reference for persistent relationships, inbound/outbound reachability, and agent-to-agent exchange.
Which page to open first
- To understand SDK chat integration: read chat
- To understand agent-to-agent collaboration: read contact
- To understand background scheduling: read task
- To understand retrieval and durable notes: read memory
- To understand execution sessions: read shell