Front door general chat

AgencyCore chat is the user's front door. A person may ask:

"What can AgencyCore do with this company?"

or:

"Why did the prospect search stop?"

or:

"What is lifecycle stage?"

Those are not all task requests. Some are product questions, some are questions about live or past Runs, some are follow-ups on scoped business entities, and some are requests to start work. The Front Door must handle that breadth without becoming a second runtime.

The rule is:

General chat answers from supplied context, or it asks, delegates, or controls a Run.

User message
    |
    v
Front Door
    +-- conversation context
    +-- entities in scope
    +-- run history
    +-- platform and organization knowledge
    +-- capability shortlist
            |
            v
    answer / clarify / delegate / control_run

No new Front Door outcome is required. General chat is the product contract for the answer and clarify paths, plus the routing discipline that keeps work in delegated Agents and Workflows.

What the feature owns

General chat owns the everyday conversational experience before a specialized capability takes over:

• build the right bounded context for the user's question;
• answer product and platform questions from retrieved knowledge;
• answer questions about scoped business entities from application context;
• summarize live and recent Runs from run history;
• resolve conversational follow-ups such as "this company" through entity scope;
• cite the records, documents or Runs that support a factual answer;
• ask one focused question when the user intent or reference is ambiguous;
• explain when the platform lacks enough context or capability;
• delegate work requests to one published Agent or Workflow;
• control a live Run when the user clearly asks to stop it.

It does not own deep research, CRM exploration, email search, web browsing, tool execution, workflow steps, policy, approval rules, memory writes, trigger scheduling or definition authoring.

The front door builder chat is still a delegated specialized Agent. General chat may route authoring intent to it, but it does not create or patch definitions itself.

Phase 6 focus

Phase 6 is not the final chat product. It is the slice that makes chat dependable as the default entry point.

The focus is:

• high-quality context assembly for general chat;
• evaluation against real question scenarios;
• missing knowledge and read capabilities for CRM, workflows and agents;
• broad question generation for test coverage;
• stress testing the chat flow for stability and latency;
• useful progress messages while the user waits.

The UI should follow the existing chat experience. Phase 6 should not redesign chat chrome, message layout, navigation or source rendering. Any source affordance should fit the current message model and can be replaced later with the full chat redesign.

Why this is not more task logic

The Front Door already has the correct closed set:

answer(text)
clarify(question)
delegate(capability_id, input)
control_run(run_id, action)

General chat makes answer useful. It does not widen what the Front Door may do.

"What does lifecycle mean?"
        |
        v
answer from platform knowledge

"Find fintech companies hiring a head of growth."
        |
        v
delegate(Signals Search, original message)

"Add a human review step to the workflow."
        |
        v
delegate(Definition Builder, authoring brief)

A general answer is a conversational product result. A delegated Run is execution. The distinction stays visible in both state and UI.

Context sources

Phase 5 enables the web chat surface and the thin Front Door. Phase 6 should make that Front Door useful as the actual front door by adding the missing context sources and entity scope.

The ContextBuilder owns retrieval. The model receives a bounded ContextBrief; it does not call search tools from the Front Door.

Fresh exploration remains delegated. If the user asks "which companies match this ICP?", the Front Door does not run a CRM or web search. It delegates to the appropriate capability.

Context evaluation

The success of general chat depends more on context quality than on prompt wording. Phase 6 should evaluate the context builder against use cases before tuning the model.

Question scenario
    |
    v
Expected context ingredients
    |
    v
ContextBuilder policy and source retrieval
    |
    v
Packed ContextBrief
    |
    v
Front Door outcome
    |
    v
Answer, clarify, delegate or control_run

Each scenario should record:

Evaluation should include both positive and negative cases. A good result is not only "the answer is right"; it is also "the Front Door did not search, execute or guess."

Initial question set

Phase 6 should generate and test a large library of user questions. The first scope is CRM, workflows and agents.

CRM questions

What does lifecycle stage mean?
Why is this company marked as a prospect?
What changed on this company recently?
Who owns this deal?
Why is this prospect waiting for review?
What evidence supports this opportunity score?
Show me the last activity on this company.
Why did this company stop matching our ICP?
Can I promote this prospect to CRM?
Find more companies like this one.

Most CRM explanation questions should answer from scoped application context and knowledge. Discovery questions such as "find more companies" should delegate.

Workflow questions

What steps does Signals Search run?
Why is this workflow waiting?
What happens after the approval step?
Can I change this workflow to add human review?
Which workflow should I use for outreach?
Why did this workflow fail?
What data does this workflow write?
Run this workflow every Monday.
Stop that workflow run.

Definition and behaviour questions should answer from knowledge and definition summaries. Authoring questions should delegate to Builder Chat. Trigger questions should route to trigger configuration when that capability exists.

Agent questions

What agents can I use?
What does the Definition Builder do?
Which tools can this agent use?
Why did this agent ask for approval?
What memory does this agent keep?
Create an agent that qualifies inbound leads.
Can this agent send email?
Why did the agent stop?
Change the running agent's instructions.

Capability questions can answer from the capability index and platform knowledge, but the capability index is not evidence for factual product behaviour. Authoring requests delegate. Live steering still clarifies or explains cancel plus restart.

General platform questions

What can AgencyCore do?
How is chat different from running a workflow?
What does approval mean?
Where do citations come from?
Why can you not answer this from chat?
What should I upload so you can answer this?

These should answer from platform knowledge. If the relevant docs are not ingested, the answer should name the missing knowledge instead of guessing.

Entity scope

General chat needs a durable way to resolve follow-ups.

Run result returns ResourceRefs
        |
        v
conversation stores entities in scope
        |
        v
next Front Door turn carries those refs
        |
        v
ApplicationContextSource resolves only those refs

The conversation should store a small ordered set of scoped entities:

agent.conversation_entities
  conversation_id
  kind
  resource_id
  label
  introduced_by_message_id
  last_referenced_at

Rules:

• Entity scope is a pointer set, not a knowledge store.
• A Run result, an assistant answer or an explicit user mention may add a ref.
• An exact, unambiguous relevant ref resolves "this" or "that".
• If more than one ref fits, the Front Door returns clarify.
• The source still resolves every ref through the normal scoped reader.
• Losing the pointer loses convenience, not data.

Builder Chat uses the same mechanism for active definition drafts. No authoring-session table is needed.

Knowledge-backed answers

Platform documentation is the main source for product questions:

docs page
  -> extract text
  -> chunk
  -> embed
  -> agent.knowledge_sources(scope = platform)
  -> agent.knowledge_chunks
  -> ContextBuilder knowledge source
  -> Front Door answer

An organization document uses the same tables with organization_id set. The Front Door may read only sources visible to the actor's organization.

Knowledge retrieval is not live web search. It answers from documents AgencyCore has ingested and marked ready.

Every factual answer from knowledge should carry source refs:

Knowledge source: /engineering/system-design/agentic-platform/interfaces/front-door
Chunk: 12
Claim: The Front Door selects one Agent or Workflow and never executes work itself.

The UI may render those refs as source chips or footnotes. The storage requirement is simpler: the assistant message records the refs it used so an answer can be audited later.

Answer contract

answer remains one Front Door outcome, but Phase 6 should make its payload structured enough to audit.

class FrontDoorAnswer(BaseModel):
    text: str
    citations: list[ResourceRef] = []
    unresolved: list[str] = []

The user-visible text is still plain chat. The extra fields are for rendering, audit and tests.

Rules:

• A factual claim about AgencyCore behaviour cites platform knowledge.
• A factual claim about the user's business cites an application or Run ref.
• A preference-shaped answer may use memory, but memory never overrides application state.
• If the needed source is missing or unavailable, say what is missing.
• If a request requires fresh work, delegate instead of answering from old context.
• If the user asks for external current facts and no research capability is available, say the platform cannot answer it from chat.
• Do not cite the capability shortlist. It is routing context, not evidence.

This is a prompt rule and a validation rule. The Front Door can reject an answer that carries unsupported citations or references outside the supplied brief.

Missing capabilities

General chat can answer only what its context sources can provide. Phase 6 should add the missing read capabilities needed for the first question set.

The first implementation should prefer read-only projections over new agent tools. A read capability is context; a tool is action.

Routing matrix

The model may be conversational in tone, but the outcome is not conversationally loose. One turn produces one of the four structured outcomes.

Examples

Product question

User:
What is the Front Door allowed to do?

General chat:
Answers from platform knowledge:
- decide answer / clarify / delegate / control_run
- never execute task work
- delegate Runs through RunManager
Includes citations to the Front Door design.

Scoped business question

User:
Why is this prospect marked review needed?

Context:
conversation entity scope contains prospect:123
application source returns review_state and reason

General chat:
Answers from the scoped prospect fields.
Does not search for more prospects.

Work request

User:
Find 20 UK fintech companies that just raised seed funding.

General chat:
Delegates to Signals Search if visible.
If no such capability is visible, explains that no published capability can do it.

Authoring request

User:
Make a workflow that researches a company, asks me to review it, then drafts outreach.

General chat:
Delegates to Definition Builder with the authoring brief.
Definition Builder owns the draft.

UI behaviour

The web chat should keep the existing chat UI and UX. Phase 6 should improve behaviour inside that experience, not replace the interface.

Source rendering is not the Phase 6 product bet. The important contract is that answers record citations and never make unsupported factual claims. The future chat redesign can choose how to expose those citations.

Waiting states

The user should see useful messages while the system works. Progress is semantic state, not chain-of-thought.

message accepted
    |
    v
thinking
    |
    v
checking_context
    |
    v
finding_capability
    |
    +-- answer or clarify
    |
    +-- preparing_task
            |
            v
       Run progress stream

The Front Door owns progress until a Run owns the work. After delegation, the runtime owns the stream.

Suggested message meanings:

Do not emit fake specificity such as "searching CRM" from the Front Door. If CRM search is happening, a delegated Run owns it.

Stress testing

Phase 6 should stress test the whole chat flow, not only model output.

The stress suite should include scenario tests, contract tests and load-style tests. A stable chat flow is one that remains bounded, idempotent and clear under failure.

Quality gate

Phase 6 should end with a system design and code quality review. General chat sits on the product front door, so the implementation must stay small, explicit and easy to maintain.

The review should check:

• the Front Door still has only four outcomes;
• no action tools or exploratory reads were added to the Front Door;
• context sources are read-only, scoped and bounded;
• prompt and answer contracts are validated by code, not only by instruction text;
• retries and duplicate messages remain idempotent;
• dead or stale Phase 6 code was removed;
• files follow the existing module boundaries and clean-code patterns;
• tests match the final design and obsolete tests are deleted.

Any deferred design risk should become an explicit follow-up with an owner.

Failure handling

V1 rules

• General chat does not add a fifth Front Door outcome.
• Phase 6 focuses on CRM, workflow and agent questions first.
• Phase 6 follows the existing chat UI and UX.
• The Front Door does not receive action tools.
• The model never performs exploratory reads in the Front Door.
• The ContextBuilder retrieves before the model reasons.
• Context quality is evaluated through scenario fixtures.
• The question library includes positive, negative and ambiguous cases.
• Knowledge answers cite knowledge refs.
• Business answers cite application or Run refs.
• Capability summaries are not evidence.
• Entity scope is durable conversation metadata, not a fact store.
• Ambiguous pronouns lead to one clarification.
• Work requests delegate through RunManager.
• Authoring requests delegate to the Definition Builder Agent.
• Live Run changes are limited to cancel. Steering remains V2.
• Progress messages are semantic state and stop when Run progress begins.
• Stress tests cover context, routing, idempotency, latency, streaming, tenancy, cost gates and citations.
• Phase 6 closes with a design and clean-code review.

Minimum scenarios

• "What can you do?" answers from platform knowledge when knowledge is available.
• "What is lifecycle stage?" cites the relevant product documentation.
• "What agents can I use?" answers from visible capability summaries and platform knowledge.
• "What steps does Signals Search run?" answers from workflow knowledge or definition summary context.
• "Why did that run stop?" asks which Run when more than one recent Run fits.
• "Why did that run stop?" answers from run history when one Run fits.
• "Tell me more about this company" resolves a scoped company ref.
• A stale or unauthorized entity ref does not leak data.
• "Find companies like this" delegates instead of searching inside the Front Door.
• "Create an agent that qualifies inbound leads" delegates to Definition Builder.
• "Stop that" cancels only when one active Run is clear.
• An answer cannot cite a ref outside the supplied ContextBrief.
• A retry writes one assistant message and no second model usage row.
• A slow context source emits useful progress but does not expose internal reasoning.