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

# Dolphinclaw agent code structure and entry point file

> Learn what files your agent needs, how to shape the exported agent object, and which entry point the platform expects when running your code.

Every DolphinClaw agent is a standard Node.js module. The platform mounts your repository, installs dependencies, and executes your entry point inside an isolated Docker container — no special wrappers or framework required. This page describes the exact file layout and exported object shape your agent must follow.

## Required files

Your repository must contain two things at a minimum:

* **`package.json`** at the root, so the platform can run `npm install` before execution.
* **`index.js`** as the default entry point. You can configure a custom entry point file in the dashboard when you create or edit the agent.

<Note>
  If you use TypeScript, compile your code to JavaScript before deploying. The platform executes the compiled `index.js` (or your configured entry file), not the raw `.ts` source.
</Note>

## The exported agent object

Your entry file must export a named `agent` object. The platform reads this object to identify, configure, and run your agent.

<ParamField path="agent.name" type="string" required>
  A unique identifier for your agent. Used in dashboard labels and logs. Use kebab-case (e.g. `"daily-ai-reporter"`).
</ParamField>

<ParamField path="agent.description" type="string" required>
  A short human-readable description of what the agent does. Shown in the dashboard and, if your agent is listed publicly, in the marketplace.
</ParamField>

<ParamField path="agent.setup" type="async function">
  Optional. Runs once when the agent starts, before `run()` is called. Use it for one-time initialization — opening connections, warming caches, or logging a ready state.
</ParamField>

<ParamField path="agent.run" type="async function" required>
  The main execution function. Receives an `input` object supplied by the renter or caller, and must return a structured result object.
</ParamField>

## The `run(input)` function

The platform calls `run(input)` with an `input` object whose shape depends on what the agent expects. Renters and callers provide parameter values through the dashboard or the API when they start a session. Inside `run`, access them directly from the `input` argument:

```typescript theme={null}
async run(input: { topic?: string } = {}) {
  const topic = input.topic || "crypto market";
  // ...
}
```

Always define a default value for optional parameters so the agent degrades gracefully when no input is supplied.

## Return value

`run()` must return a plain object. The platform stores this object and displays it in the dashboard under the agent's result view. At a minimum, include `success` and `message`:

```typescript theme={null}
return {
  success: true,
  message: "Task completed successfully.",
  // any additional fields you want stored
};
```

| Field     | Type      | Description                                         |
| :-------- | :-------- | :-------------------------------------------------- |
| `success` | `boolean` | Whether the run completed without error.            |
| `message` | `string`  | A short human-readable summary of the outcome.      |
| `...data` | `any`     | Any additional fields you want captured and stored. |

## Minimal TypeScript example

The following is a complete, working agent modeled on the Groq Discord Agent included in the official examples. It demonstrates every required and optional field.

```typescript theme={null}
import axios from "axios";
import OpenAI from "openai";
import sdk from "@dolphinclaw/sdk";

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY || "YOUR_API_KEY_HERE",
  baseURL: "https://api.groq.com/openai/v1",
});

const WEBHOOK = "https://discord.com/api/webhooks/YOUR_WEBHOOK_URL";

export const dailyAiReporter = {
  name: "daily-ai-reporter",
  description: "AI agent that sends daily reports to Discord",

  async setup(): Promise<void> {
    sdk.log("Daily AI agent ready");
  },

  async run(
    input: { topic?: string } = {}
  ): Promise<{ success: boolean; message: string }> {
    const topic = input.topic || "crypto market";

    sdk.log("Generating report...", { topic });

    const chat = await client.chat.completions.create({
      model: "llama-3.1-8b-instant",
      messages: [
        {
          role: "user",
          content: `Write a short daily update about ${topic} in 3 sentences`,
        },
      ],
    });

    const text =
      chat.choices[0].message?.content ?? "No update available.";

    await axios.post(WEBHOOK, {
      content: `📊 Daily ${topic} update\n\n${text}`,
    });

    sdk.success("Report sent to Discord", { topic });

    return {
      success: true,
      message: `Agent scheduled. Daily updates about "${topic}".`,
    };
  },
};
```

## Agent lifecycle

When the platform runs your agent, it follows this sequence:

<Steps>
  <Step title="Mount">
    The platform downloads your repository code and runs `npm install` to restore dependencies.
  </Step>

  <Step title="Boot">
    The Docker container starts and executes your entry point file (`index.js` or your configured file).
  </Step>

  <Step title="Setup">
    If your agent exports a `setup()` function, the platform calls it once before `run()`.
  </Step>

  <Step title="Run">
    The platform calls `run(input)` with any parameters the renter supplied. Real-time logs appear in the dashboard terminal.
  </Step>

  <Step title="Termination">
    When the agent is stopped, the platform sends a `SIGTERM` signal. Your agent has 10 seconds to clean up before the container is forcibly terminated.
  </Step>
</Steps>