Connect a Managed Deep Agent over HTTP

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.

Managed Deep Agents is in public beta and available on 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:

my-agent/
  agent.ts
  channels/
    orders.ts

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.

Add an HTTP channel

Declare the channel

channels/orders.ts

import { channels } from "managed-deepagents";

import { parse, verify } from "../lib/orders.js";

export const channel = channels.http({
  provider: "orders",
  verify,
  parse,
});

provider is a stable name for the external service, such as orders. It identifies the service for identity and reply routing, and it is separate from the channel name. Declaring the channel registers the provider, so any non-empty name works.

Verify the request

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 request and the original rawBody bytes. Check a signature against the bytes, not against a re-serialized body:

lib/orders.ts

import { createHmac, timingSafeEqual } from "node:crypto";
import type { HttpChannelRequest } from "managed-deepagents";

export function verify({ request, rawBody }: HttpChannelRequest): boolean {
  const secret = process.env.ORDERS_WEBHOOK_SECRET ?? "";
  const expected = Buffer.from(
    `sha256=${createHmac("sha256", secret).update(rawBody).digest("hex")}`,
  );
  const received = Buffer.from(request.headers.get("x-orders-signature") ?? "");
  return (
    received.length === expected.length && timingSafeEqual(received, expected)
  );
}

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 for the signing key. A verify callback that raises rejects the request with 500.

Parse the request into a message

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 standard Response.The message carries three fields:

userId: 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.
threadId: 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 an array of LangChain content blocks.

threadId 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.

lib/orders.ts

import type {
  HttpChannelParseResult,
  HttpChannelRequest,
} from "managed-deepagents";
import { orderThreadId } from "./ids.js";

export async function parse({
  request,
}: HttpChannelRequest): Promise<HttpChannelParseResult> {
  const event = await request.json();
  if (event.type !== "order.comment") {
    return { type: "ignore" };
  }
  return {
    type: "message",
    message: {
      userId: event.actor.id,
      threadId: orderThreadId(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:

return {
  type: "ignore",
  response: Response.json({ challenge: event.challenge }),
};

Send replies with messaging

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 process.env and returns an object with a post method. post receives the reply content and the original event, and returns the posted message id and an optional url:

channels/orders.ts

import { channels } from "managed-deepagents";

import { parse, verify } from "../lib/orders.js";

export const channel = channels.http({
  provider: "orders",
  verify,
  parse,
  messaging: (env) => ({
    async post({ content, event }) {
      const response = await fetch("https://orders.example.com/api/comments", {
        method: "POST",
        headers: { authorization: `Bearer ${env.ORDERS_API_TOKEN}` },
        body: JSON.stringify({ orderId: event.order.id, body: content }),
      });
      const posted = await response.json();
      return { id: posted.id };
    },
  }),
});

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, 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:

POST https://<deployment-url>/channels/<name>/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, so tools and middleware can read the fields the message text does not carry:

{
  "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.

npx mda deploy

pnpm exec mda deploy

bunx 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://<deployment-url>/channels/<name>/events with the external service as its webhook target.

Get started

Agent capabilities

Build and deploy

Connect a Managed Deep Agent over HTTP

Project structure

Add an HTTP channel

Call the endpoint

Read the event in the agent

Deploy the agent

See also

​Project structure

​Add an HTTP channel

​Call the endpoint

​Read the event in the agent

​Deploy the agent

​See also

Project structure

Add an HTTP channel

Call the endpoint

Read the event in the agent

Deploy the agent

See also