Channels Overview
Channels are the boundary where people, applications, and external platforms reach an eve agent. In eve terminology, a channel is not the model, not a tool, and not a third-party connection. It is the edge adapter responsible for receiving platform-specific input, turning that input into an agent message, preserving the resume handle for that surface, and deciding whether and how a response should be delivered back. The channel overview documentation defines this contract explicitly, so developers can reason about Slack, Discord, browser chat, local tooling, and custom webhooks through one shared mental model rather than treating each integration as a separate runtime.
Sources: docs/channels/overview.mdx
Purpose and Scope
Use this page when you need to choose a user-facing integration point for an eve agent, understand what a channel owns, or decide whether a requirement belongs in a channel, a client, a connection, or an agent capability. Channels are for inbound and outbound conversation surfaces: a web application, a terminal UI, a messaging product, a phone or SMS integration, or a custom HTTP endpoint. The channel layer normalizes the incoming request into an agent turn, attaches authentication and continuation context, and controls delivery back to the same platform or another appropriate place.
Sources: docs/channels/overview.mdx
The most important distinction is that channels face users or user platforms, while connections face external systems the model may use during a run. The connections overview describes a connection as a way to wire an agent into an MCP server or an HTTP API described by OpenAPI, with tool discovery, qualified tool names, and token brokering handled by eve. That makes a connection a source of callable capability, not a message surface. A Slack message may enter through a channel, while a Linear or warehouse operation may be exposed through a connection and called later by the model during execution.
Sources: docs/connections/overview.mdx
The client guide completes the picture for application developers. The typed client entrypoint talks to eve's default HTTP API, creates sessions, sends turns, checks health, inspects agent metadata, and consumes event streams without hand-writing the request and newline-delimited stream loop. That client is not a new channel; it is a consumer of the default eve HTTP channel. Browser hooks, scripts, tests, evals, backend jobs, and custom user interfaces can all use that default route surface when they want the standard session protocol instead of a provider-specific adapter.
Sources: docs/guides/client/overview.mdx
Relevant Source Files
- docs/channels/overview.mdx — Defines the channel contract, filesystem location, default eve HTTP channel, custom-channel authoring entry point, Chat SDK boundary, and channel selection guidance.
- docs/connections/overview.mdx — Defines connections so channel responsibilities can be contrasted with MCP and OpenAPI integrations, credential ownership, and model-visible tool discovery.
- docs/guides/client/overview.mdx — Explains the TypeScript client for the default HTTP API, including sessions, authentication, health checks, and why frontend or backend callers often use the eve channel indirectly.
Core Channel Primitives
A channel has three core responsibilities. First, it normalizes platform input into a user message that the agent can process. This keeps provider-specific payloads, signatures, slash command shapes, webhook formats, or browser requests out of the agent's prompt authoring model. Second, it owns the continuation token, which is the resume handle for a conversation on that surface. The token lets future turns reconnect to the right conversation context instead of always creating an unrelated session. Third, it decides delivery: whether to respond, where to respond, and what platform-specific form the response should take.
Sources: docs/channels/overview.mdx
Channel files live in the root agent's channel directory. The file stem becomes the channel identifier, so an intake channel file is addressed by the same stem. The documentation also states that local subagents do not declare channels, which keeps the external edge of a project attached to the root agent rather than scattered through delegated agent implementations. A channel module exports its channel definition as the default export. Developers can scaffold one interactively with the channel-add command, pass a channel kind such as Slack or web, or write the file directly when they need custom behavior.
Sources: docs/channels/overview.mdx
The default eve HTTP channel deserves special attention because it is present even when no matching channel file exists. It is the framework's standard HTTP session API and is the route family used by the local terminal UI, frontend hooks, the typed client, and direct curl-style calls. Add an explicit eve channel file only when you want to override the defaults, most commonly to change route authorization. In practice, this means a new project already has a working message surface for development and application integration before the team chooses any provider-specific channel.
Sources: docs/channels/overview.mdx, docs/guides/client/overview.mdx
Channel Selection Guide
Choose the default eve channel when the caller is a web application, a browser chat interface, a script, a backend service, a test, an eval target, local tooling, or a direct HTTP client. The channel overview points browser chat readers toward the frontend hook, while the client guide presents the typed client as a middle layer: lower level than framework-specific UI hooks, but higher level than raw HTTP and stream parsing. That layering is useful because the same default channel can support a polished frontend, an automation script, and a diagnostic health check without introducing another platform adapter.
Sources: docs/channels/overview.mdx, docs/guides/client/overview.mdx
Choose a platform channel when the user already lives in a messaging or collaboration product and delivery needs to follow that platform's rules. The overview names Slack for mentions, direct messages, and buttons; Discord for slash commands and components; Microsoft Teams for messages and Adaptive Cards; Telegram for bot messages; and Twilio for SMS or speech-transcribed phone calls. These integrations share the channel contract, but each one brings its own provider terms, data flow, authentication model, consent expectations, and response mechanics. Treat the channel as both a technical adapter and a trust boundary.
Sources: docs/channels/overview.mdx
Choose a custom channel when eve does not ship an adapter for the surface you need. The overview describes custom channels as definitions built with the channel API, containing route handlers for common HTTP verbs and WebSocket routes, an events map, and a send call used inside handlers to start or resume sessions. This design lets you accept a proprietary webhook, a line-of-business dashboard request, an internal command endpoint, or a real-time socket while still handing normalized work to eve's session runtime. Delivery remains owned by the channel because only the adapter knows the target platform's expectations.
Sources: docs/channels/overview.mdx
System-to-Code Mapping
The filesystem convention is the most visible implementation contract for channels. An eve project places core agent capabilities in conventional locations, and channels are one of those optional directories under the root agent. The repository README shows the broader authoring model with instructions, tools, skills, channels, and schedules grouped by purpose; the channel overview narrows that down to channel identity and export behavior. This matters operationally because adding, reviewing, or disabling a channel is a file-level change. A reviewer can inspect the channel directory and immediately see which external conversation surfaces are enabled for the root agent.
Sources: docs/channels/overview.mdx
The default HTTP channel maps to application clients rather than a provider SDK. The client guide says a Client binds a host, authentication policy, header policy, and stream reconnection budget. It can check health, inspect an agent, create independent sessions, send messages, and handle stream reconnects with credentials refreshed for each call. Those behaviors rely on the default eve route surface described by the channel overview. If a route requires bearer, basic, Vercel OIDC, bypass, or tenant headers, that authentication is configured by the caller and enforced by the channel route policy.
Sources: docs/channels/overview.mdx, docs/guides/client/overview.mdx
Connections map to agent-internal capability discovery rather than edge delivery. The connections overview states that the runtime name comes from the connection filename, that the model discovers remote tools through built-in connection search, and that tool calls use qualified names formed from the connection and tool. Tokens are resolved and cached per step, do not land in conversation history, and are not shown to the model. This is why a channel should pass user and session identity, while a connection should broker the credential needed to call a remote MCP or OpenAPI tool during the run.
Sources: docs/connections/overview.mdx
Execution Flow
A typical channel flow starts with a platform-specific request. For the default HTTP channel, that request may come from the terminal UI, a frontend hook, the typed client, or a direct HTTP caller. For a platform channel, it may be a provider webhook, slash command, button interaction, message event, or voice/SMS transcription. The channel validates and interprets the request according to its surface, extracts the user message and auth context, and determines whether the turn should start a new session or resume an existing one by using the continuation token associated with that conversation surface.
Sources: docs/channels/overview.mdx, docs/guides/client/overview.mdx
After the message enters eve, the runtime session proceeds independently from the provider request shape. The client guide shows that callers can maintain many sessions, each with its own session identifier, continuation token, and stream cursor. That same separation is useful for channel authors: the platform may think in terms of channels, threads, commands, or phone calls, while eve maintains session continuity through its own handles. When the agent produces output, the channel evaluates delivery. Some surfaces expect an immediate HTTP response, some expect a background follow-up, and some may suppress delivery entirely for a given event.
Sources: docs/channels/overview.mdx, docs/guides/client/overview.mdx
Security and consent decisions belong early in this flow. The channel overview warns that every channel has provider terms, data flow, authorization, and user-consent expectations. Before sending non-public, sensitive, regulated, or production data through a platform, developers should confirm scopes, signature checks, route authentication, and delivery behavior. The connections guide adds another authentication boundary: user-scoped connection credentials depend on the active session having user route auth. A channel that fails to establish the right user context may prevent later user-owned connection tokens from being resolved safely.
Sources: docs/channels/overview.mdx, docs/connections/overview.mdx
API and Configuration Reference
Use these public concepts as the compact reference for the channel overview. Channel modules live below the root agent channel directory and are default exports. The file stem is the channel id. The default eve HTTP channel exists without an explicit channel file. Custom channels are authored through the channel definition API and declare routes, events, and message dispatch. The route helper set named by the overview includes GET, POST, PUT, PATCH, DELETE, and WS. A handler dispatches work with send, including authorization and continuation information, so the runtime can start or resume the correct session.
Sources: docs/channels/overview.mdx
For application callers, the typed client is the primary reference point for the default HTTP channel. A client is created with a host, optional auth, optional headers, redirect behavior, and stream reconnection settings. It exposes health inspection, agent info inspection, and session creation. Sessions can send messages and track continuation state across turns. Credential-bearing clients should use redirect policies that avoid forwarding authorization headers to another origin. Per-request headers can also be attached to an individual turn, which is useful for request identifiers, tenant hints, or route-specific controls.
Sources: docs/guides/client/overview.mdx
For external system access, prefer a connection instead of overloading a channel. MCP connections are appropriate when the remote service already exposes an MCP server with tools and schemas. OpenAPI connections are appropriate when an HTTP API publishes an OpenAPI document that can be turned into operation tools. Static-token authentication can be app-scoped or user-scoped, and user-scoped credentials require an authenticated user on the active session. That distinction keeps channel route authorization, user identity, model-visible tool discovery, and secret handling separated into the parts of eve that own them.
Sources: docs/connections/overview.mdx
Implementation Notes and Next Steps
The overview also draws a clear boundary with the Chat SDK. eve uses card-builder components for composing rich Slack messages, but it does not use the Chat SDK runtime. Chat, adapter, and thread primitives from that SDK are not imported or exposed through eve's public API. When building Slack messages, the card authoring experience may feel familiar, yet channel wiring is still done through eve's channel API. This prevents developers from mixing two runtime models and makes eve's webhook handling, signature verification, event parsing, and thread management the authoritative integration layer.
Sources: docs/channels/overview.mdx
As a next step, start from the default eve channel if you are building a browser UI, local script, evaluation harness, or backend integration. Add a first-party platform channel when the user experience belongs inside Slack, Discord, Teams, Telegram, Twilio, or another supported integration surfaced by the documentation. Reach for a custom channel when the surface is proprietary or has unique delivery rules. Reach for a connection when the agent needs to call an external API or MCP server during reasoning. Keeping those choices separate makes authorization, session continuity, delivery, and secret handling easier to review.
Sources: docs/channels/overview.mdx, docs/connections/overview.mdx, docs/guides/client/overview.mdx