Title: app | deepagents_code | LangChain Reference
Open Graph Title: app | deepagents_code
X Title: app | deepagents_code
Description: Python API reference for app in deepagents_code. Part of the LangChain ecosystem.
Open Graph Description: Python API reference for app in deepagents_code. Part of the LangChain ecosystem.
X Description: Python API reference for app in deepagents_code. Part of the LangChain ecosystem.
Opengraph URL: https://reference.langchain.com/python/deepagents-code/app
Domain: reference.langchain.com
| og:image | https://reference.langchain.com/og/python/deepagents-code/app |
| og:image:width | 1200 |
| og:image:height | 630 |
| og:image:alt | app | deepagents_code |
| og:type | article |
| twitter:card | summary_large_image |
| twitter:image | https://reference.langchain.com/og/python/deepagents-code/app |
Links:
| LangChain Reference home page | https://reference.langchain.com/ |
| GitHub | https://github.com/langchain-ai |
| Main Docs | https://docs.langchain.com/oss/python/deepagents |
| Deep Agents | https://reference.langchain.com/python/deepagents |
| LangChain | https://reference.langchain.com/python/langchain/overview |
| LangGraph | https://reference.langchain.com/python/langgraph/overview |
| Integrations | https://reference.langchain.com/python/integrations/overview |
| LangSmith | https://reference.langchain.com/python/langsmith |
| Deep Agents Code | https://reference.langchain.com/python/deepagents-code |
| Deep Agents Code | https://reference.langchain.com/python/deepagents-code |
| deepagents-code | https://reference.langchain.com/python/deepagents-code |
| attributeDEFAULT_ASSISTANT_ID: Final[str]Default agent / assistant identifier when no -a flag is given. | https://reference.langchain.com/python/deepagents-code/_constants/DEFAULT_AGENT_NAME |
| attributeSYSTEM_MESSAGE_PREFIX: Final[str]Prefix for synthetic human messages (e.g. interrupt cancellation notices). Such messages are written to the messages channel for the agent's benefit on resume but are not user-authored, so they are filtered out of both the rendered transcript and a thread's initial prompt. Shared here so the single producer (textual_adapter) and its consumers (app, sessions) agree on one literal. | https://reference.langchain.com/python/deepagents-code/_constants/SYSTEM_MESSAGE_PREFIX |
| attributeCHANGELOG_URL: strURL for the full changelog. | https://reference.langchain.com/python/deepagents-code/_version/CHANGELOG_URL |
| attributeDOCS_URL: strURL for deepagents-code documentation. | https://reference.langchain.com/python/deepagents-code/_version/DOCS_URL |
| attributelogger | https://reference.langchain.com/python/deepagents-code/app/logger |
| attributeScreenResultT | https://reference.langchain.com/python/deepagents-code/app/ScreenResultT |
| attributeGoalStatus: Literal['active', 'blocked', 'complete']Lifecycle status of a TUI-owned goal. active and blocked are unfinished states; complete is terminal. A blocked goal is still considered active (unfinished) by get_goal. | https://reference.langchain.com/python/deepagents-code/resume_state/GoalStatus |
| attributeRestartChoice: Literal['restart', 'later']Outcome of the prompt: restart the server now or defer. | https://reference.langchain.com/python/deepagents-code/tui/widgets/restart_prompt/RestartChoice |
| attributeInputMode: Literal['normal', 'shell', 'shell_incognito', 'command'] | https://reference.langchain.com/python/deepagents-code/app/InputMode |
| attributeDeferredActionKind: Literal['model_switch', 'thread_switch', 'chat_output', 'agent_switch', 'mcp_login', 'rubric_model_switch', 'rubric_max_iterations_switch']Valid DeferredAction.kind values for type-checked deduplication. | https://reference.langchain.com/python/deepagents-code/app/DeferredActionKind |
| functionread_git_branch_from_filesystemRead the current git branch from repository metadata. | https://reference.langchain.com/python/deepagents-code/_git/read_git_branch_from_filesystem |
| functionread_git_branch_via_subprocessFall back to git rev-parse for unusual repository layouts. | https://reference.langchain.com/python/deepagents-code/_git/read_git_branch_via_subprocess |
| functionformat_token_countFormat a token count into a human-readable short string. | https://reference.langchain.com/python/deepagents-code/_session_stats/format_token_count |
| functionformat_message_timestampFormat a message timestamp for display. Shows only the time of day for messages from the current local date and prefixes the date otherwise. The 12- versus 24-hour clock follows the system configuration (see uses_24_hour_clock). | https://reference.langchain.com/python/deepagents-code/formatting/format_message_timestamp |
| functionrestore_iterm_cursor_guideRestore iTerm2 cursor guide when launch-time profile state required it. | https://reference.langchain.com/python/deepagents-code/iterm_cursor_guide/restore_iterm_cursor_guide |
| functionopen_url_asyncOpen url in a browser and toast on failure. Runs webbrowser.open in a thread, catches the platform errors that can arise when no browser backend is available, and posts a warning toast containing the URL so the user can copy it manually instead of the failure vanishing into a background worker log. | https://reference.langchain.com/python/deepagents-code/tui/widgets/_links/open_url_async |
| functionsave_theme_preferencePersist theme preference to ~/.deepagents/config.toml. | https://reference.langchain.com/python/deepagents-code/app/save_theme_preference |
| functionsave_terminal_theme_mappingPersist a [ui.terminal_themes][term_program] = name entry. The write is atomic (temp file + Path.replace) to avoid corrupting config.toml on crash or SIGINT. Mirrors save_theme_preference. | https://reference.langchain.com/python/deepagents-code/app/save_terminal_theme_mapping |
| functionrun_textual_appRun the Textual application. When server_kwargs is provided (and agent is None), the app starts immediately with a status-bar connection state and launches the server in the background. Server cleanup is handled automatically after the app exits. | https://reference.langchain.com/python/deepagents-code/app/run_textual_app |
| classCLIContextClient-facing builder for the per-run graph context payload. Callers populate this and pass it via context= to astream/ainvoke. ConfigurableModelMiddleware and the interrupt_on when predicate read it from request.runtime.context. In-process LangGraph coerces it into CLIContextSchema (the registered context_schema); over the API it stays a plain dict — which is why consumers handle both shapes. | https://reference.langchain.com/python/deepagents-code/_cli_context/CLIContext |
| classSessionStatsStats accumulated over a single agent turn (or full session). | https://reference.langchain.com/python/deepagents-code/_session_stats/SessionStats |
| classActionIdStable identifiers for notification actions dispatched by the app. | https://reference.langchain.com/python/deepagents-code/notifications/ActionId |
| classMissingDepPayloadTyped payload for a missing-dependency notification. | https://reference.langchain.com/python/deepagents-code/notifications/MissingDepPayload |
| classNotificationActionOne button/action row in the notification modal. | https://reference.langchain.com/python/deepagents-code/notifications/NotificationAction |
| classNotificationRegistryIn-memory store of pending notifications. Instance-scoped (one per app) so test apps don't pollute each other. Owns the bidirectional key-to-toast-identity binding so callers cannot accidentally desynchronize the click-routing indices. | https://reference.langchain.com/python/deepagents-code/notifications/NotificationRegistry |
| classPendingNotificationA single notice waiting for user action. Immutable value object: the registry owns the key-to-toast-identity binding (see NotificationRegistry) so external callers cannot corrupt click-routing indices by mutating notifications after construction. | https://reference.langchain.com/python/deepagents-code/notifications/PendingNotification |
| classUpdateAvailablePayloadTyped payload for an update-available notification. | https://reference.langchain.com/python/deepagents-code/notifications/UpdateAvailablePayload |
| classChatInputChat input widget with prompt, multi-line text, autocomplete, and history. Features: Multi-line input with TextArea Enter to submit, modifier key for newlines (see config.newline_shortcut) Up/Down arrows for command history at input boundaries (start/end of text) Autocomplete for @ (files) and / (commands) | https://reference.langchain.com/python/deepagents-code/tui/widgets/chat_input/ChatInput |
| classLoadingWidgetAnimated loading indicator with status text and elapsed time. Displays: Thinking... (3s, esc to interrupt) | https://reference.langchain.com/python/deepagents-code/tui/widgets/loading/LoadingWidget |
| classMessageDataIn-memory message data for virtualization. This dataclass holds all information needed to recreate a message widget. It is designed to be lightweight so that thousands of messages can be stored without meaningful memory overhead. | https://reference.langchain.com/python/deepagents-code/tui/widgets/message_store/MessageData |
| classMessageStoreManages message data and widget window for virtualization. This class stores all messages as data and manages a sliding window of widgets that are actually mounted in the DOM. | https://reference.langchain.com/python/deepagents-code/tui/widgets/message_store/MessageStore |
| classMessageTypeTypes of messages in the chat. | https://reference.langchain.com/python/deepagents-code/tui/widgets/message_store/MessageType |
| classToolStatusStatus of a tool call. | https://reference.langchain.com/python/deepagents-code/tui/widgets/message_store/ToolStatus |
| classAppMessageWidget displaying an app message. | https://reference.langchain.com/python/deepagents-code/tui/widgets/messages/AppMessage |
| classAssistantMessageWidget displaying an assistant message with markdown support. Uses MarkdownStream for smoother streaming instead of re-rendering the full content on each update. Once a stream finishes, the message is re-rendered from the complete source via Markdown.update() to work around Textualize/textual#6518: MarkdownFence._update_from_block refreshes the visible Label but leaves _highlighted_code pinned to the first chunk, so any later recompose (click, focus change, theme update) re-yields the stale value and wrapped fenced-code bodies vanish. A full re-parse rebuilds every fence with correct internal state. Streamed tokens are coalesced in _pending_append and flushed to the MarkdownStream on a throttled timer (_STREAM_FLUSH_INTERVAL). Writing every token immediately forced a markdown re-parse per chunk on the UI event loop, which starved keyboard input while the model streamed. Batching the writes keeps the event loop free so typing stays responsive. | https://reference.langchain.com/python/deepagents-code/tui/widgets/messages/AssistantMessage |
| classDiffMessageWidget displaying a diff with syntax highlighting. | https://reference.langchain.com/python/deepagents-code/tui/widgets/messages/DiffMessage |
| classErrorMessageWidget displaying an error message. | https://reference.langchain.com/python/deepagents-code/tui/widgets/messages/ErrorMessage |
| classQueuedUserMessageWidget displaying a queued (pending) user message in grey. This is an ephemeral widget that gets removed when the message is dequeued. | https://reference.langchain.com/python/deepagents-code/tui/widgets/messages/QueuedUserMessage |
| classSkillMessageWidget displaying a skill invocation with collapsible body. Shows skill name, source badge, description, and user args as a compact header. The full SKILL.md body (frontmatter stripped) is hidden behind a preview/expand toggle (click or Ctrl+O). The expanded view renders markdown via Rich's Markdown inside a single Static widget. Visibility is driven by a CSS class (-expanded) toggled via a Textual reactive var. Click handlers are scoped to the header and hint widgets (_SkillToggle) so clicks on the rendered markdown body do not trigger expansion toggles (preserving text selection, for instance). | https://reference.langchain.com/python/deepagents-code/tui/widgets/messages/SkillMessage |
| classToolCallMessageWidget displaying a tool call with collapsible output. Tool outputs are shown as a 3-line preview by default. Press Ctrl+O to expand/collapse the full output. Shows an animated "Running..." indicator while the tool is executing. | https://reference.langchain.com/python/deepagents-code/tui/widgets/messages/ToolCallMessage |
| classToolGroupSummaryCollapsed one-line stand-in for an assistant step's tool calls. Tools are hidden from the moment they start; this single line shows live progress ("Running 1 shell command…") and flips to the past tense ("Ran 1 shell command") once every tool finishes. Clicking the line or pressing Ctrl+O expands the underlying tool rows (and their diffs). Two modes: live (streaming): created empty, members added via add_member as they mount, a spinner timer animates the line and re-renders present/past tense, and failed tools are ejected back into view so errors stay visible. finalized (live=False, used for hydration/resume): a fixed set of completed tools rendered straight to the past tense with no timer. Purely presentational — never tracked by the message store; it is re-derived from the mounted tool widgets on each stream boundary and on hydration. | https://reference.langchain.com/python/deepagents-code/tui/widgets/messages/ToolGroupSummary |
| classUserMessageWidget displaying a user message. | https://reference.langchain.com/python/deepagents-code/tui/widgets/messages/UserMessage |
| classStatusBarStatus bar showing mode, auto-approve, cwd, git branch, tokens, and model. | https://reference.langchain.com/python/deepagents-code/tui/widgets/status/StatusBar |
| classSubagentPanelDocked two-pane panel visualizing js_eval subagent fan-out by phase. Hidden until the first spawn event. Phases (one per js_eval) list on the left and the selected phase's subagents render as a scrollable table on the right. Focus the panel and use up/down to revisit finished phases. Expands while any phase runs, collapses to the header when the turn goes idle, and re-expands when a new phase starts. | https://reference.langchain.com/python/deepagents-code/tui/widgets/subagent_panel/SubagentPanel |
| classWelcomeBannerCompact welcome banner shown at startup. Renders a bordered box with the product title and version, followed by rows that appear only when their data (and any env gate) is present. In render order: the active model (SPLASH_SHOW_MODEL, opt-in), working directory (SPLASH_SHOW_CWD, opt-in), LangSmith tracing project and its replica (each clickable once its URL resolves), thread ID (debug mode only), and the MCP tool count. MCP server warnings and the editable-install path follow. | https://reference.langchain.com/python/deepagents-code/tui/widgets/welcome/WelcomeBanner |
| classQuestionA question to ask the user. | https://reference.langchain.com/python/deepagents-code/_ask_user_types/Question |
| classServerProcessManages a langgraph dev server subprocess. Focuses on subprocess lifecycle (start, stop, restart) and health checking. Env-var management for restarts (e.g. configuration changes requiring a full restart) is handled by _scoped_env_overrides, keeping this class focused on process management. | https://reference.langchain.com/python/deepagents-code/client/launch/server/ServerProcess |
| classRemoteAgentClient that talks to a LangGraph server over HTTP+SSE. Wraps langgraph.pregel.remote.RemoteGraph which handles SSE parsing, stream-mode negotiation (messages-tuple), namespace extraction, and interrupt detection. This class adds streamed message-object conversion for the Textual adapter and thread-ID normalization. State snapshots are returned as provided by the server. | https://reference.langchain.com/python/deepagents-code/client/remote_client/RemoteAgent |
| classModelResultResult of creating a chat model, bundling the model with its metadata. This separates model creation from settings mutation so callers can decide when to commit the metadata to global settings. | https://reference.langchain.com/python/deepagents-code/config/ModelResult |
| classEventSourceSource of external events for the Textual app. Implementations must be safe to stop() even when start() failed partway through; the app always invokes stop() from a finally block. | https://reference.langchain.com/python/deepagents-code/event_bus/EventSource |
| classExternalEventA transport-independent event delivered from outside the TUI. | https://reference.langchain.com/python/deepagents-code/event_bus/ExternalEvent |
| classMCPServerInfoMetadata for a configured MCP server and its tools. | https://reference.langchain.com/python/deepagents-code/mcp_tools/MCPServerInfo |
| classMissingProviderPackageErrorRaised when a provider is selected but its LangChain package is not installed. Subclasses ModelConfigError so existing except ModelConfigError blocks keep working. Carries the provider name and the package to install so callers can render targeted recovery hints (e.g., suggest /install fireworks or the /model slash command) without string-matching on the formatted exception message. | https://reference.langchain.com/python/deepagents-code/model_config/MissingProviderPackageError |
| classExtendedSkillMetadataExtended skill metadata for CLI display, adds source tracking. | https://reference.langchain.com/python/deepagents-code/skills/load/ExtendedSkillMetadata |
| classTextualUIAdapterAdapter for rendering agent output to Textual widgets. This adapter provides an abstraction layer between the agent execution and the Textual UI, allowing streaming output to be rendered as widgets. | https://reference.langchain.com/python/deepagents-code/tui/textual_adapter/TextualUIAdapter |
| classApprovalMenuApproval menu using standard Textual patterns. Key design decisions (following mistral-vibe reference): Container base class with compose() BINDINGS for key handling (not on_key) can_focus_children = False to prevent focus theft Simple Static widgets for options Standard message posting Tool-specific widgets via renderer pattern | https://reference.langchain.com/python/deepagents-code/tui/widgets/approval/ApprovalMenu |
| classAskUserMenuInteractive widget for asking the user questions. Supports text input and multiple choice questions. Multiple choice questions always include an "Other" option for free-form input. | https://reference.langchain.com/python/deepagents-code/tui/widgets/ask_user/AskUserMenu |
| classGoalReviewMenuInline review widget for generated goal acceptance criteria. | https://reference.langchain.com/python/deepagents-code/tui/widgets/goal_review/GoalReviewMenu |
| classModelSelectorScreenFull-screen modal for model selection. Displays available models grouped by provider with keyboard navigation and search filtering. Current model is highlighted. Returns (model_spec, provider) tuple on selection, or None on cancel. | https://reference.langchain.com/python/deepagents-code/tui/widgets/model_selector/ModelSelectorScreen |
| classNotificationSuppressRequestedPosted when the user picks SUPPRESS from a notification's detail modal. The center does not dismiss on SUPPRESS because the remaining notifications should still be reachable in place. The app handles this message by running the suppress dispatch and calling NotificationCenterScreen.reload with the refreshed registry snapshot. | https://reference.langchain.com/python/deepagents-code/tui/widgets/notification_center/NotificationSuppressRequested |
| classUpdateProgressScreenModal that shows self-update progress and a bounded log tail. | https://reference.langchain.com/python/deepagents-code/tui/widgets/update_progress/UpdateProgressScreen |
| classQueuedMessageRepresents a queued user message awaiting processing. | https://reference.langchain.com/python/deepagents-code/app/QueuedMessage |
| classExternalInputTextual message carrying an external prompt or command. | https://reference.langchain.com/python/deepagents-code/app/ExternalInput |
| classDeferredActionAn action deferred until the current busy state resolves. | https://reference.langchain.com/python/deepagents-code/app/DeferredAction |
| classTextualSessionStateSession state for the Textual app. | https://reference.langchain.com/python/deepagents-code/app/TextualSessionState |
| classDeepAgentsAppMain Textual application for deepagents-code. | https://reference.langchain.com/python/deepagents-code/app/DeepAgentsApp |
| classAppResultResult from running the Textual application. | https://reference.langchain.com/python/deepagents-code/app/AppResult |
| typeAliasSpinnerStatus: Literal['Thinking', 'Offloading', 'Loading thread', 'Drafting acceptance criteria'] | NoneValid spinner display states, or None to hide. | https://reference.langchain.com/python/deepagents-code/_session_stats/SpinnerStatus |
| typeAliasAskUserWidgetResultDiscriminated union for the ask_user widget Future result. | https://reference.langchain.com/python/deepagents-code/_ask_user_types/AskUserWidgetResult |
| typeAliasGoalReviewResult | https://reference.langchain.com/python/deepagents-code/tui/widgets/goal_review/GoalReviewResult |
| modulethemeLangChain brand colors and semantic constants for the app.
Single source of truth for color values used in Python code (Rich markup,
Content.styled, Content.from_markup). CSS-side styling should reference
Textual CSS variables: built-in variables
($primary, $background, $text-muted, $error-muted, etc.) are set via
register_theme() in DeepAgentsApp.__init__, while the few app-specific
variables ($mode-bash, $mode-command, $mode-incognito, $skill,
$skill-hover, $tool, $tool-hover) are backed by these constants via
App.get_theme_variable_defaults().
Code that needs custom CSS variable values should call
get_css_variable_defaults(dark=...). For the full semantic color palette, look
up the ThemeColors instance via get_registry().
Users can define custom themes in ~/.deepagents/config.toml under
[themes. | https://reference.langchain.com/python/deepagents-code/theme |
| View source on GitHub | https://github.com/langchain-ai/deepagents/blob/bd9bafaad3f51d426563aa24658bbb3a089d4825/libs/code/deepagents_code/app.py |
Viewport: width=device-width, initial-scale=1