> For the complete documentation index, see [llms.txt](https://docs.contextual.io/documentation-and-resources/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.contextual.io/documentation-and-resources/components-and-data/agents/agent-details/operations.md). # Operations The Status column normally shows a [Contextual agent lifecycle status](#contextual-agent-lifecycle-statuses). When a lifecycle status is unavailable, it may instead show one of the following fallback values: 1. A [**generic fallback status**](#generic-fallback-statuses), such as **Pending** or **Unknown**, when the platform cannot yet determine a lifecycle status. 2. A [**raw infrastructure reason**](#raw-infrastructure-reasons), such as **PodInitializing** or **OOMKilled**, when the underlying infrastructure provides more specific status information. These sections explain how to interpret each category and what action, if any, to take. In addition, this tab provides the ability to restart all agents, to stop all agents, or to restart individual instances. ## Contextual Agent Lifecycle Statuses These are the defined states the Contextual platform itself assigns to an instance as it is created, run, and torn down. | **Status** | **What it means** | **Ready?** | **When to expect it** | **What to do** | | ------------- | ----------------------------------------------------------------------------------------------------- | ---------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | **Scheduled** | The platform has accepted the request to start this instance. | No | Briefly, when an agent starts or scales up to add an instance. | No action needed, wait for the instance to progress to Starting. | | **Starting** | The instance is starting and is not yet ready to process work. | No | During normal startup, after a deploy, or after a restart. | No action needed. If this stage takes longer than expected, see [PodInitializing](#raw-infrastructure-reasons) for one common cause. | | **Running** | The instance has finished starting and is available to process work. | Yes | The steady state for a healthy instance. | No action needed. | | **Stopping** | The instance is shutting down. Stopping or restarting an instance can interrupt in-flight executions. | No | When an instance is stopped or restarted individually, or as part of Stop All / Restart All. | No action needed, wait for the instance to finish stopping. | | **Completed** | The instance finished its work and exited normally. | No | Briefly, for an instance that has finished running before it is removed from the list. | No action needed. | ### Stopped Instances Are Removed from the List An instance that exits normally may briefly appear with a **Completed** status before it is removed from the Operations tab. After an instance is removed, it no longer appears in the current instance list. For historical details about a stopped or terminated instance—including its stop reason, exit code, restart count, instance name, image version, and start and termination times—open the agent's **Metrics** tab and review **System Metrics**. ## Generic Fallback Statuses These values appear in place of a lifecycle status when the platform cannot yet report one of the statuses above for the instance. | **Status** | **What it means** | **Ready?** | **When to expect it** | **What to do** | | ----------- | ---------------------------------------------------------------------------- | ---------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Pending** | A lifecycle status has not yet been determined or reported for the instance. | No | Briefly, during a state transition. | No action needed if brief. If it persists, treat it the same as a stalled Scheduled/Starting state. | | **Unknown** | The platform could not determine the instance's status. | No | Occasionally, if status reporting is delayed or unavailable. | Refresh the Operations tab. If Unknown persists, check the agent's **Metrics** tab and contact your support representative if the instance appears unresponsive. | ## Raw Infrastructure Reasons When a Contextual lifecycle status is not available, the Status column falls back to display the reason the underlying infrastructure reports for the instance. The set of possible values is open-ended and may include values not documented here. Treat the provided reason as a starting point for investigation rather than a definitive statement of root cause. The same reason string can result from more than one underlying issue. ### Documented Reasons | **Reason** | **What it means** | **Ready?** | **When to expect it** | **What to do** | | ------------------- | -------------------------------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **PodInitializing** | The instance has not finished its startup work. | No | During normal startup. Agents whose flow requires installing non-built-in npm dependencies can spend longer in this state, since dependency installation happens during this phase. | Usually no action needed — wait for startup to finish. If it persists well beyond the agent's normal startup time or recurs repeatedly, review recent flow/package changes, refresh the Operations view, and restart the instance once (avoid repeated restarts — they can reset initialization without fixing the underlying cause). If it remains stuck, contact Contextual Support with: tenant and Agent IDs, the instance name, Agent image version, approximate start time and duration, and whether the issue began after a flow, image, package, or configuration change. | | **OOMKilled** | The instance exceeded the memory available to it and was terminated. | No | When the instance's actual memory use exceeds its configured Instance Compute size — for example under heavy load, with a memory leak, or when processing large payloads. | Open the agent's **Metrics** tab and review memory use in **System Metrics**. Consider increasing the agent's Instance Compute size or reducing per-instance memory use (for example, smaller batches or less parallel work). Contact Contextual Support if OOMKilled recurs after increasing size. | ### This List Is Not Exhaustive PodInitializing and OOMKilled are documented here because they are common and actionable. You may encounter other infrastructure reasons in the Status column that are not covered on this page. --- # 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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.contextual.io/documentation-and-resources/components-and-data/agents/agent-details/operations.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.