This page is the map. It shows every core component and the whole path from a request to a result. It hides the classes, the tables and the contracts. Each layer page below carries those.
Read this page first. Then read the layer page for the part you must change.
One box carries a TODO . The MCP server is planned and not built, and agent access records what works today.
AgencyCore agentic platform · how one request becomes one run
AgencyCore agentic platform · how one request becomes one run a person, a machine, or an agent · one run boundary · one runtime · two planes 0 · PRODUCTS
0 · PRODUCTS each product is definitions plus product data, never new infrastructure Agentic CRM
Agentic CRM the lead generation loop Signals Search
Signals Search companies · signals · people Email sequence
Email sequence Envoy durable outreach Builder chat
Builder chat conversational authoring 1 · WHO STARTS THE WORK
1 · WHO STARTS THE WORK a person, a machine, or an agent working for a person A person, in a conversation
A person, in a conversation Web chat Slack WhatsApp Telegram A person, in the product UI
A person, in the product UI Approval inbox Agent builder Run explorer An AI agent, working for a person
An AI agent, working for a person Claude Code
Claude Code and other CLI agents Claude
Claude and other MCP clients A machine reports Nylas mail arrives Vendor webhook Schedule fires CRM row changes CHANNEL GATEWAY
CHANNEL GATEWAY verify · identify · normalize keep the session · render the reply PRODUCT APIs
PRODUCT APIs these surfaces already speak our own schema read a run · resolve an approval · publish a definition THE ac CLI
THE ac CLI it signs in as a user it works today MCP SERVER
MCP SERVER one capability is one run planned, and not built TODO TRIGGERS
TRIGGERS one event meets one rule a new source is a new producer plus a row, never a new way in FRONT DOOR
FRONT DOOR ONE model call · answer, clarify, delegate or steer a run it picks the capability, it never does the work 2 · ONE DOOR INTO EXECUTION
2 · ONE DOOR INTO EXECUTION every run starts here, or nowhere Customise Agent/Workflow draft
draft it may be incomplete, it cannot run validate
validate deterministic, by kind published
published what a new run may use Agent/Workflow Definition
Agent/Workflow Definition Agents
Agents built in, or forked Workflows
Workflows built in, or forked Skills
Skills built in, or your own Tools
Tools built in, or connected AN ORGANIZATION ADDS ITS OWN
AN ORGANIZATION ADDS ITS OWN fork a template agent or workflow · write a new skill · connect an MCP server for new tools publishing is still the safety boundary RUN MANAGER
RUN MANAGER freeze what this run will use, then ask policy POLICY
POLICY may this run start? deny
deny no dispatch, and it stays on the record allow dispatch it require approval
require approval the run waits APPROVALS
APPROVALS a person decides in the approval inbox INNGEST · durable execution
INNGEST · durable execution retry
retry a step that failed runs again, from where it stopped wait
wait for a reply, an event, an approval, or a date time out
time out a wait that never resolves ends the run publish delegate planned approved, the run resumes
approved, the run resumes 3 · THE WORK
3 · THE WORK an agent decides its own steps, a workflow follows the steps we wrote What the run may read Memory
Memory what was said before Knowledge what is true CRM data
CRM data lists · activities Product state
Product state prospects · sequences CONTEXT BUILDER
CONTEXT BUILDER no model call, always scoped to the organization AGENTIC RUNTIME · it executes the frozen snapshot
AGENTIC RUNTIME · it executes the frozen snapshot the run executor claims the run and dispatches it by kind AGENT
AGENT one framework-neutral loop Agno is the only implementation it picks its own steps, and a skill teaches it how to use a tool WORKFLOW · the steps we wrote, and no model is in charge
WORKFLOW · the steps we wrote, and no model is in charge step kinds: agent · tool · approval · wait · branch · parallel · subworkflow for example, one email sequence: agent step
agent step draft the email it follows a skill: how we write outreach tool step
tool step email.send the tool invoker asks policy first approval
approval a person decides the run waits, and holds no worker wait and branch
wait and branch a reply, or three days a reply drafts a reply, silence drafts a nudge TOOLS
TOOLS one call, one effect, the only way to the world Where a tool lands Our own API
Our own API never the database Nylas mail out Exa · Parallel
Exa · Parallel web research Firecrawl page fetch MCP servers approved only 4 · WHAT COMES BACK
4 · WHAT COMES BACK one record, one answer, one bill The execution record Run row one per execution Spans
Spans one per unit of work Cost meter written once The product result Global intelligence
Global intelligence what we learned Organization prospect
Organization prospect is it interesting? CRM do we manage it? The review inbox · one page for everything that needs a person
The review inbox · one page for everything that needs a person TODO an email waiting to send a new signal
a new signal waiting for review a run
a run waiting for approval What we sell Four products. Each one is a set of definitions plus its own product data.
Four products. Each one is a set of definitions plus its own product data. None of them brings its own scheduler, queue, run table or policy engine. Who may ask Four kinds of caller, and three doors.
Four kinds of caller, and three doors. A person in a chat enters through the gateway, which turns any channel into one message shape. The front door then makes ONE model call. It chooses what should happen, and it does none of it. A person in the product UI, and an AI agent on that person's seat, both speak our schema already, so they call the API directly. A machine sends an event, and a trigger matches it to one rule. An MCP server would be the fourth door. It is not built. The gate Every run is born here. Nothing runs around it.
Every run is born here. Nothing runs around it. A definition is built in or authored by the organization. Fork a template agent or workflow, write a new skill, connect an MCP server for new tools. Whatever the source, it must be published before a run may use it. The run manager freezes what the run may use, so a later edit cannot change work already in flight. Policy then answers once: allow, deny, or ask a person. Anything not granted is denied. Retry, wait and time out are what make a long workflow possible. A run may sit for days waiting on a reply or an approval, and it resumes exactly where it stopped. Doing the work Context is rebuilt fresh for every run, and it is always scoped to one organization. No model call happens while it is built.
Context is rebuilt fresh for every run, and it is always scoped to one organization. No model call happens while it is built. The runtime claims the run and dispatches it by kind. An agent reasons its own way to the answer. A workflow follows steps we wrote. That is the only difference between them. The agent loop sits behind a framework-neutral interface. Agno is the only implementation, and no Agno type is allowed to leak into policy, tools, definitions or surfaces. That is what keeps it replaceable. Either way, the one door to the outside world is a tool. No credentials, no raw SQL and no free API access ever reach the model. Proof, and result Every run leaves a row, a span for each unit of work, and one cost figure.
Every run leaves a row, a span for each unit of work, and one cost figure. Discovery also leaves product state. It moves from what we learned, to what is interesting to us, to what we chose to manage. Anything that needs a person collects in one review inbox. Today those queues are scattered: an email approval lives in the CRM, and a prospect is reviewed where it was found. One page is the intent, not the state. POLICY · it decides, before the work
POLICY · it decides, before the work 1 · admission
1 · admission before dispatch 2 · action
2 · action every tool call 3 · accrual
3 · accrual as the cost grows allow the work goes ahead require approval
require approval a person decides deny nothing runs Anything not granted is denied. deny > require approval > allow. A rule change applies at the next checkpoint, not the next run.
Anything not granted is denied. deny > require approval > allow. A rule change applies at the next checkpoint, not the next run. OBSERVABILITY · it records, beside the work
OBSERVABILITY · it records, beside the work run row one per execution spans
spans one per unit of work cost meter written once the durable span is written first
the durable span is written first it is the record then the live event
then the live event best effort; a client that misses it refetches A metric is a query over runs and spans. An alert is a cron that runs the query.
A metric is a query over runs and spans. An alert is a cron that runs the query. IDEMPOTENCY · it protects the effect
IDEMPOTENCY · it protects the effect run.start
run.start a client request, or the source message id webhook.<provider>
webhook.<provider> the delivery id they gave us tool.<name>
tool.<name> run id, plus the model tool call id ONE CLAIM TABLE, in Postgres
ONE CLAIM TABLE, in Postgres claimed -> done, with the stored result A repeat returns the stored result. Inngest may retry safely only because the effect underneath is idempotent.
A repeat returns the stored result. Inngest may retry safely only because the effect underneath is idempotent. Always on These three apply at every stage above, so they need no arrows of their own.
These three apply at every stage above, so they need no arrows of their own. Policy decides before the work. Observability records beside it. Idempotency sits under both, so a retry cannot double an effect. Draw an arrow from a plane to a stage and you have said what the panel already says. LEGEND a person starts it here an event or a queue hop it costs a model call the one branch point ordinary work deterministic plumbing the allowed path it waits for a person it stops here a container, not a component
a container, not a component A dashed box is not ours to run, or not durable.
A dashed box is not ours to run, or not durable. Every arrow is the main path; position carries the rest. Text is not SVG - cannot display AgencyCore agentic platform · how one request becomes one run
AgencyCore agentic platform · how one request becomes one run a person, a machine, or an agent · one run boundary · one runtime · two planes 0 · PRODUCTS
0 · PRODUCTS each product is definitions plus product data, never new infrastructure Agentic CRM
Agentic CRM the lead generation loop Signals Search
Signals Search companies · signals · people Email sequence
Email sequence Envoy durable outreach Builder chat
Builder chat conversational authoring 1 · WHO STARTS THE WORK
1 · WHO STARTS THE WORK a person, a machine, or an agent working for a person A person, in a conversation
A person, in a conversation Web chat Slack WhatsApp Telegram A person, in the product UI
A person, in the product UI Approval inbox Agent builder Run explorer An AI agent, working for a person
An AI agent, working for a person Claude Code
Claude Code and other CLI agents Claude
Claude and other MCP clients A machine reports Nylas mail arrives Vendor webhook Schedule fires CRM row changes CHANNEL GATEWAY
CHANNEL GATEWAY verify · identify · normalize keep the session · render the reply PRODUCT APIs
PRODUCT APIs these surfaces already speak our own schema read a run · resolve an approval · publish a definition THE ac CLI
THE ac CLI it signs in as a user it works today MCP SERVER
MCP SERVER one capability is one run planned, and not built TODO TRIGGERS
TRIGGERS one event meets one rule a new source is a new producer plus a row, never a new way in FRONT DOOR
FRONT DOOR ONE model call · answer, clarify, delegate or steer a run it picks the capability, it never does the work 2 · ONE DOOR INTO EXECUTION
2 · ONE DOOR INTO EXECUTION every run starts here, or nowhere Customise Agent/Workflow draft
draft it may be incomplete, it cannot run validate
validate deterministic, by kind published
published what a new run may use Agent/Workflow Definition
Agent/Workflow Definition Agents
Agents built in, or forked Workflows
Workflows built in, or forked Skills
Skills built in, or your own Tools
Tools built in, or connected AN ORGANIZATION ADDS ITS OWN
AN ORGANIZATION ADDS ITS OWN fork a template agent or workflow · write a new skill · connect an MCP server for new tools publishing is still the safety boundary RUN MANAGER
RUN MANAGER freeze what this run will use, then ask policy POLICY
POLICY may this run start? deny
deny no dispatch, and it stays on the record allow dispatch it require approval
require approval the run waits APPROVALS
APPROVALS a person decides in the approval inbox INNGEST · durable execution
INNGEST · durable execution retry
retry a step that failed runs again, from where it stopped wait
wait for a reply, an event, an approval, or a date time out
time out a wait that never resolves ends the run publish delegate planned approved, the run resumes
approved, the run resumes 3 · THE WORK
3 · THE WORK an agent decides its own steps, a workflow follows the steps we wrote What the run may read Memory
Memory what was said before Knowledge what is true CRM data
CRM data lists · activities Product state
Product state prospects · sequences CONTEXT BUILDER
CONTEXT BUILDER no model call, always scoped to the organization AGENTIC RUNTIME · it executes the frozen snapshot
AGENTIC RUNTIME · it executes the frozen snapshot the run executor claims the run and dispatches it by kind AGENT
AGENT one framework-neutral loop Agno is the only implementation it picks its own steps, and a skill teaches it how to use a tool WORKFLOW · the steps we wrote, and no model is in charge
WORKFLOW · the steps we wrote, and no model is in charge step kinds: agent · tool · approval · wait · branch · parallel · subworkflow for example, one email sequence: agent step
agent step draft the email it follows a skill: how we write outreach tool step
tool step email.send the tool invoker asks policy first approval
approval a person decides the run waits, and holds no worker wait and branch
wait and branch a reply, or three days a reply drafts a reply, silence drafts a nudge TOOLS
TOOLS one call, one effect, the only way to the world Where a tool lands Our own API
Our own API never the database Nylas mail out Exa · Parallel
Exa · Parallel web research Firecrawl page fetch MCP servers approved only 4 · WHAT COMES BACK
4 · WHAT COMES BACK one record, one answer, one bill The execution record Run row one per execution Spans
Spans one per unit of work Cost meter written once The product result Global intelligence
Global intelligence what we learned Organization prospect
Organization prospect is it interesting? CRM do we manage it? The review inbox · one page for everything that needs a person
The review inbox · one page for everything that needs a person TODO an email waiting to send a new signal
a new signal waiting for review a run
a run waiting for approval What we sell Four products. Each one is a set of definitions plus its own product data.
Four products. Each one is a set of definitions plus its own product data. None of them brings its own scheduler, queue, run table or policy engine. Who may ask Four kinds of caller, and three doors.
Four kinds of caller, and three doors. A person in a chat enters through the gateway, which turns any channel into one message shape. The front door then makes ONE model call. It chooses what should happen, and it does none of it. A person in the product UI, and an AI agent on that person's seat, both speak our schema already, so they call the API directly. A machine sends an event, and a trigger matches it to one rule. An MCP server would be the fourth door. It is not built. The gate Every run is born here. Nothing runs around it.
Every run is born here. Nothing runs around it. A definition is built in or authored by the organization. Fork a template agent or workflow, write a new skill, connect an MCP server for new tools. Whatever the source, it must be published before a run may use it. The run manager freezes what the run may use, so a later edit cannot change work already in flight. Policy then answers once: allow, deny, or ask a person. Anything not granted is denied. Retry, wait and time out are what make a long workflow possible. A run may sit for days waiting on a reply or an approval, and it resumes exactly where it stopped. Doing the work Context is rebuilt fresh for every run, and it is always scoped to one organization. No model call happens while it is built.
Context is rebuilt fresh for every run, and it is always scoped to one organization. No model call happens while it is built. The runtime claims the run and dispatches it by kind. An agent reasons its own way to the answer. A workflow follows steps we wrote. That is the only difference between them. The agent loop sits behind a framework-neutral interface. Agno is the only implementation, and no Agno type is allowed to leak into policy, tools, definitions or surfaces. That is what keeps it replaceable. Either way, the one door to the outside world is a tool. No credentials, no raw SQL and no free API access ever reach the model. Proof, and result Every run leaves a row, a span for each unit of work, and one cost figure.
Every run leaves a row, a span for each unit of work, and one cost figure. Discovery also leaves product state. It moves from what we learned, to what is interesting to us, to what we chose to manage. Anything that needs a person collects in one review inbox. Today those queues are scattered: an email approval lives in the CRM, and a prospect is reviewed where it was found. One page is the intent, not the state. POLICY · it decides, before the work
POLICY · it decides, before the work 1 · admission
1 · admission before dispatch 2 · action
2 · action every tool call 3 · accrual
3 · accrual as the cost grows allow the work goes ahead require approval
require approval a person decides deny nothing runs Anything not granted is denied. deny > require approval > allow. A rule change applies at the next checkpoint, not the next run.
Anything not granted is denied. deny > require approval > allow. A rule change applies at the next checkpoint, not the next run. OBSERVABILITY · it records, beside the work
OBSERVABILITY · it records, beside the work run row one per execution spans
spans one per unit of work cost meter written once the durable span is written first
the durable span is written first it is the record then the live event
then the live event best effort; a client that misses it refetches A metric is a query over runs and spans. An alert is a cron that runs the query.
A metric is a query over runs and spans. An alert is a cron that runs the query. IDEMPOTENCY · it protects the effect
IDEMPOTENCY · it protects the effect run.start
run.start a client request, or the source message id webhook.<provider>
webhook.<provider> the delivery id they gave us tool.<name>
tool.<name> run id, plus the model tool call id ONE CLAIM TABLE, in Postgres
ONE CLAIM TABLE, in Postgres claimed -> done, with the stored result A repeat returns the stored result. Inngest may retry safely only because the effect underneath is idempotent.
A repeat returns the stored result. Inngest may retry safely only because the effect underneath is idempotent. Always on These three apply at every stage above, so they need no arrows of their own.
These three apply at every stage above, so they need no arrows of their own. Policy decides before the work. Observability records beside it. Idempotency sits under both, so a retry cannot double an effect. Draw an arrow from a plane to a stage and you have said what the panel already says. LEGEND a person starts it here an event or a queue hop it costs a model call the one branch point ordinary work deterministic plumbing the allowed path it waits for a person it stops here a container, not a component
a container, not a component A dashed box is not ours to run, or not durable.
A dashed box is not ours to run, or not durable. Every arrow is the main path; position carries the rest. Text is not SVG - cannot display A person, a machine, or an AI agent working for a person. All of them meet at one run boundary, and one runtime executes the work. Products sit on top as definitions plus product data, and nothing reaches the world except through a tool. The MCP server is marked TODO because it is planned and not built. Term Meaning Example Capability An action the user can request company.searchWorkflow The steps that perform an action Resolve identities, remove duplicates, apply filters Tool One operation that a step can call Read company data
A product is a user-facing area, such as Companies. Its actions are capabilities.
The Front Door selects work. The runtime executes it and checks permissions.
In the API, src/agentic/capabilities/ holds business actions and their workflows.
src/agentic/services/ holds shared tools, context, memory and data access.
The API onboarding guide shows the request flow and where to change code.
The Front Door selects the five stable product IDs.
It keeps the published Agent and Workflow UUID path for custom definitions.
Stage What happens The rule it obeys 1 · Who starts the work A person speaks to a conversational surface, or works in the product UI. A machine reports an event, and a trigger matches it to one rule. An AI agent works for a person, and drives the ac CLI on that person's seat. Whoever calls, the call ends at the same boundary. 2 · One door into execution Every caller reaches the same run start. The run manager freezes the published definition, the skills, the tool contracts, the context policy and the principal. Policy answers: allow, deny, or require approval. Inngest then owns retry, wait and time out. Every run starts here, or nowhere. 3 · The work The runtime rebuilds fresh, scoped context, then claims the run and dispatches it by kind. An agent runs a model loop; a workflow follows the steps we wrote. Either one reaches the world only through a tool. One agentic hop. One runtime. 4 · What comes back The run row, its spans and its cost are the durable record. Discovery work also lands in product state: global intelligence, then organization prospect, then CRM. Anything needing a person collects in the approval inbox. One record, one answer, one bill.
Three planes run across all four stages, so they need no arrows of their own:
Policy decides at admission, at every tool call, and as cost accrues.Observability writes one run row, one span for each unit of work, and one cost meter. The durable span is written before the live event.Idempotency makes the same message, webhook or tool call take effect only once.Inngest is not just a queue. Three of its guarantees are what make a multi-day workflow possible at all:
Retry. A step that failed runs again from where it stopped, not from the top of the run.Wait. A run can park on a reply, an event, an approval, or a date, and hold no worker while it waits.Time out. A wait that never resolves ends the run, instead of leaking it.The email sequence is the clearest case, and the diagram opens it up: an agent step drafts the email and follows a skill, a tool step calls email.send where the tool invoker asks policy first, an approval step parks the run until a person decides, and a wait holds for a reply or three days. That is one run, not a chain of cron jobs.
A workflow has eight node types. Two are containers, sequence and parallel. Six are steps: agent, tool, approval, wait, branch, subworkflow. There are no loops and no expression engine. The node set is fixed at publish time, so bounded fan out over runtime data lives inside one step.
Platform templates are read-only, and an organization extends the platform by adding its own definitions:
| To add | How |
|---|---|---|
| An agent or a workflow | Fork a platform template, then edit and publish the fork |
| A skill | Write one. A skill teaches an agent how to use the tools it already has |
| A tool | Use a platform tool or approved vendor integration. MCP servers are deferred |
Writing new executable tool code is deliberately deferred. Use platform tools, vendor integrations, and organization-authored skills first. MCP expands the tool source later, after the web-first interface slice is working. Whatever the source, publishing stays the safety boundary: a draft cannot run.
A run that stops for a person always stops for the same reason: it proposes an exact action, and somebody must authorize it. Every one of those collects in the approval inbox, whatever created it.
Three things create one:
policy at admission, before a run executes anything; policy at a tool call, such as an email waiting to send; an approval node, because the workflow author asked for a gate there. The approval inbox is the guaranteed floor for all three. A channel may render buttons, but every presentation resolves the same approval row, and silence is never consent. The human review inbox is the product page for it.
Curation is not authorization. A new prospect waiting to be watched, dismissed or promoted is business judgement, not permission to act, and it stays in Signals Search. Folding it into the approval inbox would mix a queue a person may ignore with a queue that blocks a run.
One product execution substrate. One run model, one status model, one event surface.One agent framework. Agno runs the reasoning loop, behind AgentRuntime. There is no backend selector and no runtime registry.One agentic hop. The front door picks one agent or one workflow. Coordinating a workflow is not a second reasoning hop.The runtime is one layer, and Agno sits behind it. The run executor dispatches by kind. The agent loop lives behind a framework-neutral interface, and no Agno type reaches policy, tools, definitions or surfaces. That is what keeps the framework replaceable.An agent reaches the world only through a tool. No credentials, no raw SQL, and no arbitrary API access in model context.Publishing is a safety boundary. A draft cannot run. A run freezes the published configuration, and reads policy and tool state live at each checkpoint.A user writes in web chat: "find UK fintech companies with recent funding signals and marketing decision makers."
The web adapter authenticates the user and normalizes the message. The Front Door builds scoped context and an eligible capability shortlist. The model selects signals.search with its version and validated input. The capability service resolves the tenant executor and calls RunManager.start() with the message's stable key. RunManager freezes the definition tree and capability metadata. Policy admits, denies or requests approval. The workflow performs bounded research and calls its published Company/People child workflows. Tool calls pass action policy. Enrichment writes canonical Intelligence; Signals writes organization prospects. The Run and conversation streams report progress. The user reviews the resulting prospects. CRM promotion remains an explicit action. Email sequence execution belongs to a separate Phase 8 action. A compound request with no single matching published capability produces a clarification.
The Front Door does not start an implicit search/enrich/outreach plan.
Phase Scope 7 Company, People and Signals capability products 8 Email sequence execution 9 Remaining legacy cutover and removal
The capability contracts define the Phase 7 boundary.
The design scenarios define its normal, failure and recovery cases.
The four stages above tell the story of one request. The pages cover five areas. Existing article URLs remain stable and do not define Python package names.
Interfaces - who starts a run, and how the request reaches us.Runtime - how the work executes.Services - shared tools, context, memory and data access.Planes - what crosses every stage.Products - the platform applied to one product.Policy and observability belong to a tier and to a stage at the same time. That is what a plane means. It crosses every stage, so it takes no place in the sequence.
The platform contract holds the layer ownership table, the shared contracts, the data model, and the list of what we are not building.
