# Ergoly > Workers you own, one per client, inside the Slack your agency already uses. What that means and where to start. Ergoly Docs › Overview. Web: https://www.ergoly.ai/docs · Index: https://www.ergoly.ai/docs/llms.txt Ergoly gives your agency **workers**: AI members of your Slack workspace, each with a name, a job, and memory of its own. You teach a worker how your agency does a piece of work. It does that work for your clients, in their channels, under your name. Every client you assign a worker to gets a separate copy of that worker. The copy for Acme knows Acme and nothing about Globex. What a worker learns about the job travels to every client; what it learns about a client stays with that client. ## The shape of it | Thing | What it is | | --- | --- | | Company | Your agency on Ergoly. The chart of who works here, people and workers alike. | | Worker | An AI member of your company with a role, responsibilities, and behaviors you set. | | Client | A customer of yours. Assign a worker, and that client gets its own copy. | | Channel | Where a worker operates: Slack channels and DMs, email, and the web. | | Knowledge | What a worker remembers and the skills it can run. | | Work | Tasks and routines, the tools a worker is connected to, approvals, and the pages it publishes. | ## Where to start - [A day with a worker](https://www.ergoly.ai/docs/a-day-with-a-worker): One Slack walkthrough, start to finish. - [Getting started](https://www.ergoly.ai/docs/getting-started): From the invite to your first worker in Slack. - [Workers](https://www.ergoly.ai/docs/workers): Identity, role, responsibilities, behaviors, and where they work. - [Clients](https://www.ergoly.ai/docs/clients): Adding one, assigning a worker, and what stays separate. The pages use the words control uses. If you are writing code against the API or want to know what sits behind a word, see [Technical details](https://www.ergoly.ai/docs/technical). ## For agents Every page here is also served as Markdown, from the same source: add `.md` to a page's address, or use the **View as Markdown** link at the top of any page. The index is at [/docs/llms.txt](https://www.ergoly.ai/docs/llms.txt) and the whole set in one file at [/docs/llms-full.txt](https://www.ergoly.ai/docs/llms-full.txt). Point Claude Code or any agent at the index and it can read these docs the way you do. --- # A day with a worker > One worker, two clients, one morning. What it looks like from inside Slack. Ergoly Docs › Overview. Web: https://www.ergoly.ai/docs/a-day-with-a-worker · Index: https://www.ergoly.ai/docs/llms.txt Your agency is on Ergoly with one worker, Nora, who handles account management for two clients, Acme and Globex. Here is a Tuesday. ## 9:00 — a routine runs Nora has a routine that runs every weekday morning for each client: pull what moved in the project tracker and post a status note. Nobody asked for it today. It runs because it was scheduled once. ```slack #acme Nora (worker) [Every weekday 9:00]: Morning. Status as of 9:00: identity approved, website build past halfway, launch copy with your legal team. A board-ready one-pager is in this thread. [Acme rebrand · status] Identity: approved Sep 12 · Website: 14 of 22 pages built · Launch copy: with Acme legal ``` *A routine posts where it was told to. Globex gets its own note, from its own copy of Nora.* ## 10:40 — a client asks Daniel at Acme asks for something in the shared channel. Nora answers in a thread, as your agency, from everything it knows about Acme and nothing else. ```slack #acme Daniel · Acme: @Nora can you send over where the rebrand stands before our board meeting Thursday? Nora (worker): Yes. Everything from this morning still holds, and legal came back an hour ago with two small edits. I've folded them in; the updated one-pager is attached. ``` ## 11:15 — you correct it You read the thread and want the one-pager shorter. You say so, once. Nora fixes it and keeps the rule. ```slack #acme-internal Sam: @Nora board one-pagers for Acme should fit on one screen. No appendix. Nora (worker): Done. I've cut the appendix and I'll keep Acme's board one-pagers to one screen from now on. ``` *The rule is filed with Acme. Globex's one-pagers are unchanged.* ## 14:00 — it asks before acting Nora is set to get approval before anything goes to a client's mailing list. It drafts, then asks. ```slack #globex-internal Nora (worker): Globex's launch email is drafted for Thursday 8:00. It goes to 1,240 subscribers. Approve to schedule it, or tell me what to change. [Approve · Reject] Launch email · Globex · Thursday 8:00 · 1,240 recipients Priya: Approved. Nora (worker): Scheduled. Priya approved at 14:02. ``` *Whoever presses the button is recorded with the decision.* ## 16:30 — it hands something off A question comes up that needs a person. Nora opens a task, hands it to the account lead, and waits. ```slack #acme-internal Nora (worker): Acme asked whether the launch can move a week. That's a scope and budget call, so I've handed it to @Sam. I'll reply to Acme once you decide. ``` *A task waits for its holder. Nothing goes to the client until you answer.* That is the whole loop: routines run, clients ask, you correct, it asks when it should, and it hands off what is not its call. Each of those has a page of its own. - [Routines](https://www.ergoly.ai/docs/work/routines): Tasks that repeat, across clients. - [Memory](https://www.ergoly.ai/docs/workers/knowledge/memory): How a correction becomes a rule, and where it is kept. - [Approvals](https://www.ergoly.ai/docs/work/approvals): Asking first, and the record of who decided. - [Tasks](https://www.ergoly.ai/docs/work/tasks): Handing work to a worker, or to a person. --- # Getting started > From the invitation to your first worker answering in Slack. Four steps, most of them in Slack. Ergoly Docs › Getting started. Web: https://www.ergoly.ai/docs/getting-started · Index: https://www.ergoly.ai/docs/llms.txt Ergoly takes on a few agencies at a time, and someone from Ergoly sets your company up with you. After that, your AI Admin takes over: a worker that lives in your Slack and builds the rest of your company from a conversation. 1. [Getting access](https://www.ergoly.ai/docs/getting-started/access): you accept an invitation to control and a shared Slack channel with the Ergoly team. 2. [Meet your AI Admin](https://www.ergoly.ai/docs/getting-started/ai-admin): you connect Slack, name your AI Admin, and install it. It messages you and sets up your first worker. 3. [Add a client and a channel](https://www.ergoly.ai/docs/getting-started/first-client): you tell the AI Admin who the client is and which channel is theirs. 4. [Your first correction](https://www.ergoly.ai/docs/getting-started/first-correction): you tell the worker what to do differently, once, and it keeps the rule. > **Worth knowing.** Everything your AI Admin does, you can also do in control. The pages under Company, Workers and Clients show both. The AI Admin asks before it changes anything, so nothing happens without your yes. --- # Getting access > Onboarding with the Ergoly team: an invitation to control and a shared channel in Slack. Ergoly Docs › Getting started. Web: https://www.ergoly.ai/docs/getting-started/access · Index: https://www.ergoly.ai/docs/llms.txt When Ergoly takes your agency on, someone on the team creates your company and sends two invitations. ## The invitation to control You get an email inviting you to control, the web app at control.ergoly.ai. Accept it and sign up. You are the company's first **admin**, which means you can invite other people, create API keys, and set up the AI Admin. The people you invite are **members**: they can use everything in control except those three things. ## The shared Slack channel You also get a Slack Connect invitation to a private channel shared between your workspace and Ergoly's. It is where you ask the Ergoly team for help. Ergoly's own support worker, Wicket, is in that channel too, and answers there. ## What happens next The first time you open control, it takes you straight to setup, because your company has no workers yet. That is the [AI Admin](https://www.ergoly.ai/docs/getting-started/ai-admin) step. --- # Meet your AI Admin > Connect Slack, name it, install it. It messages you and sets up your company and your first worker from there. Ergoly Docs › Getting started. Web: https://www.ergoly.ai/docs/getting-started/ai-admin · Index: https://www.ergoly.ai/docs/llms.txt Your **AI Admin** is a worker that only works inside your company. It never joins a client's channel. Its job is to set things up: workers, channels, clients, and the tools they use. ## Setup, in control Setup has four steps. 1. **Connect Slack.** Ergoly needs permission to create Slack apps in your workspace. On api.slack.com/apps, open **App Configuration Tokens**, press **Generate Token**, and paste the token that starts with `xoxe-` into the **Refresh token** field. 2. **Name your AI Admin.** Type a name (the example is Ada). Leave **Full Slack permissions** on unless you have a reason not to; it lets the AI Admin invite workers to channels and create channels for you. 3. **Install it.** Press **Add to Slack** and click **Allow** in the Slack window that opens. Control shows *Starting up…* while the worker is built. 4. **Done.** Control shows * is looking around your workspace*, then * has messaged you in Slack*. ## Then, in Slack Open the direct message from your AI Admin. It introduces itself and asks what the first worker should do. Answer in plain words. It proposes a name, a job, and the channels, and asks for your yes before creating anything. ```slack Direct message with Ada Ada (worker): Hi Sam, I'm Ada, your AI Admin. I set up workers, channels, clients and tools, and I ask before I change anything. What should your first worker do? Sam: Account management for our retainer clients. Status notes, meeting prep, follow-ups. Ada (worker): Got it. I'll create a worker called Nora, job title Account Manager, reporting to you. To start it needs a Slack install, which opens a window for you to click Allow. Shall I go ahead? Sam: Yes. ``` *The AI Admin proposes, you approve. The install link needs a workspace admin.* > **Worth knowing.** Only an admin can create the AI Admin, because it holds a key to your whole company. A member who opens setup sees *An admin sets up your AI Admin*. If your company already has workers, the link to add one is above the Company page's List tab. - [Access](https://www.ergoly.ai/docs/company/access): Admins, members, the AI Admin, and API keys. - [Workers](https://www.ergoly.ai/docs/workers): What the AI Admin just created, and how to change it. --- # Add a client and a channel > Tell the AI Admin who the client is, and which Slack channel is theirs. From then on, the worker answers there as your agency. Ergoly Docs › Getting started. Web: https://www.ergoly.ai/docs/getting-started/first-client · Index: https://www.ergoly.ai/docs/llms.txt A worker on its own works for your team. To put it in front of a client, you need a **client** in Ergoly and a Slack channel that belongs to that client. The AI Admin does both from a message. ```slack Direct message with Ada Sam: Add Acme as a client and put Nora in #acme. Daniel Reyes is their contact. Ada (worker): I'll create the client Acme, assign Nora to it, set #acme as Acme's channel, and bind Daniel Reyes to Acme so his DMs with Nora go to Acme. Nora will join #acme itself. OK? Sam: OK. Ada (worker): Done. Acme is live in #acme. Nora is there now, and only sees Acme's world when it is working for Acme. ``` ## What just happened Three things. A client called Acme now exists. Nora has a separate copy for Acme, with Acme's memory and nothing else. And #acme is mapped to Acme, so a message there always reaches that copy. ## Or invite the worker yourself You can also invite a worker to a channel in Slack, the way you would invite a person. It asks you, and only you, what the channel is for. See [When a worker joins a channel](https://www.ergoly.ai/docs/workers/channels/slack). > **Worth knowing.** Start with an internal channel for the client, where your team reviews the worker's drafts, before inviting it into the channel the client is in. See [Internal client channels](https://www.ergoly.ai/docs/clients/internal-channels). - [Clients](https://www.ergoly.ai/docs/clients): Adding, assigning, and what stays separate. - [Client channels](https://www.ergoly.ai/docs/workers/channels/slack/client-channels): How a channel is mapped, and how to change it. --- # Your first correction > Say what you want done differently, once. The worker writes it down and files it with the right client, the right worker, or the whole company. Ergoly Docs › Getting started. Web: https://www.ergoly.ai/docs/getting-started/first-correction · Index: https://www.ergoly.ai/docs/llms.txt A worker learns the way a new hire does: by being told. You do not configure it. You correct it in the thread where the work happened, and it keeps the rule. ```slack #acme-internal Nora (worker): Here is the Acme weekly status draft. Three sections: done, in progress, blocked. Sam: @Nora Acme reads these on their phone. Lead with blocked, and keep the whole thing under 150 words. Nora (worker): Done, 128 words, blocked first. I've noted for Acme: lead with blocked, under 150 words. I'll keep to that for their status notes from now on. ``` *The rule is filed with Acme, because it is about Acme. Globex is unchanged.* ## Where the rule goes When a worker learns something, it asks itself who the thing is true for. A client's preference is filed with that client. A better way of doing the job is filed with the worker, so every client benefits. A rule for the whole agency is filed with the company. If it is not sure, it files narrower, and tells you where it put it. ## Checking what it kept Everything a worker remembers is a file you can read. Open the worker in control, choose the **Knowledge** tab, and pick the client from the context picker at the top. The note is there, in plain Markdown, and you can edit it. See [Memory](https://www.ergoly.ai/docs/workers/knowledge/memory). > **Worth knowing.** A correction about how the worker behaves in general, rather than a fact about a client, belongs in its behaviors. The worker proposes the exact line and adds it only after your explicit yes. See [Behaviors](https://www.ergoly.ai/docs/workers/behaviors). --- # Company > Your agency on Ergoly: the chart of people and workers, the teams and clients, the settings, and who can do what. Ergoly Docs › Company. Web: https://www.ergoly.ai/docs/company · Index: https://www.ergoly.ai/docs/llms.txt The **Company** page is a picture of your agency: who works here, people and workers alike, who reports to whom, and which clients and vendors you work with. Everything else in Ergoly belongs to the company, and nothing reaches across to another one. - [Chart](https://www.ergoly.ai/docs/company/chart): Teams, people, workers, and open roles, and how to place them. - [Members](https://www.ergoly.ai/docs/company/members): The People and Workers pages, and who can sign in to control. - [Teams](https://www.ergoly.ai/docs/company/teams): Internal teams, clients, and vendors. - [Settings](https://www.ergoly.ai/docs/company/settings): Slack, email, avatars, task archiving. - [Access](https://www.ergoly.ai/docs/company/access): Admins and members, the AI Admin, and API keys. --- # Chart > An org chart that holds people and workers side by side. Drag to place, and the chart decides who a worker turns to when it needs a person. Ergoly Docs › Company. Web: https://www.ergoly.ai/docs/company/chart · Index: https://www.ergoly.ai/docs/llms.txt The chart shows your agency as a tree: teams, the people in them, the workers in them, and open roles you have not filled yet. A person is anyone from your Slack workspace. A worker sits on the chart like a person does, with a title and someone it reports to. ## Adding to the chart Press **Add** at the top, or right-click empty canvas. The menu has two rows: **Individuals** (Person, Worker, Open role) and **Teams** (Team, Vendor, Client). A person is picked from Slack; a worker opens the new-worker page; an open role is a seat to fill later. ## Placing and moving - Drag a card onto another card to make it report there, onto a team to join it, or onto an open role to fill it. - The **No team** tray along the bottom holds everything not on the chart yet: new workers, clients nobody has placed, people from Slack. Drag out of it to place; drag onto it to remove. - Every card has a sheet. Open it to change the name or title, **Move…** it, or **Remove from chart**. Removing takes the card and everything under it back to the tray; nothing is deleted. - One seat can hold two people (**Share this seat**), and a person or worker can be placed in more than one spot. ## What to show The **Show on the chart and list** menu has two boxes: **Vendors** (on by default) and **Clients** (off by default). The **Chart** and **List** tabs show the same company two ways; List has a status filter. ## Why it matters to a worker The chart is a picture, not a permission. Placing a worker in a team does not change what it can see. It does decide one thing: when a worker needs a person, it goes to the nearest person above it on the chart, unless you set someone else. See [Reporting](https://www.ergoly.ai/docs/workers/reporting). > **Worth knowing.** A team's lead is not a setting. It is simply the one seat directly under the team. --- # Members > People and workers are listed side by side. Who can sign in to control is a separate list. Ergoly Docs › Company. Web: https://www.ergoly.ai/docs/company/members · Index: https://www.ergoly.ai/docs/llms.txt Two pages under Company list who works here. - **People**: One row per person from your Slack workspace who is on the chart, is a client's contact, or is waiting in the tray. Columns: Name, Team, Reports to. Nobody is invited here; people appear once a worker is installed in your workspace, and you place them. - **Workers**: One row per worker, with its team, the clients it serves, and its status. **New Worker** starts the create wizard. A row opens the worker's own page. ## Who can sign in Being on the chart does not give someone a login. Logins to control are managed under **Settings**, on the **Members** tab, where you invite people by email and set their role. An **admin** can invite people, create API keys, and set up the AI Admin. A **member** can do everything else. ## Worker statuses | Status | Meaning | | --- | --- | | Active | Installed and answering. | | Onboarding · Provisioning | Being built. Give it a few minutes. | | Onboarding · Awaiting install | Waiting for a Slack admin to click Allow. | | Active · Stopped | Paused from the worker's Settings tab. | | Failed / Error | Something went wrong during setup. Open the worker for details and a Retry. | | Quarantined | Ergoly stopped it after repeated failures. The worker's page says why and has an Unquarantine button. | --- # Teams > Three kinds of team: your own, a client, and a vendor. Each holds different things. Ergoly Docs › Company. Web: https://www.ergoly.ai/docs/company/teams · Index: https://www.ergoly.ai/docs/llms.txt A team on the chart is one of three kinds, and the kind decides what can sit inside it. - **Team**: A team of your own. Holds people, workers, open roles, and other teams. Created from **Add → Team** with a name and a colour. - **Client**: A company you work for. Nothing is placed inside it; the cards in its box are the people you have linked to that client. Created from **Add → Client**, from the Clients page, or by asking the AI Admin. - **Vendor**: An outside company that works for you. Holds people only. Created from **Add → Vendor** with a name, a website (its logo comes from there), what they do, and who it reports to. ## What a client's box does Adding a person to a client's box is how you tell Ergoly that this person belongs to that client. From then on, their direct messages with any worker serving that client go to that client's copy of the worker. The sheet says so: *Priya's DMs with Nora will go to Acme.* If no worker serves the client yet, you are asked to assign one first. See [Assigning a worker](https://www.ergoly.ai/docs/clients/assigning-a-worker). ## Archiving A team or vendor can be archived from its sheet, after a confirm. Its members go back to the tray. A client is not archived here; its own page handles that. > **Worth knowing.** A team can be converted to a person when it has exactly one seat and nothing else, and a worker can be converted to a team. Both are on the card's sheet. --- # Settings > Six tabs: Slack, Members, API keys, Avatars, Email, and Tasks. Ergoly Docs › Company. Web: https://www.ergoly.ai/docs/company/settings · Index: https://www.ergoly.ai/docs/llms.txt - **Slack**: The connection Ergoly uses to create Slack apps in your workspace. It shows **Configured** or **Not yet set up**, the linked workspace's name, and a **Refresh token** field with **Save**, **Rotate**, and **Test connection**. You set this during setup; come back here only to rotate the token. - **Members**: Who can sign in to control and their role. See [Access](https://www.ergoly.ai/docs/company/access). - **API keys**: Keys that reach everything your company owns. Admins only. See [Access](https://www.ergoly.ai/docs/company/access). - **Avatars**: Pick a style for your workers' avatars from a gallery and press **Save avatar style**. It applies to every worker at once; photos you uploaded yourself are kept. - **Email**: Your workers' sending domain: its status, the sending address shape (worker@yourdomain), the DNS records Ergoly publishes for it, and **Re-check now**. The domain is claimed when your first worker is built; you do not set anything up. See [Email](https://www.ergoly.ai/docs/workers/channels/email). - **Tasks**: The **Archive period**: a task with no activity for this long is closed as archived, with a line on its log saying so. **After N days with no activity**, or **Never**. The default is 30 days. --- # Access > Three ways into your company: a person in control, the AI Admin in Slack, and an API key. Ergoly Docs › Company. Web: https://www.ergoly.ai/docs/company/access · Index: https://www.ergoly.ai/docs/llms.txt ## People in control Everyone you invite under **Settings → Members** can use control. Two things are reserved for **admins**: creating and revoking API keys, and setting up the AI Admin. Both exist because each hands out a key to the whole company. ## The AI Admin in Slack Your AI Admin is a worker that works only for your team and holds its own API key. That is what lets it create workers, map channels, add clients and connect tools from a conversation. It can never be put in front of a client, and it asks before every change. See [Meet your AI Admin](https://www.ergoly.ai/docs/getting-started/ai-admin). ## API keys A key reaches everything your company owns, read and write. There is no narrower key. To create one: 1. Open **Settings**, then the **API keys** tab, and press **Create key**. 2. Give it a **Name** (the placeholder suggests *deploy-pipeline*) and an **Expiry**: never, 30 days, 90 days, or a year. 3. Copy it. Control says *This is the only time it is shown*, and means it. The list shows each key as **Yours**, **A worker's**, or **System-managed**, and any of them can be revoked. Revoking takes effect from the next request. What a key did before that is in the [activity feed](https://www.ergoly.ai/docs/work/approvals). > **Worth knowing.** A key is not a person. Everything it writes is recorded under the key's own name, so give each job its own key and an expiry if the job has an end. - [The API](https://www.ergoly.ai/docs/technical/api): The reference, the first call, and the shape of every answer. --- # Workers > An AI member of your company. It has a name, a job, responsibilities and behaviors you set, and a separate copy for each client it serves. Ergoly Docs › Workers. Web: https://www.ergoly.ai/docs/workers · Index: https://www.ergoly.ai/docs/llms.txt A **worker** is one Slack app with one name. People address it the way they address a colleague: in a channel, by @-mention, or in a DM. It has a role, a list of responsibilities, a list of behaviors, memory of its own, and skills it can run. Everything about it is on its page in control, under **Workers**. One worker can serve many clients. For each client, it gets a separate copy with that client's memory and nothing of any other client's. Your own team talks to a copy that holds every client's memory. You never see the copies; you see one worker. ## The worker's page The header shows the avatar, the name, the role title, a status badge, and, once the worker serves clients, a context picker: **Internal** or one client. The picker decides which copy the Tasks, Knowledge, Connections and Triage tabs show. | Tab | What it holds | | --- | --- | | Overview | The four role cards: Responsibilities, Out of scope, Behaviors, When they conflict. | | Clients | The clients, channels and people this worker serves, and the Add to client button. | | Tasks | Scheduled tasks for the chosen context, with Run now, History, Edit, Disable. | | Knowledge | The memory browser for the chosen context, and the worker's tools. | | Connections | The apps that reach this worker in the chosen context. | | Triage | Whether it is awake, recent conversations, and Restart. | | Settings | Identity, runtime, response behavior, escalation, email, and the danger zone. | ## Creating a worker Ask your AI Admin, or press **New Worker** on the Workers page. The wizard has five steps: **Identity** (name, job title, who it reports to, and a drafted responsibilities list), **Clients**, **Slack & channels** (an Add to Slack window; click Allow), **Tools**, and **Launch**, which ends with *Say hello to *: send it a message to prove it works. - [Identity](https://www.ergoly.ai/docs/workers/identity): Name, avatar, Slack app, email address. - [Role](https://www.ergoly.ai/docs/workers/role): The job title and what it is for. - [Responsibilities](https://www.ergoly.ai/docs/workers/responsibilities): What it is accountable for, and what is out of scope. - [Behaviors](https://www.ergoly.ai/docs/workers/behaviors): Avoid, Don't, Prefer, Use. - [Channels](https://www.ergoly.ai/docs/workers/channels): Where it works: Slack, email, the web. - [Knowledge](https://www.ergoly.ai/docs/workers/knowledge): Memory and skills. --- # Identity > A name, an avatar, a Slack app, and an email address. Change any of them from the worker's Settings tab. Ergoly Docs › Workers. Web: https://www.ergoly.ai/docs/workers/identity · Index: https://www.ergoly.ai/docs/llms.txt - **Name**: What people call it, in Slack and in control. On the Settings tab, under **Identity**, with **Role title** beside it. Press **Save**; the change reaches the worker on its next turn. - **Avatar**: Click the photo in the page header (**Change photo**). PNG, JPEG or WebP under 2 MB. The style of generated avatars is set for the whole company under Settings → Avatars. - **Slack app**: Each worker is its own Slack app and bot. Under **Connection & runtime**, **Set icon in Slack** pushes the avatar to the app so it matches in both places. The card also shows the Slack app ID, read-only. - **Email address**: Every worker has one, shown under Identity as a copy chip once it exists. It looks like `nora@youragency.ergoly-mail.com`; a client's copy has its own, with the client's name in it. See [Email](https://www.ergoly.ai/docs/workers/channels/email). > **Worth knowing.** The name is also the worker's slug in URLs and in the API. Renaming changes what people see; the slug set when the worker was created stays. --- # Role > The job title, and the one-line job it does. A worker is a role, not an automation. Ergoly Docs › Workers. Web: https://www.ergoly.ai/docs/workers/role · Index: https://www.ergoly.ai/docs/llms.txt A worker's **role** is its job title and what the job is for: *Account Manager*, *SEO Analyst*, *Bookkeeper*. You set the title when you create the worker and can change it under Settings → Identity. The title is what people see under its name, and it is the first thing the worker reads about itself. ## One worker, one role The question of how many workers to run is a question about roles, not tasks. Divide by role: if two jobs would be done by two different people at your agency, judged by two different standards, make two workers. If one person would do both, make one worker and give it two skills. [Staff it, don't wire it](https://www.ergoly.ai/thoughts/staff-it-dont-wire-it) makes the full argument. ## Persona From the name, the title and the company, Ergoly writes the worker's persona: who it is, how it introduces itself, whose name it works under. The persona is rewritten whenever the worker is rebuilt, so it always matches what control says. The parts you own are the [responsibilities](https://www.ergoly.ai/docs/workers/responsibilities) and [behaviors](https://www.ergoly.ai/docs/workers/behaviors). > **Worth knowing.** Give the title the way you would on a job posting. A worker with a vague title asks more questions than one with a clear one. --- # Responsibilities > The list of what a worker is trained for and accountable for. Requests outside the list are outside its job. Ergoly Docs › Workers. Web: https://www.ergoly.ai/docs/workers/responsibilities · Index: https://www.ergoly.ai/docs/llms.txt A worker's **responsibilities** are an enumerated list: the high-order things it is trained and proven capable of, and responsible for in its role. Once the list is saved, the worker treats a request that is not on it as outside its job, and says so. ## The cards On the worker's **Overview** tab, the first two cards are **Responsibilities** and **Out of scope**. Both come from one file in the worker's memory. A pencil icon opens an editor with **Write** and **Preview**; press **Save** and it reaches the worker on its next turn. If the worker edited the file while you had it open, control says so and offers **Reload**. ## Drafted for you When you create a worker, the wizard drafts a responsibilities list from the job title and your company chart. Edit it before you continue. If a worker's list is still empty, control can show a **Proposed responsibilities** card built from what the worker does today, with **Save as the list** and **Reject**. ## How the list changes You can edit it any time. The worker can also propose a change, in Slack, when it learns something about its job. It makes the change only after your explicit yes, and records a dated line under *Changes* in the file saying what changed and who agreed. ```slack #acme-internal Sam: @Nora from now on you also own the monthly client health report. Nora (worker): I can add that. Proposed line for my responsibilities: Prepare the monthly client health report for each retainer client. Shall I add it? Sam: Yes. Nora (worker): Added, with a note that Sam agreed on the 22nd. ``` > **Worth knowing.** The AI Admin's responsibilities are kept by Ergoly and are not edited here. --- # Behaviors > What a worker follows day to day, as Avoid, Don't, Prefer and Use lines. Read every turn, changed only by agreement. Ergoly Docs › Workers. Web: https://www.ergoly.ai/docs/workers/behaviors · Index: https://www.ergoly.ai/docs/llms.txt A worker's **behaviors** are the rules it follows in every conversation. They are written as four kinds of line, and the file itself explains them: - **Avoid**: Not without a good reason. - **Don't**: There is never a good reason. - **Prefer**: Names the better option, and the one to watch for. - **Use**: A positive instruction. *Four lines from a behaviors file* ``` - Don't send anything to a client's mailing list without approval. - Avoid scheduling calls before 10:00 in the client's time zone. - Prefer a one-screen summary over an attachment; watch for decks over ten slides. - Use the client's own product names, never ours. ``` ## Where they live On the **Overview** tab, the **Behaviors** card shows the list and the **When they conflict** card shows what the worker does when two rules collide. Both are one file in the worker's memory. Edit either card with the pencil, or edit the file in the Knowledge tab. ## Changing them from Slack Tell the worker how you want it to behave, in the thread. It proposes the exact line and adds it only after your explicit yes, then records who agreed and when. A rule you state once in a conversation about Acme is a fact about Acme and goes in Acme's memory instead; a rule about how the worker behaves everywhere goes here. ```slack #globex-internal Priya: @Nora never quote prices in a client channel. Send them to me first. Nora (worker): Understood. Proposed behavior: Don't quote prices in a client channel; send them to the account lead first. Add it? Priya: Add it. Nora (worker): Added. It applies to every client from my next message. ``` *A behavior applies everywhere the worker works. A client preference stays with the client.* > **Worth knowing.** The worker reads its behaviors at the start of every turn, so a saved line is in force immediately. There is no deploy. --- # Response policy > When a worker speaks: only when @-mentioned, or to anything it judges is for it. And whether it listens when not addressed. Ergoly Docs › Workers. Web: https://www.ergoly.ai/docs/workers/response-policy · Index: https://www.ergoly.ai/docs/llms.txt Two settings decide when a worker answers in a channel. Both are on the worker's **Settings** tab, under **Response behavior**. - **Replies**: **Only when @mentioned**, or **To anything it judges is for it**. - **Listens when not addressed**: **Off — un-addressed messages never reach it**, or **On — it reads them but still cannot reply**. Listening lets a worker learn from a channel it does not answer in; its Slack status shows *Listening…* while it reads. With nothing set, a worker is quiet: it replies only when @-mentioned and sees nothing else. Direct messages are always answered. ## Set it per client The **Scope** picker lets you set a value for the whole company (labelled *Organization — every Worker*), for one worker everywhere it works, for one client, or for one copy. The narrowest value wins. So one worker can answer everything in Acme's channel and only mentions in Globex's. ## Or ask the worker People can ask the worker itself to go quiet or to answer everything, in the channel. A value you set in control overrides what it was asked. ```slack #acme Daniel · Acme: @Nora only answer when we tag you in here, please. Nora (worker): Done. In #acme I'll reply only when I'm @-mentioned. ``` > **Worth knowing.** In a thread it already replied in, a worker still needs an @-mention, except while it is working there. Adding an @-mention to a message by editing it, within an hour, counts. --- # Reporting > Who a worker reports to on the chart, and who it takes a question to when it needs a person. Ergoly Docs › Workers. Web: https://www.ergoly.ai/docs/workers/reporting · Index: https://www.ergoly.ai/docs/llms.txt ## Reports to A worker sits on the Company chart like a person. You choose who it reports to when you create it (**Reports to** in the wizard, with *Nobody — leave them off the chart* as an option), and you can move it later by dragging on the chart or from its card's **Move…**. See [Chart](https://www.ergoly.ai/docs/company/chart). ## Who it asks When a worker needs a person, it takes the question to its **escalation assignee**. By default that is worked out from the chart: the nearest person above the worker that it can message. If the chart names nobody, it is the person who created the worker. To pick someone else without changing the chart, open the worker's **Settings** tab, find **Escalation assignee**, and choose a person under **Set the assignee**. The card's *In force right now* line always says who it is and why: *set here*, *from the org chart*, or *its creator*. **Clear** goes back to the chart. > **Worth knowing.** Escalation is for questions, not approvals. Approvals go to whoever the worker was told to ask, with buttons in the thread. See [Approvals](https://www.ergoly.ai/docs/work/approvals). --- # Access > Who can talk to a worker, and which clients it serves. Set on the Clients tab. Ergoly Docs › Workers. Web: https://www.ergoly.ai/docs/workers/access · Index: https://www.ergoly.ai/docs/llms.txt A worker's access is three lists: the **clients** it serves, the **channels** it answers in, and the **people** whose direct messages belong to a client. All three are on the worker's **Clients** tab, in one table with the caption *Where messages to this Worker go: a client, or your own team (internal)*. ## Who can talk to it | Person | In a client's channel | By direct message | | --- | --- | --- | | Someone at your agency | Answered by that client's copy | Answered by your team's copy, which knows every client | | A client's contact, linked to that client | Answered by that client's copy | Answered by that client's copy | | A guest, or someone from another workspace not linked to a client | Answered by that client's copy, in that client's channel only | Told it cannot help: *I only work with people from the organization that set me up.* | ## Adding a client Press **Add to client**. Pick the **Client**, then tick **Channels** and **People**. As the dialog says, *channels route by conversation, people route their DMs and group DMs*. A channel or person already linked to another client is greyed out: nothing is moved silently. See [Assigning a worker](https://www.ergoly.ai/docs/clients/assigning-a-worker). ## Channels Each channel row can be **Mark internal**, **Reassign** to another client, or removed. **Add channel** lists channels the worker can see that are not set up yet: public ones it can **Join**, private ones you invite it to first with `/invite`. Details under [Channels](https://www.ergoly.ai/docs/workers/channels). > **Worth knowing.** A worker marked internal-only has no Add to client button. Its tab says: *This is an internal-only worker: it can never be put in front of a client. It works in DMs and internal channels only.* Your AI Admin is one. --- # Triaging > When a worker is slow, silent or stuck: what the Triage tab shows, and the three buttons that fix most things. Ergoly Docs › Workers. Web: https://www.ergoly.ai/docs/workers/triaging · Index: https://www.ergoly.ai/docs/llms.txt The **Triage** tab answers two questions: is the worker awake, and what has it been saying. - **Runtime**: One row per context (Internal and each client): **awake** or **sleeping**, last activity, last wake, and recent time-to-first-reply. A sleeping worker is normal. It sleeps after a few idle minutes and wakes on the next message in seconds. - **Turns**: Recent conversations grouped by Slack thread. Click one to read it; **Load older turns** goes back further; a copy action gives you the thread as Markdown. ## The fixes, least invasive first 1. **Stop.** Send the word `stop` in the thread, or `@worker stop`. Only the person whose message started the work can stop it; anyone at your agency can stop a scheduled run. 2. **Restart Worker**, on the Triage tab. It does the least invasive thing that applies: clears a stuck reply, re-activates, or relaunches. It may interrupt a reply in progress. 3. **Unquarantine**, in the banner at the top of the page. Ergoly quarantines a worker after repeated failures and says why. Read the reason, then press the button. ## The danger zone At the bottom of **Settings**: **Stop** pauses the worker; **Restart** brings a stopped or failed one back; **Re-install / update scopes** re-runs the Slack install so new permissions take effect; **Delete Worker** removes the Slack app, every copy, and all its data, after you type its name. > **Worth knowing.** If a worker is silent in a channel, check its [response policy](https://www.ergoly.ai/docs/workers/response-policy) and whether the channel is set up, before restarting anything. An un-set-up channel answers an @-mention with *I'm not set up for this channel yet*. --- # Channels > Where a worker operates: Slack, email, and the web. And the events in those channels that make it act. Ergoly Docs › Workers. Web: https://www.ergoly.ai/docs/workers/channels · Index: https://www.ergoly.ai/docs/llms.txt A **channel** is anywhere a worker can be reached. Slack is where it lives: channels, direct messages, group messages. Email is a second address for the same worker. The web is for other systems: a URL they can post to, and the API. An **event** is something that happens in a channel: a message, a mention, a scheduled routine firing, a delivery to a webhook. Every event starts a worker working, and ends with an answer back where the event came from. See [Events](https://www.ergoly.ai/docs/workers/channels/events). - [Slack](https://www.ergoly.ai/docs/workers/channels/slack): Internal channels, client channels, DMs, group DMs. - [Email](https://www.ergoly.ai/docs/workers/channels/email): Sending now; receiving coming soon. - [Web](https://www.ergoly.ai/docs/workers/channels/web): Hooks, triggers, and the API. - [Events](https://www.ergoly.ai/docs/workers/channels/events): Everything that makes a worker act. --- # Slack > Each worker is a member of your workspace. Every channel it is in belongs to one client or to your team, and that decides what it knows there. Ergoly Docs › Workers. Web: https://www.ergoly.ai/docs/workers/channels/slack · Index: https://www.ergoly.ai/docs/llms.txt A worker is a named member of your Slack workspace: its own app, its own avatar, in the channels you invite it to. Four kinds of place, four pages: - **[Internal channels](https://www.ergoly.ai/docs/workers/channels/slack/internal-channels)**: Your team's own channels. The worker answers from everything it knows, every client included. - **[Client channels](https://www.ergoly.ai/docs/workers/channels/slack/client-channels)**: A channel that belongs to one client. The worker answers from that client's world and nothing else. - **[DMs](https://www.ergoly.ai/docs/workers/channels/slack/dms)**: A direct message. Who you are decides which copy answers. - **[Group DMs](https://www.ergoly.ai/docs/workers/channels/slack/group-dms)**: A message to the worker and a few people at once. ## When a worker joins a channel Invite a worker to a channel the way you invite a person. It stays only if a workspace admin invited it, and it asks the inviter, privately, what the channel is for, with a suggestion. ```slack #acme Nora (worker): I just joined #acme. It looks like your client Acme's channel. Set me up for Acme? [Only visible to you] Set up for Acme · Internal channel · New client… · An existing client… · Leave channel Sam: Set up for Acme Nora (worker): Done — #acme is Acme's channel, and their agent is live. Go ahead and talk to me there. ``` *Only the person who invited it can answer. Anyone else is told so.* If no client matches, it offers **New client…**, which creates the client and sets the channel up in one go. If only your team is in the channel, it suggests **Internal channel**. **Leave channel** backs out. ## Threads and progress In a channel, a worker always replies in a thread. While it works, its Slack status shows *is thinking…*. A message that arrives while it is busy gets a 👀 reaction and is handled next; several messages from the same person in a row are handled as one. --- # Internal channels > Your team's own channels. The worker answers from everything it knows, including every client. Ergoly Docs › Workers. Web: https://www.ergoly.ai/docs/workers/channels/slack/internal-channels · Index: https://www.ergoly.ai/docs/llms.txt An **internal channel** is one that belongs to your team rather than to a client. The copy of the worker that answers there holds every client's memory, so your own people can ask it about any account: *what's open for Acme*, *draft Globex's renewal note*. ## Marking a channel internal - When the worker joins and asks, press **Internal channel**. - On the worker's **Clients** tab, press **Mark internal** on a channel row, or use **Add channel** and choose Internal. - Ask your AI Admin: *make #ops an internal channel for Nora*. A channel with no setting at all is not internal. It is unassigned, and the worker tells anyone who mentions it there that it is not set up yet. ## Who is answered In an internal channel the worker answers your workspace's members. A guest in an internal channel is answered too, because the channel decides, so keep client contacts out of internal channels unless you mean them to be there. > **Worth knowing.** The channel your team uses to review a worker's drafts for one client is a special case: it is internal, but the drafts are about one client. See [Internal client channels](https://www.ergoly.ai/docs/clients/internal-channels). --- # Client channels > A channel that belongs to one client. The worker answers there as your agency, from that client's world and nothing else. Ergoly Docs › Workers. Web: https://www.ergoly.ai/docs/workers/channels/slack/client-channels · Index: https://www.ergoly.ai/docs/llms.txt A **client channel** is mapped to one client. The copy of the worker that answers there has that client's memory, that client's connections, and the people linked to that client. It has never seen another client's channel, and nothing typed in the channel can change that. ## Mapping a channel to a client - When the worker joins and asks, press the suggested client, or **An existing client…**, or **New client…**. - On the worker's **Clients** tab, press **Add to client**, pick the client, and tick the channel. Or **Add channel**, then assign it by client slug. - On the client's own page, press **Bind a Worker** and tick the channel. - Ask your AI Admin: *#globex is Globex's channel*. ## Moving a channel A channel already mapped to one client is never taken over from the join buttons. To move it, use **Reassign** on the worker's Clients tab; control asks you to confirm, so a move is always something you asked for twice. ## Shared channels A client channel is usually a Slack Connect channel shared with the client's workspace. The worker answers the client's people there. It does not need them to be linked to the client for that; the channel decides. Linking matters for [DMs](https://www.ergoly.ai/docs/workers/channels/slack/dms). > **Worth knowing.** Only a workspace admin can add a worker to a channel. A client contact who invites it gets *only workspace admins can add me to a new channel*, and the worker leaves. --- # DMs > A direct message is always answered. Who you are decides which copy of the worker answers. Ergoly Docs › Workers. Web: https://www.ergoly.ai/docs/workers/channels/slack/dms · Index: https://www.ergoly.ai/docs/llms.txt Anyone at your agency can DM a worker, and the copy that answers is your team's: it knows every client. A client's contact who is **linked to that client** also gets an answer, from that client's copy. Everyone else is told, politely, that the worker cannot help them. | Who sends the DM | Who answers | | --- | --- | | A member of your workspace | Your team's copy | | A person linked to Acme | Acme's copy | | A guest, or a Slack Connect contact linked to no client | Nobody. They see: *I'm not able to pick this up — I only work with people from the organization that set me up.* | ## Linking a person to a client Link a person from the worker's **Clients** tab (**Add to client**, then the **People** tab), from the client's page (**Bind a Worker**, People), or by adding them to the client's box on the [Company chart](https://www.ergoly.ai/docs/company/teams). The chart's sheet says what it does: *Daniel's DMs with Nora will go to Acme.* ## Threads in DMs In a DM, each message you send starts its own thread, and the worker replies in it. That keeps a long DM history readable: one topic, one thread. > **Worth knowing.** A DM is never a channel. It cannot be mapped to a client; only the person can be linked. If a linked person's client copy is not live yet, their message is dropped and marked with ❌. --- # Group DMs > A message to the worker and a few people at once. The people in it decide which client it is about. Ergoly Docs › Workers. Web: https://www.ergoly.ai/docs/workers/channels/slack/group-dms · Index: https://www.ergoly.ai/docs/llms.txt A **group DM** is a direct message with the worker and two or more people. The worker answers in it, flat rather than in threads, and decides whose copy answers from who is present. | Who is in the group | Who answers | | --- | --- | | Only your own people | Your team's copy | | Your people and contacts linked to one client | That client's copy | | Contacts linked to two different clients | Nobody. The message is dropped, because no single copy could answer without mixing clients. | > **Worth knowing.** A group DM with two clients' people in it is the one place a worker refuses outright rather than picking. Start two group DMs instead. --- # Email > Every worker has an email address and can send from it. Receiving is coming soon. Ergoly Docs › Workers. Web: https://www.ergoly.ai/docs/workers/channels/email · Index: https://www.ergoly.ai/docs/llms.txt Each worker has an email address under a sending domain Ergoly sets up for your company when your first worker is built. It looks like `nora@youragency.ergoly-mail.com`. A client's copy has its own, with the client's name in it, so mail about Acme comes from Acme's copy. Mail goes out under the worker's name. ## Sending Ask the worker to email someone and it does, with to, cc and bcc, attachments up to about 3 MB, and replies into an existing thread. It sends at most five emails a minute and to at most a hundred recipients at once. Every email it sent is listed on the worker's **Settings** tab under **Email**, with when, from, subject and status. ```slack #acme-internal Sam: @Nora email Daniel the status one-pager, cc me. Nora (worker): Sent to daniel@acme.example from nora.acme@youragency.ergoly-mail.com, cc Sam, subject Acme rebrand — status, 22 Oct, with the one-pager attached. ``` ## Switching it off The same card has a kill switch: **Switch email off** stops the worker sending anything until you switch it back on. ## The domain Under **Settings → Email** for the company you can see the domain's status, the records Ergoly published for it, and **Re-check now**. You do not set anything up yourself. - [Receiving email](https://www.ergoly.ai/docs/workers/channels/email/receiving): Coming soon. --- # Receiving email > A worker reading mail sent to its address, and acting on it. Ergoly Docs › Workers. Web: https://www.ergoly.ai/docs/workers/channels/email/receiving · Index: https://www.ergoly.ai/docs/llms.txt **Coming soon.** A reply to a worker's address is recorded today, but nothing reads it and nothing starts from it. When receiving ships, an email to a worker's address will be an event like a Slack message: the worker reads it, works on it, and replies by email, with the thread visible to your team. Until then, ask people to reach a worker in Slack. --- # Web > Ways for other systems to reach a worker: a hook it listens on, triggers from connected tools, and the API. Ergoly Docs › Workers. Web: https://www.ergoly.ai/docs/workers/channels/web · Index: https://www.ergoly.ai/docs/llms.txt ## Hooks A **hook** is a URL that belongs to one worker. When another system posts to it, the worker takes what arrived and works on it, and the answer lands in a Slack channel or a person's DM that you named when you created the hook. A form submission, a new ticket, a deploy finishing: anything that can send a web request can start a worker. Each hook has a name, a destination (a channel the worker is in, or a person linked to it), and a threading choice: every delivery as a new message, each delivery in its own thread, or all deliveries in one thread. You can add an opening line and a template for how the payload is shown. Hooks are created through the API today; there is no screen for them in control yet. Creating one returns the URL and a secret that starts with `whsec_`, shown once. The caller sends the secret with every delivery. See [The API](https://www.ergoly.ai/docs/technical/api). ## Triggers A **trigger** is an event inside a connected tool, such as a new deal in your CRM, that starts a worker without a web request. See [Triggers](https://www.ergoly.ai/docs/workers/channels/web/triggers), coming soon. ## The API Everything you can do in control, a key can do from a terminal or a coding agent: create workers, add clients, map channels, schedule tasks, connect tools, read the activity feed. There is no API call that sends a worker a message directly; to start it from code, use a hook or a task. See [The API](https://www.ergoly.ai/docs/technical/api). > **Worth knowing.** A hook on a client's copy of a worker can only post into that client's channels or DM that client's people. If the channel is later moved to another client, deliveries stop until the hook is re-pointed. --- # Triggers > An event inside a connected tool that starts a worker: a new deal, a new ticket, a changed row. Ergoly Docs › Workers. Web: https://www.ergoly.ai/docs/workers/channels/web/triggers · Index: https://www.ergoly.ai/docs/llms.txt **Coming soon.** Triggers are not available yet. A hook does the same job today for any system that can send a web request. When triggers ship, you will pick an event in a connected app, a worker, and where its answer goes, and the worker will act whenever the event happens, with no web request to set up. Until then, see [Web](https://www.ergoly.ai/docs/workers/channels/web) for hooks. --- # Events > Everything that makes a worker act. Each one ends with an answer back where it came from. Ergoly Docs › Workers. Web: https://www.ergoly.ai/docs/workers/channels/events · Index: https://www.ergoly.ai/docs/llms.txt An **event** is something that happens in a channel. Every event starts the worker working on one thing, and when it is done, the answer goes back to where the event came from. These are all of them. | Event | What starts | Where the answer goes | | --- | --- | --- | | A mention | An @-mention in a channel the worker is set up in. | A thread under the message. | | A message | A message with no mention, in a channel where the worker is set to answer everything. With listening on, it reads but does not reply. | A thread, or nowhere. | | A DM or group DM | Any message, from someone it may talk to. | The same DM. | | A queued message | A message sent while it was busy, handled once it is free. | A thread under that message. | | A button press | Someone presses Approve, Reject, or another button the worker posted. | The same thread, with the decision recorded. | | A scheduled task | A task fires on its schedule. | The channel or person the task names; otherwise only the task's log. | | A task change | A task is handed to the worker, commented on by a person, or changes state. | The task's log, and Slack if the task says so. | | A hook delivery | Another system posts to the worker's hook. | The channel or DM the hook names. | | Its first day | A newly built worker sends its first DM to the person who created it. | That DM. | Not events: an email arriving (receiving is not live), a trigger from a connected tool (not available yet), or someone opening control. > **Worth knowing.** A worker works on one event at a time. A second event in the same place waits; events in different places, for different clients, run on different copies and do not wait for each other. --- # Knowledge > What a worker knows: its memory and its skills. Both are files you can read and edit. Ergoly Docs › Workers. Web: https://www.ergoly.ai/docs/workers/knowledge · Index: https://www.ergoly.ai/docs/llms.txt A worker's **knowledge** is two things. **Memory** is what it remembers: facts about clients, preferences, how your agency likes things done. **Skills** are procedures it can run: a saved way of doing a piece of work. Both are plain files, kept in folders that decide who they apply to, and both are on the worker's **Knowledge** tab. *Diagram: Four levels your company owns, and the platform's underneath. A note in a narrower level wins over the same note in a broader one.* - [Memory](https://www.ergoly.ai/docs/workers/knowledge/memory): What it remembers, where a note lives, corrections, editing it yourself. - [Skills](https://www.ergoly.ai/docs/workers/knowledge/skills): What one is, where it lives, writing one, workers writing their own. --- # Memory > Your worker remembers what you tell it. A note about Acme stays with Acme; a rule for the whole agency applies everywhere. Ergoly Docs › Workers. Web: https://www.ergoly.ai/docs/workers/knowledge/memory · Index: https://www.ergoly.ai/docs/llms.txt Your worker remembers what you tell it. A note about Acme stays with Acme. A note about how you like decks written stays with the worker, for every client. A rule for the whole agency applies everywhere. If two notes disagree, the more specific one wins. ## Where a note lives The **Knowledge** tab shows one file tree with a folder per level, narrowest first. The names use your own: for a worker called Nora serving Acme, the folders read *Nora @ Acme (Private)*, *Acme (Client)*, *Nora (Worker)*, *Your agency (Org)*, and *Platform*. | Folder | Applies to | Example | | --- | --- | --- | | Private | This worker, in this one context. | Its own working notes. | | Client | Every worker serving this client. | Acme reads status notes on their phone: keep them short. | | Worker | This worker, for every client. | How Nora formats a meeting prep. | | Org | Every worker in your company. | We never quote prices in a client channel. | | Platform | Every worker on Ergoly. Written by Ergoly, read-only. | How to file a note; how to use a connected tool. | ## How the worker files a note When it learns something, the worker asks who it is true for: one client, this worker everywhere, or the whole company. It files there, and if it is unsure it files narrower. A client's copy can write only its own client's folder and its private one; your team's copy can write every client's, the worker's, and the company's. ## Corrections Correct the worker in the thread where the work happened. It fixes the work, writes the rule down in the same turn, and tells you where it put it. A correction about one client goes in that client's folder. A correction about the worker's conduct is proposed as a [behavior](https://www.ergoly.ai/docs/workers/behaviors) and added after your yes. ## Editing it yourself Everything except the Platform folder is yours to edit. In the memory browser: **New file** (a path such as `notes/pricing.md`, and the content), **Upload a file**, **Edit**, **Delete**. Pick the client in the context picker first to see that client's folder. A change reaches a running worker in about twelve seconds. - The `always/` folder in each level holds notes the worker reads in full at the start of every conversation. Keep it short: standing rules, not reference material. - The persona is not edited here; use the Identity card. Responsibilities and behaviors can be edited here or as cards on Overview, but not deleted. - Skills live in each level's `skills/` folder. See [Skills](https://www.ergoly.ai/docs/workers/knowledge/skills). > **Worth knowing.** Memory is files, not a database, so you can read it, diff it, revert it, and write it in any editor. Pushing a file through the API is the same as editing it in control. See [Where knowledge lives](https://www.ergoly.ai/docs/technical/where-knowledge-lives). --- # Skills > A saved way of doing a piece of work. Written by you in any editor, or by the worker when it has done something more than once. Ergoly Docs › Workers. Web: https://www.ergoly.ai/docs/workers/knowledge/skills · Index: https://www.ergoly.ai/docs/llms.txt A **skill** is a procedure saved as a file: a name, a line on when it applies, and the steps. When a worker has reasoned its way through the same job twice, the right move is to write it down, and then it runs the steps next time instead of working them out again. ## What one looks like *A SKILL.md* ``` --- name: weekly-status-note description: Write the weekly status note for a retainer client from the project tracker. Use on Monday mornings or when asked for a status. Stops short of sending it. --- 1. Pull every item that changed in the client's board since last Monday. 2. Group into done, in progress, blocked. Blocked first. 3. Keep it under 150 words. Lead with the blocked item that needs the client. 4. Post the draft in the client's internal channel and wait. ``` The same open format coding agents use for their own skills. The description matters most: it is what the worker reads to decide whether the skill applies. ## Where a skill lives A skill sits in the `skills/` folder of one memory level, and that decides who has it: one client, one worker, or the whole company. A skill of the same name in a narrower level shadows the broader one, so Acme can have its own way of doing status notes without anyone editing the shared skill. Your skills always beat Ergoly's. ## Writing one yourself 1. Write the SKILL.md in Claude Code, Cursor, or any editor. 2. Put it in the right level: the worker's Knowledge tab, **New file** or **Upload a file** under `skills//`, or push it through the API. 3. The worker has it on its next conversation. There is nothing to deploy. Already have skills written for Claude Code? Hand one to a worker in Slack and say *use this skill*. It rewrites it in its own words, maps the tools it needs to your connections, and offers a test run. For a whole set, ask your AI Admin to import them; it proposes which workers should own which. ## Workers writing their own ```slack #globex-internal Priya: @Nora that's the third time you've built the renewal summary the same way. Remember how this is done. Nora (worker): Written down as a skill, renewal-summary, in my own folder so it applies for every client. Next time I'll follow those steps rather than working them out. ``` *The worker writes the skill, checks it, and says where it filed it.* > **Worth knowing.** Around thirty skills, a worker is getting broad. Around fifty, split it into two workers with two roles. See [Role](https://www.ergoly.ai/docs/workers/role). --- # Connections > How a worker uses the tools it has been given. The tools themselves are set up under Work. Ergoly Docs › Workers. Web: https://www.ergoly.ai/docs/workers/connections · Index: https://www.ergoly.ai/docs/llms.txt A worker uses whatever **connections** reach it: apps your company has connected and placed with the company, with this worker, with a client, or with this worker for one client. The worker's **Connections** tab lists the apps that reach it in the chosen context, and nothing else. It never holds a password or a key. It calls the app by name, and Ergoly supplies the credential on the way out. Connect and place apps on the company's **Connections** page; the worker's tab is a view of the result. ## From Slack A worker can also ask for a connection itself, within its own reach. For an app that signs in, it posts a link anyone in the conversation can open; for an app that takes a key, you paste the key in the thread and it goes straight to the vault, never echoed back. A client's copy can place a connection only with itself for that client, or with that client. ```slack #acme-internal Sam: @Nora you'll need Acme's HubSpot for this. Nora (worker): I'll connect HubSpot for Acme only. Here's the sign-in link; it works for a few minutes. Once someone signs in, I can read Acme's pipeline. [Connect HubSpot to Nora for Acme] Opens a sign-in in a new tab · Placed with: Nora for Acme ``` - [Connections, under Work](https://www.ergoly.ai/docs/work/connections): Connecting a tool, placement, keys, custom tools, credential safety. --- # Clients > A customer of yours. Assign a worker to a client and that client gets its own copy, with its own memory and nothing of any other client's. Ergoly Docs › Clients. Web: https://www.ergoly.ai/docs/clients · Index: https://www.ergoly.ai/docs/llms.txt A **client** is a company you work for. On its own, a client in Ergoly is a record: a name, a website, a logo. It starts doing something when you assign a worker to it. From then on there is a copy of that worker for that client, and every channel and person you link to the client reaches that copy. The **Clients** page lists them with tabs for Active, Inactive and Archived, and each client's page has four tabs: **Overview** (the About text, details, and Channels & People), **Workers**, **Tasks**, and **Connections**. - [Adding a client](https://www.ergoly.ai/docs/clients/adding): From the AI Admin, the Clients page, or the chart. - [Assigning a worker](https://www.ergoly.ai/docs/clients/assigning-a-worker): What it creates, and the channels and people that go with it. - [Client separation](https://www.ergoly.ai/docs/clients/separation): What a client's worker can and cannot see. - [Internal client channels](https://www.ergoly.ai/docs/clients/internal-channels): Backstage before the client channel. --- # Adding a client > Three ways: ask your AI Admin, press New Client, or let a worker create one when it joins a channel. Ergoly Docs › Clients. Web: https://www.ergoly.ai/docs/clients/adding · Index: https://www.ergoly.ai/docs/llms.txt ## Ask your AI Admin Tell it the client's name and, if you have it, the website. It confirms what it is about to create and does it on your yes. ```slack Direct message with Ada Sam: Add Globex as a client. globex.example Ada (worker): I'll create the client Globex with globex.example as its website, which gives it a logo and a description. No worker is assigned yet; tell me which one when you're ready. OK? Sam: OK Ada (worker): Done. Globex is in the tray on your Company chart until someone places it. ``` ## In control 1. Open **Clients** and press **New Client**, or open **Company**, press **Add**, and choose **Client**. 2. Type the **Company name**. The slug under it is the client's short name in URLs; click it to change it. 3. Add the **Website URL** if you have it. Ergoly uses it for the logo and a public description. 4. Optionally paste a **Slack Channel ID** for the channel you share with the client. You can do this later from the worker instead. 5. Press **Create client**. ## From a channel When a worker joins a channel and no client matches, it offers **New client…**. That creates the client and maps the channel to it in one step. See [Slack](https://www.ergoly.ai/docs/workers/channels/slack). > **Worth knowing.** A client with no worker assigned does nothing. The next step is [assigning a worker](https://www.ergoly.ai/docs/clients/assigning-a-worker). --- # Assigning a worker > Bind a worker to a client, with at least one channel or person. That creates the client's own copy of the worker. Ergoly Docs › Clients. Web: https://www.ergoly.ai/docs/clients/assigning-a-worker · Index: https://www.ergoly.ai/docs/llms.txt Assigning a worker to a client creates a separate copy of that worker for that client. The copy starts with the company's knowledge and the worker's own, plus the client's folder, which is empty until the worker learns something. Everything it learns about Acme goes there and nowhere else. ## How 1. On the client's page, press **Bind a Worker**. Or on the worker's **Clients** tab, press **Add to client**. 2. Pick the **Worker** (or the **Client**). 3. Tick the **Channels** that belong to this client, and the **People** who are this client's contacts. At least one of either. The dialog explains the difference: *channels route by conversation, people route their DMs and group DMs*. 4. Press **Bind worker**. Control maps the channels, joins the public ones (private ones need you to `/invite` the worker first), links the people, and builds the copy. If building fails, the binding stays and the row offers **Activate** to try again. Or ask your AI Admin: *assign Nora to Globex in #globex*. ## Already taken A channel or person already linked to a different client is greyed out. Nothing is moved silently. To move a channel, use **Reassign** on the worker's Clients tab and confirm. ## Removing **Unbind** on the client's Workers tab, or **Remove** on the worker's Clients tab, removes every channel and person link for that pair and everything the worker set up for the client. The client's folder of knowledge stays with the client. | | What it reaches | | --- | --- | | Your team's copy of Nora | Every client's folder, the worker's, the company's | | Nora for Acme | Acme's folder, the worker's, the company's | | Nora for Globex | Globex's folder, the worker's, the company's | > **Worth knowing.** Your AI Admin cannot be assigned to a client. It is internal-only by design. --- # Client separation > What a client's copy of a worker can see, what it cannot, and what a client's contact can do. Ergoly Docs › Clients. Web: https://www.ergoly.ai/docs/clients/separation · Index: https://www.ergoly.ai/docs/llms.txt The copy of a worker that serves Acme has Acme's folder, the worker's own knowledge, and the company's. It does not have Globex's folder, Globex's connections, or Globex's people. There is no setting that changes this, and nothing a person types in Acme's channel can change it either, because which copy answers is decided from the channel before the worker reads a word. | | Nora for Acme | Your team's Nora | | --- | --- | --- | | Acme's notes and preferences | Yes | Yes | | Globex's notes and preferences | No | Yes | | Connections placed with Acme | Yes | No, unless also placed wider | | Connections placed with the whole company | Yes | Yes | | People on the Company chart | Acme's own contacts and the workers serving Acme | Everyone | | Globex's channel | Never | Never; that is Globex's copy's | ## What a client's contact can do - Talk to the worker in their channel, and DM it once they are linked to the client. - Stop the worker's reply to their own message with `stop`. - Press buttons the worker posts for them, and ask it to be quieter. ## What a client's contact cannot do - Add the worker to a channel, or set a channel up. Only your workspace's admins can. - Stop a scheduled run. Only your own people can. - Reach your team's copy of the worker, or anything about another client. ## What travels up A fact about Acme stays with Acme. A lesson about the job, filed in the worker's folder by your team's copy, reaches every client. That is the point: the worker gets better at the work for everyone, and no client ever sees another's. See [Memory](https://www.ergoly.ai/docs/workers/knowledge/memory). > **Worth knowing.** A client channel is never answered by your team's copy, even if the client's copy is down. Silence is the safe failure. - [How a worker runs](https://www.ergoly.ai/docs/technical/how-a-worker-runs): The copies, underneath. - [How credentials are held](https://www.ergoly.ai/docs/technical/how-credentials-are-held): Why a client's keys never reach another client's copy. --- # Internal client channels > Backstage: a channel of your own where the team reviews a worker's drafts for a client before the worker is in front of that client. Ergoly Docs › Clients. Web: https://www.ergoly.ai/docs/clients/internal-channels · Index: https://www.ergoly.ai/docs/llms.txt Before a worker talks to Acme directly, give it a channel where your team can see what it would say. That channel is **internal**, because only your people are in it, but the work in it is about one client. ## Setting it up 1. Create the channel in Slack with your own people in it. 2. Invite the worker. When it asks what the channel is for, press **Internal channel**, not the client. 3. Ask the worker for the client's work there: *draft Acme's weekly status*. Your team's copy answers, with Acme's folder in reach, so the draft is about Acme. 4. When the drafts are right, invite the worker to the channel Acme is in, and set that one up for Acme. ```slack #acme-internal Sam: @Nora draft Acme's weekly status for Monday. Don't send anything. Nora (worker): Draft below. Blocked first, 131 words. Tell me what to change and I'll keep the rule for Acme. [Acme · weekly status · draft] Blocked: launch date needs Acme's sign-off · In progress: 14 of 22 pages · Done: identity approved Priya: Good. Swap the second line for the legal edits, then it's ready. ``` *The team reviews in the internal channel. Nothing reaches Acme until someone sends it.* ## Why it is internal Because your team's copy answers there, it knows the whole company: every client, every connection placed with the company. That is what you want backstage. In Acme's own channel, only Acme's copy answers, which knows less, on purpose. See [Client separation](https://www.ergoly.ai/docs/clients/separation). > **Worth knowing.** Keep client contacts out of the internal channel. The channel decides who is answered, so a guest in an internal channel would be answered by your team's copy. --- # Work > What a worker does between conversations: tasks and routines, the tools it is connected to, approvals, and the pages it publishes. Ergoly Docs › Work. Web: https://www.ergoly.ai/docs/work · Index: https://www.ergoly.ai/docs/llms.txt Conversations are where a worker is asked. **Work** is what it carries: tasks handed to it and by it, routines that run on a schedule, the connections it uses, the approvals it waits for, and the artifacts it publishes. In control these are the **Tasks**, **Artifacts**, **Connections** and **Activity** pages. - [Tasks](https://www.ergoly.ai/docs/work/tasks): Handing work to a worker or a person, and where results go. - [Routines](https://www.ergoly.ai/docs/work/routines): Tasks that repeat, and running one across clients. - [Connections](https://www.ergoly.ai/docs/work/connections): Connecting a tool, and who may use it. - [Approvals](https://www.ergoly.ai/docs/work/approvals): Asking first, the buttons, and the activity feed. - [Artifacts](https://www.ergoly.ai/docs/work/artifacts): Pages a worker publishes with a link. --- # Tasks > A piece of work with someone who asked and someone doing it. Hand it to a worker or a person, follow it on its log, and say where the result goes. Ergoly Docs › Work. Web: https://www.ergoly.ai/docs/work/tasks · Index: https://www.ergoly.ai/docs/llms.txt A **task** has a **requester** (who asked), a **holder** (who is doing it), and a **log** (every handoff, comment, state change and run). Workers and people can be either. Handing a task to another worker is the only way one worker asks another for something. ## From Slack Ask in plain words. Work the worker cannot finish in one go, or work that belongs to someone else, becomes a task. It names the holder, and from then on the task's log is where the work is tracked. ```slack #acme-internal Nora (worker): Acme asked whether the launch can move a week. That's a scope and budget call, so I've opened a task and handed it to @Sam: Acme launch date — move one week? I'll reply to Acme once you decide. Sam: Yes, one week is fine. Confirm with them and update the plan. Nora (worker): Resolved. I've told Acme Thursday the 30th, and moved every date in the plan a week. ``` *A person's comment on a task wakes the worker. The worker's own comments wake nobody.* ## The Tasks page Three tabs, each with a count: **Scheduled**, **In progress**, **Closed**. Columns: Task, Runs on (the worker), Requester, Holder, Due (marked *Late* when past), Schedule. A task's own page shows its state, the people on it, where results go, its **Log**, and its **Run history**, with buttons for a person: **Start**, **Resolve**, **Hand off…**, **Decline**, and **Cancel task**. ## States and outcomes | State | Meaning | | --- | --- | | Scheduled | Not started yet: it has a schedule or a start time. | | In progress | Someone holds it. | | Closed · resolved | The requester is satisfied. | | Closed · declined | The holder said no. Only the holder can decline. | | Closed · cancelled | Withdrawn. | | Closed · archived | No activity for the company's archive period (30 days by default; Settings → Tasks). | ## Where results go A task names where its results go: a Slack channel the worker is in, a person (by DM), or nowhere, in which case the result stays on the log. A task scheduled from a DM sends its result back to that person. A task about a client can only be handed to a worker serving that client, or to a person. > **Worth knowing.** The worker works a task by scoping it, planning and doing it, checking its own result, and resolving. After two attempts that still fall short, it hands the task to a person rather than trying a third time. --- # Routines > A task that repeats. Describe it once, say where results go, and point it at every client it should run for. Ergoly Docs › Work. Web: https://www.ergoly.ai/docs/work/routines · Index: https://www.ergoly.ai/docs/llms.txt A **routine** is a task with a schedule. Every weekday at 9, the first of the month, every hour. It runs on the worker you name, posts where you said, and keeps a run history. In control, routines live on the **Tasks** page under **Scheduled**. ## From Slack ```slack #acme-internal Sam: @Nora every weekday at 9 Pacific, post Acme's status note here. Nora (worker): Scheduled: Acme status note, weekdays at 09:00 America/Los_Angeles, results posted in #acme-internal. First run is tomorrow. Say pause the status note to pause it. ``` *The worker repeats the schedule, the time zone, and where results go. Without a destination it will not schedule.* Say when, and say where results go. If you leave out the time zone the worker asks; if you leave out the destination it refuses, because a routine that posts nowhere is a routine nobody sees. Asking for the same routine again replaces it rather than making a second one. ## From control Press **New task** on the Tasks page: the **Worker**, a **Title**, the **Prompt** (what the worker should do, written so it makes sense on its own), **Scope** (Internal or a client), a **Schedule** (**Once** or **Recurring**: every few minutes, hourly, daily, weekly, monthly, or a cron expression), a **Timezone**, and an optional **Slack channel**. Leave the channel blank and the result stays on the run log. ## Running across clients One routine can run for several clients, each on that client's own copy of the worker, each posting to that client's channel. On the task's page, the **Clients** card has **Add a client**; each client can have its own channel and time zone, and can be ticked on or off. From Slack, ask your team's copy: *run it for Acme and Globex*. A client's copy cannot fan out; it only knows one client. ## Pausing and cancelling - *Pause the Monday report* pauses it. The schedule is kept; on resume it runs from now without catching up. - *We don't want it any more* cancels it for good. - In control: **Disable** / **Enable** or **Delete** on the row's Actions menu, and **Run now** to run it immediately. ## Run history Every run is listed on the task's page and on each client's Tasks tab, with started, finished, duration, worker, client, where it posted, and any error. Filter by worker, client, or status. > **Worth knowing.** The routine's prompt is read by the worker's future self with no conversation around it. Write it the way you would brief someone on their first day: what, for whom, where it goes. --- # Connections > The apps, keys and tool servers your company has connected, and who may use each one. Ergoly Docs › Work. Web: https://www.ergoly.ai/docs/work/connections · Index: https://www.ergoly.ai/docs/llms.txt A **connection** is an app your workers can use: a CRM you signed in to, an API you pasted a key for, a tool server at a URL. Every connection is **placed**: with the whole company, one worker, one client, or one worker for one client. Placement is the whole of who may use it. The **Connections** page lists them by category, with a status and an **Actions** menu (Open, Rename, Reconnect, Remove) on each. - [Connecting a tool](https://www.ergoly.ai/docs/work/connections/connecting-a-tool): Sign in, paste a key, or give a server's address. - [Placement](https://www.ergoly.ai/docs/work/connections/placement): Company, worker, client, or worker for one client. - [Keys and tools](https://www.ergoly.ai/docs/work/connections/keys-and-tools): What a key connection is, and what a worker does with it. - [Custom tools](https://www.ergoly.ai/docs/work/connections/custom-tools): A tool server by URL, or any API by its base URL. - [Credential safety](https://www.ergoly.ai/docs/work/connections/credential-safety): Why your worker never holds a password. --- # Connecting a tool > Press Add Connection, pick the app, choose who may use it, and sign in or paste a key. Ergoly Docs › Work. Web: https://www.ergoly.ai/docs/work/connections/connecting-a-tool · Index: https://www.ergoly.ai/docs/llms.txt 1. On **Connections**, press **Add Connection**. 2. **Pick the app.** Search the catalog of more than 1,500 apps, or browse by category. Under the results, two other ways in: **A tool server** by URL, or **An API key for another app** by its base URL. See [Custom tools](https://www.ergoly.ai/docs/work/connections/custom-tools). 3. **Access.** Choose who may use it. The narrowest option is the default. See [Placement](https://www.ergoly.ai/docs/work/connections/placement). 4. **Name** it, and add a **Description** in your own words. Workers read the description to decide when to use it. 5. **How to connect.** **Sign in** opens the app's own sign-in in a new tab; every worker placed here then acts as the account you sign in with. **Use a key** takes a key, checks it once, and keeps it out of every worker's reach. **No sign-in** is for tools that need none. 6. Press **Connect** and finish in the other tab. The person who signs in does not need an Ergoly account. ## From Slack A worker can ask for a connection within its own reach, posting a sign-in link that lasts a few minutes or taking a key pasted in the thread. A workspace admin can also DM a worker `connect `, such as `connect hubspot`, and get a link. Your AI Admin can connect an app for any worker and place it anywhere. See [Connections, under Workers](https://www.ergoly.ai/docs/workers/connections). ## Later A connection's status is **Active**, **Waiting for sign-in**, **Expired**, **Failed** or **Revoked**. **Reconnect** on the card offers **Finish sign-in**, **Sign in again**, or **Replace key** as the status calls for. **Send reconnect links** at the top DMs each person who owns a pending sign-in with their links. **Remove** confirms on the card. > **Worth knowing.** If you would rather the sign-in screen show your agency's name than Ergoly's, add your own OAuth app under the **Legacy** tab, **Your OAuth apps**, with its client ID, secret, and the redirect URI control gives you to register. --- # Placement > Who may use a connection: the whole company, one worker, one client, or one worker for one client. The narrowest match wins. Ergoly Docs › Work. Web: https://www.ergoly.ai/docs/work/connections/placement · Index: https://www.ergoly.ai/docs/llms.txt Every connection is placed somewhere, and the placement alone decides which copies of which workers can use it. There is no other switch. | Placement | Who can use it | | --- | --- | | One worker for one client | Only that worker, and only when it is working for that client. The default. | | One client | Every worker, when it is working for that client. | | One worker | That worker, for every client and for the company. | | Whole company | Every worker, everywhere. | *Diagram: Acme's HubSpot, placed with Acme, reaches Nora for Acme and nobody else. The company's Google Drive reaches every copy of every worker.* ## Narrowest wins When the same app is connected at two placements, a copy uses the narrowest one that matches it. Acme's own HubSpot, placed with Acme, beats the company-wide HubSpot for Acme's copy of Nora. Globex's copy, with no HubSpot of its own, uses the company's. ## Changing a placement Open the connection and change its access. Before you add, move or remove a placement, control shows who **Gains it**, who **Loses it**, and who **Keeps it**. A connection must keep at least one placement; to take it away from everyone, remove the connection. On a card, placement reads *Everyone (Company)*, *Nora (Worker)*, *Acme (Client)*, or *Nora for Acme*. A client's page lists the connections that reach that client, marking the ones inherited from the company. > **Worth knowing.** A client's accounts belong with that client. Place them with the client, not the company, and no other client's copy can ever reach them. See [Client separation](https://www.ergoly.ai/docs/clients/separation). --- # Keys and tools > What happens when you paste a key, and what a worker can then do with the app. Ergoly Docs › Work. Web: https://www.ergoly.ai/docs/work/connections/keys-and-tools · Index: https://www.ergoly.ai/docs/llms.txt Some apps are connected by signing in. Others take an **API key** you paste. Either way the result is the same to a worker: an app it can use by name. ## A pasted key Choose **Use a key** when connecting. The key is checked once, with one read that succeeds with the key and fails without it, so a wrong key is refused on the spot. A key that passes is stored and never shown again, not to you and not to any worker. A worker that needs it calls the app, and Ergoly supplies the key on the way out. ## What a worker does with an app A connected app gives a worker a set of actions: read a deal, create a page, search a folder. Each turn, the worker is shown the connections that reach it, with your description of each. It picks the one that fits, calls it by name, and reports what it did. Two connections of the same app at the same placement are both offered, and the worker says which one it used. ```slack #acme Daniel · Acme: @Nora how many open deals do we have over $50k? Nora (worker): Seven, totalling $612k. Three are past their close date; I've listed them in the thread. Read from Acme's HubSpot. ``` ## When a key stops working If the app refuses the key, the connection's status becomes **Expired** and the worker tells whoever asked that the app needs reconnecting. **Reconnect** on the Connections page takes a new key or a fresh sign-in. > **Worth knowing.** A key pasted into a Slack thread goes straight into the vault and is never echoed back. Still, prefer pasting keys in control when you can. --- # Custom tools > Any tool server by its URL, or any API by its base URL, when the catalog does not list the app. Ergoly Docs › Work. Web: https://www.ergoly.ai/docs/work/connections/custom-tools · Index: https://www.ergoly.ai/docs/llms.txt The catalog covers most apps. For anything else, **Add Connection** offers two other ways in, under the search results. - **A tool server**: Paste an `https://` URL. The server says how it signs in: a hosted sign-in, a key, or nothing. Once connected, Ergoly reads the tools it offers, and your workers get them as actions, the same as a catalog app. - **An API key for another app**: Paste the API's **base URL**, your key, and the **header the key is sent in**. Workers can then call any endpoint on that API. Add a link to its docs and workers read them to learn the endpoints. Both are placed like any other connection, and both keep the credential out of every worker's reach. > **Worth knowing.** Give the API's documented base URL, not its website. A key is attached to the hostname you give, and a request that gets redirected to a different host leaves the key behind. --- # Credential safety > A worker never holds a password or a key. The credential is added to the request on the way out, by a part of Ergoly the worker cannot reach. Ergoly Docs › Work. Web: https://www.ergoly.ai/docs/work/connections/credential-safety · Index: https://www.ergoly.ai/docs/llms.txt When a worker uses a connected app, it never sees the key or the token. It makes the call, and a gateway between the worker and the internet matches the request against the connections placed within that worker's reach, adds the credential, and sends it on. The credential exists in Ergoly's vault and on the wire to the vendor, and nowhere in between. - No screen in control, and no answer from the API, ever shows a stored key. **Reconnect** replaces it; nothing reveals it. - A sign-in that needs consent needs a person. The worker posts a link to open; nothing exists until the consent finishes. - A key pasted in Slack goes into the vault and is never repeated in the thread. - A connection placed with Acme is never added to a request from Globex's copy, because the gateway checks placement before it adds anything. Why it is built this way: a worker is a program that reads messages from people outside your agency. If it held a key, a clever message could ask it to repeat the key. It cannot repeat what it does not have. - [How credentials are held](https://www.ergoly.ai/docs/technical/how-credentials-are-held): The vault and the gateway, in detail. --- # Approvals > A worker asks before it acts when you tell it to, and on its own for anything hard to undo. The decision is recorded. The activity feed holds everything else. Ergoly Docs › Work. Web: https://www.ergoly.ai/docs/work/approvals · Index: https://www.ergoly.ai/docs/llms.txt ## Asking for approval Tell the worker in plain words: *ask me before sending anything to a client*, *get approval before you change a price*, *confirm with Priya first*. To make the rule permanent, have it added to the worker's [behaviors](https://www.ergoly.ai/docs/workers/behaviors). A worker also asks on its own for anything with a big consequence that is hard to undo: money, a first send to a client, deleting things, terms, changing who has access. ## Approve and Reject in Slack The worker posts what it is about to do, with two buttons in the conversation's own words, usually **Approve** and **Reject**. Only the first press counts. The platform replaces the buttons with one line saying who pressed which and when, so the thread is its own record. If someone other than the person it asked presses, the worker asks that person to confirm in the thread. ```slack #globex-internal Nora (worker): Globex's launch email is drafted for Thursday 8:00 to 1,240 subscribers. Approve to schedule it. [Approve · Reject] Launch email · Globex · Thursday 8:00 · 1,240 recipients Priya: Approved. Nora (worker): ✅ Approve — Priya · Oct 22 at 14:02. Scheduled. ``` *The buttons retire the moment they are used.* ## The activity feed The **Activity** page is an append-only log of everything that happens across your company: who did it and when. Entries can never be edited or deleted. Columns: When, Actor, Kind, Summary. Filter by area, or by who did it, where *system* means your workers and your API keys. Every change made with a key is here under the key's name, which is why revoking a key never erases what it did. > **Worth knowing.** Escalation is different from approval. An approval goes to whoever the worker was told to ask, in the thread. An escalation is a question that needs a person, and goes to the worker's escalation assignee. See [Reporting](https://www.ergoly.ai/docs/workers/reporting). --- # Artifacts > A web page a worker publishes with a link: a report, a dashboard, a one-pager. Private to your company by default, or open to anyone with the link. Ergoly Docs › Work. Web: https://www.ergoly.ai/docs/work/artifacts · Index: https://www.ergoly.ai/docs/llms.txt ## Creating one Ask the worker for anything you would rather pass around as a link: a report, a dashboard, a chart, a comparison, a one-pager, a calculator. It builds a self-contained page, publishes it, and replies with the link and whether it is private or public. Ask for changes and a new version appears at the same link. ```slack #acme-internal Sam: @Nora turn the Q3 numbers into a one-page dashboard I can send to Acme. Nora (worker): Published, private to your company: control.ergoly.ai/youragency/a/k8f2… Say make it public and anyone with the link can open it. [Acme · Q3 dashboard] Private · People in Your agency · Location: Acme ``` ## Publishing and locations Every artifact has a **Location**: your company, or one client. The location decides which workers can find and read it: all of them, or only that client's. A new artifact's location follows the worker that made it. Any signed-in member of your company can open every artifact, whatever its location. The **Artifacts** page lists them all, with filters for author, location and sharing. ## Privacy and sharing On the artifact's page, the **Sharing** popover offers **Private** (people in your company) or **Public** (anyone with the link, no sign-in). New artifacts are private. There is no delete: setting an artifact back to private is how you take it down. > **Worth knowing.** A page can hold a lot: up to 4.5 MB, with charts and tables. It cannot hold live data, forms, or anything that stores what a reader types. - [Collaboration](https://www.ergoly.ai/docs/work/artifacts/collaboration): Coming soon. --- # Collaboration > Commenting on an artifact, and the worker picking the comments up. Ergoly Docs › Work. Web: https://www.ergoly.ai/docs/work/artifacts/collaboration · Index: https://www.ergoly.ai/docs/llms.txt **Coming soon.** Today, ask the worker for the change in Slack and it publishes a new version at the same link. When collaboration ships, you and a client will comment on a published page, and the worker will read the thread and publish the next version. Until then, the conversation about an artifact happens in Slack. --- # Technical details > What happens behind the words in these docs, for the engineer at your agency or anyone on the API. Ergoly Docs › Technical details. Web: https://www.ergoly.ai/docs/technical · Index: https://www.ergoly.ai/docs/llms.txt The rest of the docs use the words control shows you: Company, Worker, Client, Channel, Knowledge, Task. This section explains what each one is underneath, and gives the name the API uses for it. You do not need any of this to run Ergoly. You need it if you are writing code against the API, or if you want to know exactly where something lives. - [How a worker runs](https://www.ergoly.ai/docs/technical/how-a-worker-runs): Turns, eworks, and why each client gets its own copy. - [Where knowledge lives](https://www.ergoly.ai/docs/technical/where-knowledge-lives): The five tiers, and why the narrowest one wins. - [How a channel reaches a worker](https://www.ergoly.ai/docs/technical/how-a-channel-reaches-a-worker): Channel mappings, routing, and dispatch. - [How credentials are held](https://www.ergoly.ai/docs/technical/how-credentials-are-held): The vault and the egress gateway. - [The API](https://www.ergoly.ai/docs/technical/api): Keys, the reference, and your first call. - [Glossary](https://www.ergoly.ai/docs/technical/glossary): The docs' word, the API's name, the internal word. --- # How a worker runs > A worker is one identity. Each client it serves gets a separate running copy, and each message it handles is one turn. Ergoly Docs › Technical details. Web: https://www.ergoly.ai/docs/technical/how-a-worker-runs · Index: https://www.ergoly.ai/docs/llms.txt A **worker** (a *Worker* in the API) is one Slack app with one name. It does not run as one process. For each client you assign it to, Ergoly starts a separate copy with its own sandbox, its own memory, and its own set of files. The API calls each copy an **ework**; internally they are also called postings. ## One copy per client, plus one for you Say your worker Nora serves Acme and Globex. There are three copies of Nora: one for Acme, one for Globex, and one for your own team. The Acme copy has Acme's memory and nothing of Globex's. Your team's copy has every client's memory, which is why your own people can ask it about any account. | Copy | API name | Serves | Holds | | --- | --- | --- | --- | | Your team's | core ework | your internal channels and your own people's DMs | company memory, Nora's memory, and every client's memory | | Acme's | client ework | Acme's channel and Acme's people | company memory, Nora's memory, Acme's memory only | | Globex's | client ework | Globex's channel and Globex's people | company memory, Nora's memory, Globex's memory only | Which copy handles a message is decided before anything runs, from the channel and the sender. The copy for Acme can never be handed a Globex message, so there is no rule a persuasive message could talk it out of. That decision is described in [How a channel reaches a worker](https://www.ergoly.ai/docs/technical/how-a-channel-reaches-a-worker). ## Turns A **turn** is one round trip: a message arrives, one copy of the worker works on it, and one reply goes back. The message can come from Slack, from a scheduled routine, from a webhook, or from a task's log changing. A copy handles one turn at a time. A message that arrives while a turn is running waits and is handled next; a run of messages from the same person is folded into one turn. While a turn runs, Slack shows one message that fills in as steps complete. The worker writes Markdown and Ergoly converts it for Slack, so what it writes is what you read. ## Sleep and wake A copy that has been idle for a few minutes goes to sleep, and the next message wakes it in a few seconds. There is no setting for this and nothing to keep awake. A sleeping copy is healthy, and a copy that answers after a quiet hour is proof the platform is working. ## What a copy can do Every copy has the same five tools: read a file, write a file, edit a file, run a shell command, and act in Slack. Everything else a worker does, from calling an app to scheduling a routine, is a skill it runs through the shell. A copy also has an email address, a sandbox with a file system and the web, and whatever connections have been placed within its reach. > **Worth knowing.** The API's `workers` resource is the identity. Its `eworks` resource lists the copies, read-only: a copy is created by assigning a client and removed by unassigning one, never directly. --- # Where knowledge lives > Memory and skills are files in five tiers, and when two tiers disagree the narrowest one wins. Ergoly Docs › Technical details. Web: https://www.ergoly.ai/docs/technical/where-knowledge-lives · Index: https://www.ergoly.ai/docs/llms.txt A worker's **knowledge**, its memory and its skills, is a set of Markdown files. The files are held in **tiers** (the API's word too). Four tiers belong to your company; one belongs to Ergoly. | Docs word | Tier | Belongs to | Who writes it | | --- | --- | --- | --- | | One copy's own notes | instance | one running copy of a worker | that copy | | Client knowledge | client | one client | that client's copy, your team's copy, you | | Worker knowledge | worker | one worker, across all its clients | any copy of that worker, you | | Company knowledge | org | your company | you, and your team's copies | | Platform knowledge | system | Ergoly | Ergoly only; read-only for everyone else | *Diagram: Five tiers. A copy of a worker reaches its own, its client's, its worker's, the company's, and the platform's.* ## Narrowest wins When two tiers hold a file with the same name, the narrower tier's file is the one the worker reads. A note about decks in Acme's tier beats a note about decks in Nora's tier, which beats one in the company's, which beats Ergoly's. That is how one client, or one worker, can state an exception without anyone editing the shared text. The same rule covers skills. A skill of the same name in a narrower tier shadows the broader one. Ergoly's own skills sit at the bottom, so anything you write wins over anything we ship. ## What each copy reaches Acme's copy of Nora mounts four tiers: company, Nora, Acme, and its own. Your team's copy mounts company, Nora, its own, and **every** client's tier, so it can file a fact about Acme in Acme's tier. No copy ever sees another worker's tier, and a client's copy never sees another client's. ## The files Each tier has an `always/` folder, whose documents the worker reads in full at the start of every turn, in filename order. A worker's persona, its responsibilities and its behaviors are three such files in its worker tier. Each tier also has a `skills/` folder, where every skill is a directory with a `SKILL.md`. Everything else is indexed and read when the worker needs it. ## Every change is a commit Each tier is a private git repository that Ergoly creates and fronts. A change you make in control, through the API, or that a worker makes itself is a commit, and reaches every running copy that mounts that tier within about twelve seconds. Nothing restarts. You can see the history, revert a change, and write the files in any editor. > **Worth knowing.** The `memory` resource in the API is addressed by ework, because which tiers exist depends on which copy you ask about. Read with no tier named and the answer lists the tiers that copy reaches. --- # How a channel reaches a worker > Every Slack message is routed to one copy of one worker by a fixed rule, before any model runs. Ergoly Docs › Technical details. Web: https://www.ergoly.ai/docs/technical/how-a-channel-reaches-a-worker · Index: https://www.ergoly.ai/docs/llms.txt A **channel** in the docs is any place a worker operates. For Slack, the thing underneath is a **channel mapping** (the API's `channels` resource): a record that says which client a Slack channel belongs to, or that it is one of your own. Routing is the code that reads those records. *Diagram: A message in a channel becomes an event, the event is routed to one copy of a worker, and that copy takes a turn.* ## The rule, in order | Question | Answer | | --- | --- | | Is this Slack channel mapped to a client? | That client's copy of the worker. | | Is it a direct message from someone bound to a client? | Their client's copy. | | Is the sender one of your company's own people? | Your team's copy. | | Anyone else | One sentence saying it cannot help here, and no worker runs. | The questions are asked in that order, and the first yes decides. No model is consulted. Which client a turn is about is therefore fixed by which copy runs it, never by anything in the message. ## A mapping is a decision A channel is mapped to a client, or marked internal. Both are explicit records. A channel with no mapping at all routes nowhere, and is not treated as internal. Moving a channel that is already mapped to one client onto another has to be confirmed, so a re-point is always something you asked for twice. Direct messages are never mapped. A DM routes by who is in it, through that person's binding to a client. That is one route to the answer rather than two, so there is nothing to disagree. ## Dispatch Once the copy is chosen, the message is signed and sent to that copy's sandbox, which has its own key. The reply comes back as a stream of pieces (text, a progress step, a request to send a message) and is posted to Slack by the platform, never by the copy. A copy never holds a Slack token. A message that arrives while that copy is busy is queued and handled next. A run of messages from one sender is folded into one turn; messages from two senders are two turns. > **Worth knowing.** Routines, webhooks, and a task's log changing start turns the same way: the platform decides which copy, then dispatches. A routine for Acme fires on Acme's copy, and a webhook aimed at an Acme channel is refused if that channel is ever re-mapped to someone else. --- # How credentials are held > A worker never holds a password or a key. A gateway puts the secret into the request on the way out. Ergoly Docs › Technical details. Web: https://www.ergoly.ai/docs/technical/how-credentials-are-held · Index: https://www.ergoly.ai/docs/llms.txt A **connection** in the docs is a credential your company holds and a record of who may use it. Underneath, the credential sits in a **vault** and is used by an **egress gateway**: a proxy every copy of every worker sends its outbound traffic through. ## The placeholder When a copy of a worker calls an API, it does not send the key. It sends the literal word `egress-managed` where the key would go. The gateway matches the request's hostname against the connections placed within that copy's reach, swaps the placeholder for the real secret, and forwards the request. The secret exists in the vault and on the wire to the vendor, and nowhere in between. *A call from inside a worker's sandbox* ``` # What the worker sends. The gateway replaces the placeholder in place, # keeping whatever scheme surrounds it. curl -sS "https://api.example.com/v1/me" \ -H "Authorization: Bearer egress-managed" ``` ## Reach A connection is placed with the company, one worker, one client, or one worker for one client. The gateway resolves the narrowest placement that matches. Acme's accounts, placed with Acme, are injected only into Acme's copy; Globex's copy cannot see that they exist. A connection with no placement is inert. *Diagram: Four placements. The narrowest one that matches the copy and the hostname is the one the gateway uses.* ## Nothing comes back out No API response ever contains a stored secret, on create, on read, or after a rotation. Reading one back in the clear is a browser-only act by a person on the Connections page, and it is recorded against their name. Connecting an account that needs a sign-in hands you a link to open; nothing exists until the consent finishes. ## Connected apps Apps from the catalog, and tool servers, work through a tool platform rather than the gateway: the account's token is held there, and a copy calls the app through control, which signs the call with the copy's own key. The same placement rules decide who may use it, and the copy still never sees the token. > **Worth knowing.** The platform API key a worker uses to call Ergoly itself is held the same way. It is placed at one worker's tier and injected by hostname, which is why the API answers on its own host: a call to control's own address would bypass the gateway and arrive with no credential. --- # The API > One key per company, one header, one envelope. The reference is served by the API itself. Ergoly Docs › Technical details. Web: https://www.ergoly.ai/docs/technical/api · Index: https://www.ergoly.ai/docs/llms.txt Anything you can click in control, a key can do from a terminal or from a coding agent: create workers, add clients, map channels, schedule routines, connect tools, read the activity feed. Every call is scoped to the company the key belongs to, and there is no parameter that widens it. ## Access and keys Keys belong to the company, not to a person. Anyone holding one acts as the whole company, and every write it makes is recorded under the key's own id. Only an admin can mint or revoke a key, in control under **Settings**, on the **API keys** tab. A key is shown once. Give it an expiry if the job it does has an end; revoking takes effect from the next request. A worker can hold a key too. Your AI Admin does, placed at its own tier and injected by the gateway, which is what lets it set up your company from Slack. See [Access](https://www.ergoly.ai/docs/company/access). ## Calling a worker from the web A **webhook** is a URL an outside system can POST to. Each one belongs to a worker and names a Slack channel or a person; a delivery starts a turn, and the answer lands there. Creating one returns a `whsec_` secret, shown once and stored hashed; send it as a Bearer token on every delivery. Lose it and you rotate. Deliveries are accepted with a 202 and a delivery id, and the turn runs afterwards. See [Web](https://www.ergoly.ai/docs/workers/channels/web). ## The reference The reference is served by the API, to the same key the API takes, so a coding agent can fetch how to call it with the header it already has. It comes back as Markdown by default, JSON when asked for, and HTML in a browser, all from one source. | What | Where | | --- | --- | | The overview, the one page that answers without a key | `https://control.ergoly.ai/api/v1` | | The reference index, one entry per resource | `https://control.ergoly.ai/api/v1/docs` | | One resource page | `https://control.ergoly.ai/api/v1/docs/{resource}` | | The whole contract as OpenAPI 3.1 | `https://control.ergoly.ai/api/v1/openapi.json` | *Your first call: which company does this key belong to?* ``` export ERGOLY_API_KEY="" curl -sS "https://control.ergoly.ai/api/v1/organization" \ -H "Authorization: Bearer $ERGOLY_API_KEY" ``` ## The shape of every answer - A single resource answers `{"data": …}`. A list answers `{"data": […], "page": …}`, and `page` is there even when there is nothing more. - Paging is by cursor: pass `limit` and the previous page's `nextCursor`. A page stays stable while rows are written underneath it. - An id that belongs to another company answers 404, the same 404 an id that never existed gets. - A write that can create real infrastructure takes an `Idempotency-Key`. A retry is answered from the first attempt; the same key with a different body is a conflict. - Every refusal carries a machine-stable `code`. Branch on it, never on the message. Without a valid key every refusal reads alike, on purpose. ## Resources | Resource | Docs word | What it covers | | --- | --- | --- | | organization | Company | Which company the key belongs to. | | workers | Worker | The identities: one Slack app each. Responsibilities and behaviors come back on a single-worker read. | | eworks | A worker's copies | One per client plus your team's. Read-only. | | clients | Client | Create one; bind it to a worker. | | channels | Channel | The workspace's channel directory, and the mappings. | | tasks | Tasks and routines | Hand-offs, scheduled jobs, targets, run history. | | jobs | — | How a provisioning run is going: the other half of every 202. | | memory | Knowledge | Read and write the tiers a copy mounts. | | connections | Connection | Credentials and connected apps, and their placements. | | webhooks | Web | Inbound URLs that start a turn. | | response-policy | Response policy | Mentions only or everything; listen. | | activity | Activity | The append-only audit feed. | | usage | — | Cost, turn outcomes, and a per-day pulse over a window. | | errors | — | The closed set of refusal codes. | > **If you use Python's urllib.** Send a `User-Agent` that does not begin with `Python-urllib`. The hosting platform's bot protection refuses that one string before the request reaches Ergoly, so a good key answers 401. Any other agent string works. --- # Glossary > The docs' word, the API's name, and the internal word, side by side. Ergoly Docs › Technical details. Web: https://www.ergoly.ai/docs/technical/glossary · Index: https://www.ergoly.ai/docs/llms.txt The docs use the words control shows you. The API uses the names its records carry. Engineers at Ergoly use a few more. This is the crosswalk. | Docs | API | Internal | Meaning | | --- | --- | --- | --- | | Company | organization | org | Your agency on Ergoly. Owns everything. | | Worker | Worker | Worker | One Slack app, one name, one job. | | A worker's copy | ework | posting, ework | One running copy of a worker: for one client, or for your team. | | Your team's copy | core ework | core | The copy that serves your internal channels and holds every client's memory. | | A client's copy | client ework | client-bound ework | The copy for one client, holding only that client's memory. | | Client | Client | Client | A customer of yours. | | Channel | channel | channel mapping, room | A Slack channel, mapped to a client or marked internal; also email and the web. | | Event | — | turn trigger, dispatch | Something that happens in a channel and starts work. | | — | — | turn | One message handled by one copy, with one reply. | | — | — | front desk, routing | The fixed rule that sends a message to one copy. | | Knowledge | memory | tiers | Memory and skills, as files in five tiers. | | Company, worker, client knowledge | org, worker, client | tenant tiers | The tiers your company owns. | | Platform knowledge | — | system tier | Ergoly's own tier, read-only, lowest precedence. | | Skill | skill | skill | A directory with a SKILL.md, in a tier. | | Task | task | task | Work with a requester, a holder, and a log. | | Routine | scheduled job | scheduled task, cron | A task whose start repeats. | | Connection | connection | vault connection | A credential or connected app, and its placement. | | Placement | placement | placement, scope | Who may use a connection: company, worker, client, or worker for one client. | | — | — | egress gateway | The proxy that puts a secret into an outbound request by hostname. | | AI Admin | — | AI Admin | Your internal-only worker that sets the company up from Slack. | | Behaviors | behaviors | behaviors | The Avoid, Don't, Prefer, and Use lines a worker follows. | | Responsibilities | responsibilities | responsibilities | What a worker is trained for and accountable for. | | Activity | activity | activity log | The append-only record of every write. | | Artifact | — | artifact | A web page a worker publishes. |