# agents::begin

> Tag 0: the client begins its work on an agent container, once, first, and hands over the arguments and the template id; the server answers Begun, carrying the dependencies the container declared and the secrets it takes, once the container holds them and, for the life of the connection, every loop of the agent on the scope — Active, every chunk the agent says, and Inactive carrying the rotating secrets handed back; every channel of the container’s life rides this scope.

Canonical: https://protocol.diverge.network/2.3.0/container-proxy-endpoints/agents-begin/
Specification revision: 2.3.0

The client opens the scope with a request whose payload is the tag
byte `0` followed by the request as JSON: the arguments and the id of
the template the container is made from. The server answers with
exactly one `Begun` response, carrying the dependencies the
container's program declared and the secrets it takes, once the
container holds its arguments, and after it sends every loop of the
agent's conversation as responses, for as long as the connection
lives; the server ends the scope by the response finish when the
server ends, or after an error it sends when it cannot collect a
loop's rotating secrets. This section states what the server does. It
states nothing about the client beyond the order
[Connection](/2.3.0/container-proxy/connection/) provides.

- **The request.** [Request](/2.3.0/container-proxy-endpoints/agents-begin/request/) states its form.
- **The response.** [Response](/2.3.0/container-proxy-endpoints/agents-begin/response/) states the one response
  and the sequence of the main stream.
- **The channels.** The client opens the channels that
  [Client Channels](/2.3.0/container-proxy-endpoints/agents-begin/client/) defines; the server opens the
  channels that [Server Channels](/2.3.0/container-proxy-endpoints/agents-begin/server/) defines. Each channel is
  its own section. Neither party opens a channel on the scope before
  the `Begun` response.

## The order

1. **The server reads the request.** A request whose payload does not
   decode is answered by a response finish that no response precedes,
   as [Container Proxy Endpoints](/2.3.0/container-proxy-endpoints/) provides. A begin on a
   connection that has begun is answered by exactly one response, the
   error, and the finish; the first begin continues.
2. **The server hands the arguments and the template id to the
   container.** Both are held for the life of the container. A
   container that refuses them is answered by exactly one response,
   the error in the container's own words, and the finish; the
   connection has not begun.
3. **The server answers `Begun`.** Exactly once, and before any chunk,
   carrying what the container's program answered its registration
   with: the dependency tool templates it declared, and the secrets
   it takes, each by name to its mode. The server reads neither.
4. **The server holds delivery until the container is fed.** From
   `Begun`, and from every `Inactive`, the server delivers no message
   to a program that declared one or more secrets until the client
   has opened a [secrets](/2.3.0/container-proxy-endpoints/agents-begin/client/secrets/)
   channel and the server has answered it `Fed`. A program that
   declared no secret is delivered to from `Begun` and from every
   `Inactive`.
5. **The server relays the conversation.** A message the client sends
   on an [enqueue](/2.3.0/container-proxy-endpoints/agents-begin/client/enqueue/) channel is the
   only thing that starts a loop or joins its queue. The server sends
   `Active` when a loop begins, each chunk the agent produces as one
   response, in the order produced, and, when the loop ends, collects
   from the program the value of every `rotating` secret it declared
   and sends `Inactive` carrying them. A collect the program does not
   answer with every value asked for is answered by exactly one
   response, the error naming the secret and carrying no value, and
   the finish.
6. **The scope ends with the server.** The server sends the response
   finish when it ends, and after the error of step 5, and at no
   other time.

## The rules that hold throughout

- **One begin.** The server serves exactly one begin scope per
  connection.
- **Both directions.** The server opens channels on this scope for
  everything the container asks of the world outside it — its
  database connections, its tool calls outward — and the
  client opens channels on it for the image's `/DIVERGE.md`, the
  queue, the feed of the secrets' values, and its half of each
  database connection.
- **No daemon connection.** An agent container holds no account and
  asks the daemon nothing: the server opens no daemon channel on
  this scope, and the client opens none.
- **One error after `Begun`.** After `Begun`, the server sends an
  error response only when it cannot collect a loop's rotating
  secrets, and that error ends the scope. A loop that ends in any
  other way is reported by `Inactive` and by nothing else on the
  scope.
- **No value in an error.** No error the server sends carries the
  value of a secret.
- **No timeout.** The server imposes no timeout on any channel or on
  the scope.