Fabric Operations Agent CI/CD and REST API

Microsoft exposes an Operations Agent public definition and item-specific REST APIs that support CI/CD scenarios. A definition can carry the goals, instructions, data sources, actions, recipient, playbook placeholder, and `shouldRun` state that determine what the control loop monitors, who it contacts, what it can invoke, and whether it is active.

That makes deployment correctness a production safety issue. A technically successful update can still point at a development KQL database, retain a test recipient, bind a production action to the wrong flow, overwrite a reviewed instruction, or set the agent running before the new playbook and permissions are validated.

Can the release prove the exact definition, source IDs, action IDs, recipient, identity, playbook evidence, and run state that reached production? If not, the automation is moving risk faster rather than controlling it.

Send the definition and pipeline Review the agent pilot

Define the supported automation and identity boundary

Inventory the current Fabric API operations used to create, get, list, update, retrieve definitions, update definitions, and delete Operations Agent items. Record delegated scope, workspace and item role, supported identity, request and correlation IDs, long-running-operation behavior, retry policy, rate limit, preview status, and rollback method for each call.

Microsoft currently documents `Item.ReadWrite.All` and a delegated user identity for create and update-definition operations, while service principals and managed identities are listed as unsupported. A generic Fabric service principal used elsewhere in the pipeline does not make these Operations Agent calls supported. Use an approved user-bound release mechanism or keep the step manual until the required workload identity is documented and tested.

Control every deployable and environment-specific field

Artifact	Release evidence	Promotion risk	Required control
Goals and instructions	Reviewed text, owner, version, diff, test mapping, and approved environment substitutions.	A broad or stale instruction changes generated monitoring behavior.	Source control, peer review, policy checks, regression suite, and immutable release hash.
Data sources	Alias, source ID, workspace ID, type, environment, schema, access, and current watermark.	Production agent reads test data, the wrong workspace, or an incompatible schema.	Typed environment manifest, allowlisted IDs, existence and permission preflight, and no free-form replacement.
Actions	Alias, action ID, kind, display name, description, parameter metadata, authority, and environment.	A recommendation invokes the wrong flow or uses unvalidated production parameters.	Action allowlist, contract tests, least privilege, approval owner, idempotency, and postcondition checks.
Recipient	Approved user or channel, item write permission, environment, escalation, and offboarding owner.	Test messages reach production users or approvals go to an unauthorized recipient.	Environment mapping, membership and permission validation, canary message, and review.
Playbook	Generation status, summary, glossary, rules, queries, bindings, evaluation result, and approval.	A deployment assumes the prior generated playbook remains valid after configuration changes.	Regenerate when required, inspect diff, replay ground truth, and block activation until approved.
`shouldRun`	Expected inactive or active state, activation approver, window, health checks, and stop owner.	Promotion immediately activates unverified rules and actions or disables a required control.	Inactive-first default, explicit post-deploy activation, state reconciliation, alerting, and emergency stop.
Item metadata	Display name, description, folder, sensitivity label, `.platform` behavior, tags, and ownership.	Metadata or label differs from approved governance expectations.	Separate metadata policy, understand `updateMetadata`, and verify resulting item properties.
API response	Status, `Location`, `x-ms-operation-id`, `Retry-After`, request ID, final state, and retrieved definition.	A 202 response is treated as success before the long-running operation completes.	Bounded polling, retry-after compliance, terminal-state handling, and post-deploy readback.

Keep one normalized source definition and explicit environment manifests for workspace, source, action, recipient, and state. Validate the current Operations Agent definition specification before release. Microsoft documents evolving preview schemas and rejects unknown data-source types or action kinds; do not silently drop fields to make a payload pass.

Test identity, payload, failure, state, and behavior

Test	Method	Pass condition	Failure response
Identity and authorization	Run with approved user, expired and revoked token, wrong tenant, Reader, Contributor, Admin, service principal, and managed identity.	Only currently supported and authorized identities perform each operation; denials are visible.	Correct release identity and role, revoke access, or keep deployment manual.
Schema validation	Test missing parts, invalid Base64, malformed JSON, unknown type or kind, duplicate alias, invalid UUID, and unexpected fields.	Invalid definitions fail before production and no partial configuration is accepted.	Local schema gate, payload repair, contract update, or release block.
Environment rebinding	Promote to test and production using intentionally similar IDs, missing dependencies, wrong workspaces, and changed schemas.	Only allowlisted target resources are selected and every dependency passes preflight.	Manifest correction, dependency deployment, source or action rollback, and incident review.
Long-running operation	Exercise 200, 202, delayed completion, 429, retry-after, timeout, terminal failure, network interruption, and duplicate submission.	The pipeline waits for terminal state, retries safely, and never reports an ambiguous release as successful.	Reconcile operation and item state, bounded retry, idempotent orchestration, or manual recovery.
Definition readback	Retrieve the public definition after create or update and compare normalized content with the approved release artifact.	Goals, instructions, references, recipient, metadata behavior, and `shouldRun` match exactly.	Stop agent, reject release, restore prior definition, and investigate transformation.
Playbook regression	Generate and inspect rules, then replay positive, negative, boundary, transition, stale, permission, and action cases.	Behavior meets the same or approved improved quality and safety gates as the prior version.	Keep inactive, fix definition or source, regenerate, and rerun evaluation.
Activation gate	Deploy inactive, run canary checks, request approval, start, observe initial cycles, and exercise emergency stop.	No production monitoring starts before explicit approval and verified dependencies.	Stop agent, revoke write path, restore prior version, and notify owner.
Rollback	Restore prior definition, environment references, recipient, playbook, state, and action contract after a simulated bad release.	Known-good monitoring resumes within the recovery objective with complete evidence.	Manual containment, downstream action reconciliation, and pipeline redesign.
Audit and separation	Trace commit, reviewer, release identity, approver, API calls, operation IDs, definition hash, tests, activation, and outcome.	No single actor can author, approve, deploy, and activate a material production change without detection.	Branch protection, environment approval, role separation, logging, or production hold.

Run behavioral tests after deployment, not only JSON validation. The agent is an LLM-assisted control loop; the same syntactically valid configuration can generate different or unsafe operational behavior when sources, schema, instructions, runtime, or actions change.

Promote inactive, reconcile state, and retain recovery evidence

Use a release sequence of validate, authenticate, preflight dependencies, create or update inactive, poll the long-running operation, retrieve and compare the definition, generate and inspect the playbook, run regression and permission tests, obtain approval, activate, observe a canary window, and record evidence. Never set `shouldRun` from a developer branch or unreviewed environment default.

Store the last known-good definition, environment manifest, generated-rule evidence, evaluation result, item and operation IDs, owner, and stop procedure. Alert on definition drift, direct UI or MCP changes outside the pipeline, unsupported identity use, failed long-running operations, unexpected active state, source or action changes, missing approvals, and regression deterioration.

Preview API and schema behavior can change. Pin the tested contract, monitor official documentation, validate unknown fields and new enum values deliberately, and rerun API plus behavioral tests after Fabric releases. Separate item creation, definition update, metadata update, playbook generation, and activation so each step has a clear failure and rollback boundary.

Run a two-to-four-week CI/CD assessment

Select one Operations Agent, dev/test/prod workspaces, source and action dependencies, DevOps platform, release owners, and existing manual baseline.
Inventory definitions, schema version, item APIs, supported identities, delegated scopes, roles, source and action IDs, recipients, playbook process, state, logs, and rollback.
Create the normalized source definition, environment manifests, schema and policy checks, identity model, API orchestration, approval matrix, and release evidence format.
Implement create or update inactive, long-running-operation polling, retry-after handling, readback comparison, dependency preflight, and failure reconciliation in nonproduction.
Generate and inspect the playbook, run the rule and action evaluation suite, test permissions, and block activation when any quality or safety gate fails.
Exercise wrong-environment, malformed payload, unsupported identity, 429, timeout, duplicate call, partial failure, direct drift, activation, emergency stop, and rollback scenarios.
Run a controlled production canary with human approval, inactive-first promotion, post-deploy readback, behavioral tests, monitored activation, and complete audit evidence.
Deliver the architecture, source definition, manifests, pipeline, tests, runbook, identity constraints, scorecard, recovery evidence, and automate, limited automation, manual gate, or stop recommendation.

Frequently asked questions

Can Microsoft Fabric Operations Agent be deployed through a REST API?

Yes. Microsoft documents Operations Agent REST APIs to create items, retrieve public definitions, and update definitions. The OperationsAgentV1 public-definition format is specifically described as supporting CI/CD scenarios. Create and updateDefinition can complete immediately or as long-running operations.

What is included in an Operations Agent public definition?

The current definition specification includes user-authored goals, instructions, data-source references, action references and parameters, an optional recipient, a playbook object, and the shouldRun state. Environment-specific workspace, source, action, recipient, and execution values must be controlled during promotion.

Does the Operations Agent REST API support service principals?

Not for the current create and update-definition operations documented by Microsoft. Those references list delegated user identity as supported and service principals and managed identities as unsupported. Do not assume generic Fabric API identity support applies to an Operations Agent endpoint; verify each operation's current identity table.

Can an Operations Agent deployment start monitoring automatically?

The public definition includes a shouldRun boolean that represents whether the agent should run or remain stopped. A release process should keep nonproduction and newly promoted production agents inactive until source, action, playbook, permission, and regression checks pass and an accountable owner approves activation.

How long does an Operations Agent CI/CD assessment take?

A focused assessment commonly takes two to four weeks for one agent, three environments, a representative source, bounded action set, and an existing DevOps platform. It covers definition baselining, identity, environment rebinding, API orchestration, validation, release gates, audit, and rollback.

Official implementation references

Start with one agent and make inactive-first promotion non-negotiable. Datrick can baseline the definition, implement the API release path, test identity and environment failures, add behavioral gates, and prove recovery.

Scope the CI/CD assessment

Deployment automation should not silently start a new control loop.