> ## Documentation Index
> Fetch the complete documentation index at: https://enterprise-docs.trytilde.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Anatomy of an agent

> What a Tilde agent is made of: your framework code, the Tilde SDK, and a container.

A Tilde agent has three parts:

* **Your agent code**, written in the framework you already use.
* **The Tilde SDK**, which connects your code to the gateway and gives it an invocation context.
* **A container or Lambda function** that packages the two.

Your code contains no chat provider integration, no provider API keys, and no HTTP server. The gateway supplies all three at runtime.

## Example agent

This agent uses the Vercel AI SDK. It is two small files: one connects to Tilde, and one handles a single invocation.

```typescript src/index.ts theme={"system"}
import { connectAgent, type AgentContext } from "@trytilde/sdk";
import { createOpenAI } from "@ai-sdk/openai";
import { respond } from "./agent.js";

// Build the model client for each invocation. `ctx.inference`
// returns a base URL for Tilde's inference gateway and a
// placeholder API key. The gateway swaps in the real provider
// credential, so this process holds no key.
const modelFor = (ctx: AgentContext) => {
  const openai = createOpenAI(ctx.inference("openai/production"));
  return openai.responses("gpt-4o-mini");
};

// Dial out to Tilde. `connectAgent` reads TILDE_GATEWAY_URL and
// TILDE_DEPLOYMENT_TOKEN, opens an outbound HTTP/2 stream, and
// sends ready heartbeats. This process listens on no port.
const connection = connectAgent({
  // Tilde calls `run` once for each invocation, with a fresh
  // context.
  run: (ctx) => respond(ctx, modelFor(ctx)),

  onRegistered: (registration) =>
    console.log("Agent is ready", registration.deploymentId),
});

// On shutdown, stop taking work and let active invocations
// finish and report. Your orchestrator sends SIGTERM during a
// rollout.
for (const signal of ["SIGINT", "SIGTERM"] as const)
  process.once(signal, () => void connection.close());
```

```typescript src/agent.ts theme={"system"}
import type { AgentContext } from "@trytilde/sdk";
import {
  convertToAiSdkMessages,
  convertToAiSdkTools,
} from "@trytilde/sdk-vercel-ai-node";
import {
  APICallError,
  convertToModelMessages,
  generateText,
  stepCountIs,
  type LanguageModel,
} from "ai";

const instructions = [
  "You are a support assistant.",
  "Use the current channel tools to respond to the latest message.",
  "Model text is private and is not delivered to the user.",
].join(" ");

// Handle one invocation with plain Vercel AI SDK calls.
export async function respond(
  ctx: AgentContext,
  model: LanguageModel,
) {
  try {
    // 1. Load the conversation from Tilde, and convert it into
    //    AI SDK messages. Attachments are downloaded for you.
    const history = await ctx.message.history();
    const uiMessages = await convertToAiSdkMessages({
      messages: history.items,
      context: ctx,
    });

    // 2. Convert the tools of the channel this message arrived
    //    on, such as sendMessage, into AI SDK tools. Each call
    //    runs through the gateway, which checks the agent's
    //    capabilities and records it.
    const tools = convertToAiSdkTools(ctx.channel.current);

    // 3. Call the model. This is the standard AI SDK function.
    //    The request goes through Tilde's inference gateway.
    const result = await generateText({
      model,
      system: instructions,
      messages: await convertToModelMessages(uiMessages),
      tools,
      // Let the model call tools, read results, and call again.
      stopWhen: stepCountIs(8),
      maxOutputTokens: 600,
      // Stop when a user interrupts or an operator stops the run.
      abortSignal: ctx.signal,
      // Tag model calls so you can find them in the Tracing tab.
      experimental_telemetry: { functionId: "support-agent" },
    });

    // 4. The agent replied by calling sendMessage in step 3.
    //    `result.text` is private. Record it as a working note.
    if (result.text) await ctx.reason(result.text);
  } catch (error) {
    // Provider error bodies can contain sensitive details.
    // Log only the status.
    const status = APICallError.isInstance(error)
      ? error.statusCode
      : undefined;
    if (ctx.signal.aborted) console.warn("Invocation cancelled");
    else console.error("Invocation failed", { status });
    const suffix = status ? ` (${status})` : "";
    throw new Error(`Agent run failed${suffix}`);
  }
}
```

```dockerfile Dockerfile theme={"system"}
FROM node:22-slim AS build
WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN corepack enable && pnpm install --frozen-lockfile
COPY . .
RUN pnpm build

FROM node:22-slim
WORKDIR /app
ENV NODE_ENV=production
COPY --from=build /app/node_modules ./node_modules
COPY --from=build /app/dist ./dist
USER node
# No EXPOSE: the agent only dials out.
CMD ["node", "dist/index.js"]
```

The container needs two environment variables, `TILDE_GATEWAY_URL` and `TILDE_DEPLOYMENT_TOKEN`. See [Deploy direct agents](https://enterprise-docs.trytilde.ai/deployment/direct-agents.md).

### The invocation context

Everything your agent does during an invocation goes through `ctx`. It is bound to one invocation, and carries that invocation's short-lived token.

| Member | Purpose |
| - | - |
| `ctx.message.history()` | The conversation so far, paginated, with attachments. |
| `ctx.channel.current` | The tools of the channel the message arrived on, such as `sendMessage`. |
| `ctx.inference(name)` | Client settings for an assigned [inference connection](https://enterprise-docs.trytilde.ai/inference-providers.md). |
| `ctx.tools` | The agent's granted [tools](https://enterprise-docs.trytilde.ai/tools.md), with their schemas. |
| `ctx.goals`, `ctx.tasks` | The agent's own plan, shown in the [session](https://enterprise-docs.trytilde.ai/sessions.md). |
| `ctx.reason(text)` | Records a working note. It is never sent to the user. |
| `ctx.signal` | Aborts when a user interrupts, or an operator stops the run. Pass it to model and tool calls. |
| `ctx.stop()` | Ends the invocation. |

The adapter package only converts types. `convertToAiSdkMessages` and `convertToAiSdkTools` turn Tilde history and tools into AI SDK values, and you call `generateText` or `streamText` yourself. To use a framework with no adapter, read `ctx` directly inside `run`.

## Lifecycle of a request

![Sequence of one request: a message reaches the gateway, passes access checks and request guards, wakes the agent with a short-lived token, the agent calls the LLM through the gateway, replies through a channel tool, and the gateway applies response guards before delivery](https://mintcdn.com/tilde-enterprise/iqzekvN3Ed8yJqIb/images/request-lifecycle.drawio.svg?fit=max\&auto=format\&n=iqzekvN3Ed8yJqIb\&q=85\&s=9325e211f9048dc092417831b704c978)

&#x20;*Click to zoom*

**1. A message arrives**

A chat provider's webhook, or your own app through native chat, delivers the message to the gateway.

**2. The gateway checks and routes it**

The gateway checks that the sender can message this agent, runs [request guards](https://enterprise-docs.trytilde.ai/security/middleware.md), and picks a ready deployment. See [Routing](https://enterprise-docs.trytilde.ai/routing.md).

**3. The gateway wakes the agent**

The gateway sends the invocation down the agent's open HTTP/2 stream, with a short-lived token. The SDK calls your `run` function.

**4. The agent loads its context**

The agent reads the conversation history and the channel's tools through the gateway.

**5. The agent calls the model**

The LLM request goes to the gateway with a placeholder key. The gateway injects the real credential, forwards the request, streams the response back, and records the usage.

**6. The agent replies**

The agent calls the channel's send tool.

**7. The gateway screens the reply**

The gateway checks the agent's [capabilities](https://enterprise-docs.trytilde.ai/iam.md#agent-capabilities), runs response guards, and records the tool call.

**8. The reply is delivered**

The gateway sends the reply through the provider's API, with the connection's credential.

**9. The agent reports**

The SDK uploads logs and traces, and reports that the invocation ended.

For a sidecar agent, the sidecar takes the gateway's place in steps 3 to 7, on loopback.

## Lifecycle of an agent

An agent has many deployments over its life. Each deployment is one release of your container, registered in Tilde and tied to a commit.

![Two rows of steps. First deployment: build, register the deployment, roll out, connect, and serve. Deploying an update: build version two, register it, roll it out beside version one, route new conversations to it, drain version one, and retire it](https://mintcdn.com/tilde-enterprise/iqzekvN3Ed8yJqIb/images/agent-deployment-lifecycle.drawio.svg?fit=max\&auto=format\&n=iqzekvN3Ed8yJqIb\&q=85\&s=2d284f4f50f963ed163989e267f28b4f)

&#x20;*Click to zoom*

### First deployment

1. **Build** the agent image from your Dockerfile.
2. **Register a deployment.** Tilde returns a deployment token once. The deployment is registered but offline.
3. **Roll out** your replicas with the token.
4. **Connect.** Each replica dials the gateway and sends ready heartbeats.
5. **Serve.** Once a replica is ready, new conversations route to the release.

### Deploying an update

An update is a new deployment of the same agent. You never replace a deployment in place.

1. **Build** the new image.
2. **Register** a second deployment. It has its own token.
3. **Roll out** the new release beside the old one. Both stay connected.
4. **Route.** In latest mode, new conversations go to the new release as soon as it is ready. In weighted mode, you send it a percentage first.
5. **Drain.** Conversations that started on the old release stay pinned to it, so keep it running until they end.
6. **Retire** the old deployment. Its token stops working.

To roll back, promote the old deployment. It becomes the serving deployment again, and conversations pinned to the new release stay there.

Automate these steps in your pipeline. See [Release agents from CI](https://enterprise-docs.trytilde.ai/deployment/ci-cd.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.