> ## Documentation Index > Fetch the complete documentation index at: https://langchain-5e9cc07a-preview-docsmd-1789592284-4ee7e30.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Connect a Managed Deep Agent over HTTP > Start Managed Deep Agents runs from any external service that can send a JSON webhook, and return responses through your own transport. An HTTP channel turns a managed deep agent into a JSON endpoint that any external service can call. Use it for a provider that Managed Deep Agents does not support directly, such as an order system, a support tool, or your own application. You supply two callbacks: one that authenticates the request and one that converts it into a message. Managed Deep Agents owns caller handoff, thread selection, the agent run, and the reply. For the provider-managed alternative, see [Slack](/langsmith/python/managed-deep-agents-channels-slack). Managed Deep Agents is in **public [beta](/langsmith/release-stages)** and available on [LangSmith Cloud](/langsmith/cloud) in the US region only. HTTP channels require `managed-deepagents>=0.8.0`. ## Project structure An HTTP channel declaration lives under `channels/`, like any other channel: ```text theme={null} my-agent/ agent.py channels/ orders.py ``` The file name becomes the channel name and the endpoint path. A project can declare more than one HTTP channel, and names must be unique. For the full project layout, see [Project structure](/langsmith/python/managed-deep-agents-project-structure). ## Add an HTTP channel ```python channels/orders.py theme={null} from managed_deepagents import channels from lib.orders import parse, verify channel = channels.http( provider="orders", verify=verify, parse=parse, ) ``` `provider` is a stable name for the external service, such as `orders`. It identifies the service for [identity](/langsmith/python/managed-deep-agents-identity) and reply routing, and it is separate from the channel name. Declaring the channel registers the provider, so any non-empty name works. Managed Deep Agents calls `verify` first. Return `true` to continue to `parse`, or `false` to reject the request with `401`. `verify` receives an `HttpChannelRequest` with a Starlette `request` and the original `raw_body` bytes. Check a signature against the bytes, not against a re-serialized body: ```python lib/orders.py theme={null} import hashlib import hmac import os from managed_deepagents import HttpChannelRequest def verify(context: HttpChannelRequest) -> bool: secret = os.environ["ORDERS_WEBHOOK_SECRET"] digest = hmac.new(secret.encode(), context.raw_body, hashlib.sha256).hexdigest() received = context.request.headers.get("x-orders-signature", "") return hmac.compare_digest(f"sha256={digest}", received) ``` The endpoint has no platform authentication. Channel event routes authenticate inside the adapter, not through Managed Deep Agents ingress. That makes `verify` the only thing standing between the public internet and an agent run. Always check a signature or a shared secret, and never return `true` unconditionally. Use a [deployment secret](/langsmith/python/managed-deep-agents-deploy) for the signing key. A `verify` callback that raises rejects the request with `500`. `parse` converts a verified request into a message that starts a run, or ignores the event. Return one of two shapes: * `{"type": "message", "message": {...}}` starts a run. * `{"type": "ignore"}` skips the event. Both accept an optional `response`, a Starlette `Response`. The message carries three fields: * **`user_id`**: The caller's ID in the external service, resolved from the verified event. Agent Auth maps it to the principal whose credentials the run may use, so derive it from verified data rather than from an unauthenticated field. * **`thread_id`**: The conversation to run in, as a UUID. Managed Deep Agents lowercases it and maps it to a durable agent thread, so the same value continues the same conversation. * **`content`**: The message text, or a list of LangChain content blocks. `thread_id` must be a UUID. Managed Deep Agents rejects any other value with `400`, so map an external conversation ID to a UUID before returning it, for example with `uuid.uuid5`. ```python lib/orders.py theme={null} import json import uuid from managed_deepagents import HttpChannelParseResult, HttpChannelRequest ORDERS_NAMESPACE = uuid.UUID("6f0c9a3e-8f1a-4f5e-9c2b-7d4e1a2b3c4d") def parse(context: HttpChannelRequest) -> HttpChannelParseResult: event = json.loads(context.raw_body) if event.get("type") != "order.comment": return {"type": "ignore"} return { "type": "message", "message": { "user_id": event["actor"]["id"], "thread_id": str(uuid.uuid5(ORDERS_NAMESPACE, event["order"]["id"])), "content": event["comment"]["body"], }, } ``` Return a `response` to control what the provider receives. Managed Deep Agents sends it after the run is accepted for a message, and immediately for an ignored event. Use it to answer a provider's verification challenge without starting a run: ```python theme={null} return { "type": "ignore", "response": JSONResponse({"challenge": event["challenge"]}), } ``` Add `messaging` to deliver the agent's final response back to the external service. Omit it for a channel that only starts runs. `messaging` receives the process environment and returns an object with an async `post` method. `post` receives the reply `content` and the original `event`, and returns the posted message `id` and an optional `url`: ```python channels/orders.py theme={null} from collections.abc import Mapping import httpx from managed_deepagents import channels from lib.orders import parse, verify def messaging(env: Mapping[str, str]) -> object: class Transport: async def post(self, *, content: object, event: object) -> dict[str, str]: async with httpx.AsyncClient() as client: response = await client.post( "https://orders.example.com/api/comments", headers={"authorization": f"Bearer {env['ORDERS_API_TOKEN']}"}, json={"order_id": event["order"]["id"], "body": content}, ) return {"id": response.json()["id"]} return Transport() channel = channels.http( provider="orders", verify=verify, parse=parse, messaging=messaging, ) ``` Managed Deep Agents posts the reply after the run finishes, separately from the response the provider already received. Two cases produce no reply: a run that pauses on an [interrupt](/langsmith/python/managed-deep-agents-tools#respond-to-an-interrupt), and a run whose agent already delivered a final message itself. A `messaging` callback that fails to return a usable transport rejects the request with `500`. ## Call the endpoint A deployed HTTP channel accepts requests at the channel name, not the provider name: ```text theme={null} POST https:///channels//events ``` A declaration in `channels/orders.py` or `channels/orders.ts` is reachable at `/channels/orders/events`. The request body must be standard JSON encoded as UTF-8. Managed Deep Agents answers with one of these, unless `parse` returned its own `response`: | Status | Body | Cause | | ------ | --------------------------------------------- | --------------------------------------------------------------------------------------- | | `202` | `{"status": "accepted", "deliveryId": "..."}` | The run started. | | `202` | `{"status": "ignored"}` | `parse` returned an ignore result. | | `400` | `{"error": "invalid channel payload"}` | The body is not standard JSON, or `parse` raised. | | `400` | `{"error": "invalid channel parse result"}` | `parse` returned an unrecognized shape. | | `400` | `{"error": "invalid channel message"}` | The message is missing a caller, has a thread that is not a UUID, or has empty content. | | `401` | `{"error": "invalid channel signature"}` | `verify` returned `false`. | | `500` | `{"error": "channel verification failed"}` | `verify` raised. | A `202` means the run was accepted, not that it finished. The agent's answer arrives later through `messaging`. ## Read the event in the agent Each run carries the provider and the original event as [run context](/langsmith/python/managed-deep-agents-middleware#use-runtime-context), so tools and middleware can read the fields the message text does not carry: ```json theme={null} { "provider": "orders", "raw_event": { "type": "order.comment", "order": { "id": "A-1024" } } } ``` `raw_event` is the parsed request body, preserved as received. ## Deploy the agent An HTTP channel needs no provider authorization, so deployment is the standard command. Managed Deep Agents mounts the endpoint from the declaration. ```bash theme={null} uv run mda deploy ``` Put the signing key and any reply credentials in the project `.env` so `mda deploy` forwards them as deployment secrets. Then register `https:///channels//events` with the external service as its webhook target. ## See also * [Channels overview](/langsmith/python/managed-deep-agents-channels): understand how channels connect messaging services to an agent. * [Slack](/langsmith/python/managed-deep-agents-channels-slack): use the provider-managed Slack channel instead. * [Identity](/langsmith/python/managed-deep-agents-identity): authenticate callers and scope channel runs to the resolved user. * [Deploy an agent](/langsmith/python/managed-deep-agents-deploy): configure and deploy a managed deep agent. ***
[Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers. [Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/langsmith/managed-deep-agents-channels-http.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).