Customize components
Change application source when a documented setting is insufficient. Prefer Application settings and Agents & prompts before creating a fork. Use Run locally to prepare a development environment.
Choose the owner
| Change | Repository and starting point |
|---|---|
| Agent definitions, workflow graphs, prompts and registered tools | Orchestrator, application definitions and tool/connector owners under src/ |
| MCP transport, authentication and explicit toolset registration; NL2SQL generation, validation, execution and catalog import | Agent App MCP Server, separate from orchestrator definitions |
| File parsing, chunking, source jobs, indexing | Ingestion, chunking/, jobs/, and tools/ |
| Chat presentation, identity/session handling, backend client | UI, src/gpt_rag_ui/, public/, and .chainlit/ |
| Ingestion operator dashboard | Ingestion frontend/, not the chat UI or native runtime |
| Platform resources, component selection, immutable source pins | Agent Landing Zone, not component infra/ placeholders |
Make the smallest change in its owning repository. Keep executable examples, sample documents, schemas, and regression tests with the code. User, operator, and developer guides belong on this central site. Local engineering contracts, ADRs, policies, and changelogs retain their own repository purpose.
How to make and adopt a source change
- Before editing, record the platform manifest and the owning component's compatible revision. Obtain a component checkout only for source development, then follow Run locally; cloning is not the normal application deployment procedure.
- Add a focused behavioral test in that repository, then change its canonical owner below. Keep denied-user behavior, wire schemas and deployment inputs unchanged unless the change explicitly requires a coordinated contract update.
- Run the component checks, using its protected target base. For a setting-only change, use the canonical settings procedure instead of modifying source.
- Before deployment, pin the tested source in the manifest and application definition together using component adoption. Source edits and local reloads do not update a running Azure application.
- Deploy through the platform lifecycle, then verify the exact changed behavior and a denied case. Keep the prior tested pins for rollback; changing parser code does not rebuild existing indexes or reverse data mutations.
Agents, workflows and prompts
A MAF Agent handles conversation; a MAF Workflow defines a published process. Hosting and tools are separate choices. To extend the application:
- Extend the owning agent definition or workflow graph. Use the official MAF
execution and human-input APIs, not a second execution loop, polling queue
or application-owned checkpoint engine.
Start with
src/native/agent.py,src/native/workflow.pyand theirsrc/native/contracts.pymodels.src/native/hosted.pyandsrc/native/durable.pycompose the selected host. - Register the intended capabilities explicitly. Foundry IQ, Search, MCP and optional MCP NL2SQL are tools/capabilities, not a mixed strategy registry or a user-facing host picker.
- Keep packaged instructions and typed tool inputs with the reviewed source. Test missing/invalid configuration and prompts. Functional App Configuration values refresh through the supported provider; an existing workflow retains its run snapshot without freezing authorization.
- Use the explicit host integration: request-aware Hosted agent/workflow factories and native Responses persistence, or the official Durable Extension worker/client with DTS. Do not build a universal protocol or state SDK to hide these differences.
- Keep workflow/executor and native registration names aligned between the published worker and client. Test reconnect, rejection, stale/duplicate human replies, ownership denial and required-tool failure on each supported host.
Prompt variants and settings do not grant source permissions. Preserve denied retrieval as an error where strict authorization requires it. See Workflows & human input for state and recovery, and the API reference for host-specific client boundaries.
Tools and retrieval
A tool is an operation the agent can call. Model Context Protocol, or MCP, is a protocol for exposing tools. A registered MCP operation is distinct from an MCP knowledge source consulted by Foundry IQ.
- Extend the existing tool/connector used by the application. Keep argument validation, timeout, cancellation, and result shaping at that boundary.
- Follow Tools & MCP for supported integrations rather than embedding endpoint URLs or credentials in a prompt.
- To extend the supplied subset with another Foundry tool, follow How to add another Foundry tool for compatibility, registration, permissions and deployment.
- Preserve the separation between workload authentication and delegated user authorization. Hosted Toolbox calls need validated platform call context. Native retrieval and protected downloads require their own user tokens.
- Do not accept client-supplied groups, user IDs, indexes, or document URLs as proof of access. Add negative tests for cross-user and source-denied requests.
-
For SQL, keep a read-only database principal as the primary security boundary. Generated-SQL validation is not a substitute for database permissions. SQL generation, catalog retrieval and execution belong in Agent App MCP Server.
Keep its reviewed modules, typed schemas, scoped permissions, dependencies and tests aligned with explicit module registration.
MCP_TOOLSETS=[]registers zero tools and initializes no NL2SQL dependencies.["nl2sql"]selects the two supplied SQL tools at startup. Unknown/duplicate/invalid selections fail closed. Changes require restart/redeployment.
Retrieval backend selection does not switch every datasource or tool. Use Foundry IQ and the relevant source guide for source registration. Source configuration and consent remain operator tasks.
Chunkers and ingestion jobs
A chunker splits a document into the records used for retrieval. In the ingestion repository:
- Implement or extend a class under
chunking/chunkers/usingbase_chunker.pyand a nearby parser as the contract. - Register format selection in
chunking/chunker_factory.py. Preserve the distinction between text fallback, transcripts, spreadsheets, JSON, document analysis, and multimodal processing. Office support depends on the selected analysis service and version. - Exercise the parser through
DocumentChunkerinchunking/document_chunking.py. It returns chunks, record errors, and warnings. Keep expected index field names, embedding dimensions, and document/conversation authorization metadata. - Test empty, malformed, oversized, unsupported, and partially failed input. Mock analysis, embedding, Blob, and Search clients. A successful HTTP envelope is not proof every chunk was indexed.
- For source jobs, extend the existing job owner.
main.pycomposes startup and shutdown.jobs/runtime.pyowns scheduler state, the registry, lock, running-job tracking, and cron map. Admin routes use that interface, not mutable state imported frommain.
Do not test a parser by starting the service against production storage.
Startup and cron can index or purge data even without an explicit HTTP request.
Use Jobs & schedules for execution and recovery.
Keep source samples under the repository's samples/ rather than adding
document bodies to a guide or a telemetry fixture.
Chat UI ownership and imports
The distribution installs the gpt_rag_ui package from src/gpt_rag_ui/.
Import the installed package rather than using filesystem-path manipulation.
| Canonical area | Owns |
|---|---|
bootstrap.py |
ASGI composition and auth-before-Chainlit mount order |
api/ |
Authenticated /api/native routes, callbacks and session bridge |
services/ |
Native application operations, owner metadata, feedback, citations and download policy |
auth/ |
Identity, OAuth, session, and transport security |
clients/ |
Explicit Hosted and DTS clients, plus separately required ingestion, Blob and Cosmos transports |
config/ |
Provider/cache, typed settings, and staged asset-root resolution |
telemetry/ and util/ |
Instrumentation and pure constants |
Root main.py, app.py, datalayer.py, and connectors/ are supported
compatibility adapters, not implementation owners. Patch canonical owners in
tests, not private adapter globals. .quality/migration.json freezes the
compatibility export inventory and .quality/policy.json tracks the current scope.
Do not add sys.path or sys.modules workarounds.
Keep native session selection and consume-once request metadata at the authenticated API boundary. The native application service owns UI UUID mapping and product metadata; explicit host clients own execution calls. Do not route native operations through an unrelated data-layer adapter.
Callback, history, and OAuth registration must remain idempotent. Native history uses the selected host client plus UI-owned metadata. Keep session/run owner checks explicit before native reads, continuation and pending human replies.
For presentation, start with public/theme.json, public/custom.css, and
.chainlit/config.toml. Preserve light/dark themes, keyboard focus, readable
contrast, responsive layout, and reduced-motion behavior.
Keep the staged assets with the installed code.
For embedding, use the existing portal contract, not new
browser-stored credentials or weakened origin checks.
Operator dashboard changes
Edit React/TypeScript under ingestion's frontend/.
Use its local proxy and Node setup,
start the backend separately, and keep typed frontend payloads aligned with
the API reference. Native orchestrator entrypoints do
not mount ingestion dashboard/admin APIs.
Test read-only, administrator, unauthenticated, denied, empty, loading, and failure states. A local development admin bypass is not production authorization. Configuration writes, unblocking files, manual jobs, and curation decisions mutate data.
Validate and adopt the change
Run the owning repository's behavioral and quality checks. Record which protocols and negative-access cases were tested and which live checks remain unperformed. Follow its local engineering and contribution rules.
When a customized component is ready for separately authorized deployment, use Bring your own app. That guide owns source pinning, application definitions, deployment, and rollback. Changing a Git remote or pushing a component branch does not update the platform's validated combination.