> For the complete documentation index, see [llms.txt](https://ask.birdie.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ask.birdie.ai/integrations-and-data-ingestion/agent-supervisor-mapping.md). # Agent & Supervisor Mapping ### Overview Birdie isolates Agent QA access **per BPO**. Rather than inferring the agent → supervisor → BPO relationship from tickets (which can be incomplete or eventually consistent), Birdie relies on a dedicated **mapping feed** as the source of truth for access control — an authoritative list of, for every agent, who their supervisor is and which BPO they belong to. *** ### Requirements * **Separate feed**: send the mapping in its own directory or dataset, distinct from your ticket ingestion (e.g. use a dedicated `agent_supervisor/` directory). * **Full snapshot**: send one row per active agent, covering the full current roster — not an incremental delta. Each refresh replaces the previous state. * **Matching identifiers**: the identifiers in the mapping must match exactly the ones that appear in your tickets (see the schema below), otherwise the links cannot be made. * **Kept up to date**: the mapping must be refreshed on an ongoing basis so that new hires, role changes, and BPO moves are reflected (see [Keeping the mapping up to date](#keeping-the-mapping-up-to-date)). *** ### Data Schema Each row maps one agent to their supervisor and BPO. All three fields below are required. | Column Name | Type | Required | Description | Example | Impact | | --------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `agent_id` | STRING | Yes | The agent's identifier, as it appears in your tickets (`author_id`) — typically an email, but any identifier that is stable over time works. Must match the ticket value exactly so the agent can be linked to their own data. | `"maria.silva@company.com"` | When the agent logs in they see none of their own tickets — the agent isn't linked to their data, so no per-agent access, Quality Score, or Agent Feedback. | | `supervisor_id` | STRING | Yes | The identifier of the agent's direct supervisor — typically an email. Grants the supervisor access to their team's data and drives supervisor-level QA rollups. | `"joao.souza@company.com"` | Supervisor sees no team data; supervisor-level rollups unavailable. | | `company` | STRING | Yes | A stable identifier for the BPO (outsourcing vendor) the agent works for. Determines which workspace the agent and supervisor are isolated into. Must be **unique and stable per BPO** and match the agent's `agent_company` in your tickets. | `"acme_bpo"` | A wrong or ambiguous value breaks per-BPO isolation — an agent may land in the wrong workspace, or a BPO's data may be split or merged. | *** ### One workspace per BPO The `company` field is what routes an agent and their supervisor into a workspace, so it must identify each BPO **uniquely and consistently over time**: * **One BPO must always be sent as a single, stable value.** If the same BPO arrives under two different values (e.g. `acme_bpo` and `acme_bpo_inc`), each value is treated independently. Unless both values are intentionally mapped to the same workspace, the BPO's data can become fragmented. * **Two different BPOs must never share the same value.** If they do, their data is merged into one workspace and the per-BPO isolation is broken. > **Birdie does not create workspaces from the mapping.** The feed only synchronizes agents and supervisors with workspaces that already exist in Birdie. If a `company` value doesn't match an existing workspace (or one of its aliases), those rows are skipped — no new workspace is created automatically. If your organization has a single BPO (or none), the `company` value can be the same across all agents — everyone shares one workspace. **Internal (in-house) agents in a mixed setup.** If some agents are your own internal team alongside one or more BPOs, those internal agents should also have a stable `company` value. That value may be a default shared by all internal agents or a custom value chosen for your workspace layout, but it should remain unique and consistent like any other `company` value. *** ### Keeping the mapping up to date The mapping reflects a live organization: agents are hired, change roles, and move between BPOs. An out-of-date mapping means people lose access they should have, or keep access they shouldn't. So this is an **ongoing ingestion**, not a one-time load. * **Delivery**: send it through any supported file-based source — Cloud Storage (AWS S3, Azure Blob Storage, Google Cloud Storage) or an sFTP share — following the Data Lake / File-based Ingestion path (see [Birdie's Integration Paths](/integrations-and-data-ingestion/birdies-integration-paths.md)). See [S3 / Azure / GCS](/integrations-and-data-ingestion/how-to-integrate-with/s3-azure-gcs.md) or [sFTP](/integrations-and-data-ingestion/how-to-integrate-with/sftp.md) for setup. * **Cadence**: refresh regularly (a daily full snapshot is recommended) so changes propagate. Each snapshot replaces the previous state. * **Fail-closed**: the mapping defines a user's scope, not whether they can sign in. If an agent or supervisor is missing from the current mapping, they won't receive a default or broad scope. They'll only see data after they appear in the next refresh. *** ### Frequently Asked Questions #### What if an agent isn't in the mapping yet? The mapping defines scope, not authentication. If an agent isn't in the current mapping, they may still be able to sign in, but they'll see no data until they're included in the next refresh. For supervisors, any agents missing from the mapping simply won't be part of their scope. Send the full active roster on every refresh to avoid gaps. #### Can an agent move to another BPO? Yes. Update the agent's `company` **and** `supervisor_id` together in the same snapshot — a move to another BPO means a new supervisor too, so both must change at once. The agent is routed to the new BPO's workspace within 24 hours. #### Do agents and supervisors need to exist as separate rows? No. A supervisor is identified by appearing as the `supervisor_id` of the agents they manage. If a supervisor is also an agent under someone else, they can additionally appear as an `agent_id` in their own row. #### What file format should we use? Any format supported by your chosen file-based source (CSV, Parquet, or JSON). The Birdie team will help you configure the feed during setup. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://ask.birdie.ai/integrations-and-data-ingestion/agent-supervisor-mapping.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.