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

# Quickstart

> Build and publish your first agent in five minutes.

## Run an agent

<iframe src="https://www.youtube.com/embed/Hhf09Q-4CUg" title="YouTube video player" frameborder="0" className="w-full aspect-video rounded-xl" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen />

<Steps>
  <Step title="Sign in">
    Go to [app.guild.ai](https://app.guild.ai) and sign in with your Google or GitHub account, or enter your email to receive a passwordless magic link.
  </Step>

  <Step title="Create a workspace">
    Select the **/home** Workspace from the workspace selector at the top of the left sidebar. This is a default Workspace in your personal Guild account.
  </Step>

  <Step title="Install an agent">
    Inside your /home workspace, go to **Agents** and click **Add agent**. Browse the Agent Hub and install one (try `github-issues` if you have a GitHub integration, or any public agent).
  </Step>

  <Step title="Start a session">
    Go back to your workspace and click **New session**. Select your agent, type a message, and press **Enter**.

    The agent runs and responds in the session panel. It may ask clarifying questions or request access to services along the way.
  </Step>
</Steps>

<Tip>
  To connect GitHub, Slack, Jira, or other services, go to your organization's **Settings > Credentials** and click **Connect** for each service.
</Tip>

***

## Build your own agent

Paste this into your coding agent (Claude Code, Cursor, Codex, etc.) to get started:

```text Coding agent prompt theme={null}
Install the Guild CLI globally with npm: npm install -g @guildai/cli
Authenticate by running: guild auth login --no-browser
This will print a URL. Tell me to open it in my browser to complete authentication, then wait for the command to finish.
After auth succeeds, run: guild setup
This will install skills for guild agent development.
Then select the home workspace: guild workspace select home
Then create a new agent: mkdir hello-agent && cd hello-agent && guild agent init --name hello-agent --template LLM
Edit agent.ts to be a friendly greeting agent using llmAgent with multi-turn mode and guildTools.
Test the agent with: echo '{"prompt":"Hello!"}' | guild agent test --mode json
Ask me if the response looks good. Once I confirm, save and publish with: guild agent save --message "First version" --wait --publish
```

Or follow the steps below manually.

Ready to build a custom agent? The Guild CLI handles the full workflow: create, test, save, publish.

### Prerequisites

* **Node.js 18+** and **npm** (see [nodejs.org](https://nodejs.org))

### Install and authenticate

<Steps>
  <Step title="Install the CLI">
    ```bash theme={null}
    npm install -g @guildai/cli
    ```
  </Step>

  <Step title="Authenticate with Guild">
    ```bash theme={null}
    guild auth login
    ```

    This opens your browser to sign in at [app.guild.ai](https://app.guild.ai) and configures your local npm registry for Guild packages.

    Verify:

    ```bash theme={null}
    guild auth status
    # ✓ Authenticated
    ```
  </Step>
</Steps>

<Tip>
  If something goes wrong, run `guild doctor` to diagnose your setup. See the [CLI troubleshooting](/cli/getting-started#troubleshooting) section for common issues.
</Tip>

### Create, test, publish

<Steps>
  <Step title="Create the agent">
    ```bash theme={null}
    mkdir hello-agent && cd hello-agent
    guild agent init --name hello-agent --template LLM
    ```

    This creates the agent in the Guild backend, initializes a local git repo, and pulls starter files:

    ```text theme={null}
    hello-agent/
    ├── agent.ts          # Your agent code
    ├── package.json      # Dependencies (runtime packages are pre-configured)
    ├── tsconfig.json     # TypeScript config
    ├── guild.json        # Local config (managed by the CLI)
    └── .gitignore
    ```
  </Step>

  <Step title="Edit the agent">
    Open `agent.ts` and replace the contents:

    ```typescript theme={null}
    import { llmAgent, guildTools } from "@guildai/agents-sdk"

    export default llmAgent({
      description: "A friendly greeting agent",
      tools: { ...guildTools },
      systemPrompt: `You are a friendly assistant. Greet users warmly and answer their questions.`,
      mode: "multi-turn",
    })
    ```

    `mode: "multi-turn"` keeps the conversation going after each response. `llmAgent` wires `ui_notify` internally so progress notifications (`task.ui.notify()`) work, but hides it from the model unless you explicitly add `ui_notify` to your agent's `tools`. Add `userInterfaceTools` explicitly if your agent needs `ui_prompt` or `ui_ping`.

    <Note>
      The `description` field is optional and deprecated as of `@guildai/agents-sdk` 0.4.0. Guild generates the agent's published description automatically from its code, so setting `description` no longer affects the published description.
    </Note>
  </Step>

  <Step title="Select a workspace">
    ```bash theme={null}
    guild workspace select
    ```

    This prompts you to pick a workspace interactively. You can also pass `--workspace <id>` to `guild agent test` directly.
  </Step>

  <Step title="Test it">
    ```bash theme={null}
    guild agent test
    ```

    This opens an interactive chat session. Ephemeral versions are created automatically when testing from a local agent directory:

    ```text theme={null}
    You: Hello!
    Agent: Hello! Welcome. I'm happy to help. What can I do for you today?
    ```

    Press `Ctrl+C` to exit.
  </Step>

  <Step title="Save and publish">
    ```bash theme={null}
    guild agent save --message "First version" --wait --publish
    ```

    * `--wait` blocks until validation passes
    * `--publish` makes the agent available to your organization

    Your agent is live. Install it in a workspace to use it.

    For details on publishing workflows, see [Publish to the Agent Hub](/platform/publish-to-agent-hub).
  </Step>
</Steps>

## Next steps

<CardGroup cols={2}>
  <Card title="CLI reference" icon="terminal" href="/cli/getting-started">
    Full development loop: templates, testing, publishing, troubleshooting.
  </Card>

  <Card title="Agent SDK" icon="code" href="/guide/sdk-introduction">
    Build advanced agents with typed inputs, tool sets, and platform services.
  </Card>

  <Card title="LLM agents" icon="brain" href="/guide/llm-agents">
    Prompt-driven agents with tools (the simplest way to build).
  </Card>

  <Card title="Coded agents" icon="square-code" href="/guide/coded-agents">
    Deterministic TypeScript agents for algorithmic workflows.
  </Card>
</CardGroup>