Quickstart

Run an agent

Go to app.guild.ai and sign in with your Google or GitHub account, or enter your email to receive a passwordless magic link.

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.

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).

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.

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

Build your own agent

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

Coding agent prompt

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)

Install and authenticate

Install the CLI

npm install -g @guildai/cli

Authenticate with Guild

guild auth login

This opens your browser to sign in at app.guild.ai and configures your local npm registry for Guild packages.Verify:

guild auth status
# ✓ Authenticated

If something goes wrong, run guild doctor to diagnose your setup. See the CLI troubleshooting section for common issues.

Create, test, publish

Create the agent

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:

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

Edit the agent

Open agent.ts and replace the contents:

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.

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.

Select a workspace

guild workspace select

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

Test it

guild agent test

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

You: Hello!
Agent: Hello! Welcome. I'm happy to help. What can I do for you today?

Press Ctrl+C to exit.

Save and publish

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.

Next steps

CLI reference

Full development loop: templates, testing, publishing, troubleshooting.

Agent SDK

Build advanced agents with typed inputs, tool sets, and platform services.

LLM agents

Prompt-driven agents with tools (the simplest way to build).

Coded agents

Deterministic TypeScript agents for algorithmic workflows.

Overview

The Smith

Platform

Insights

Agent SDK

Run an agent

Build your own agent

Prerequisites

Install and authenticate

Create, test, publish

Next steps

CLI reference

Agent SDK

LLM agents

Coded agents

​Run an agent

​Build your own agent

​Prerequisites

​Install and authenticate

​Create, test, publish

​Next steps

CLI reference

Agent SDK

LLM agents

Coded agents

Run an agent

Build your own agent

Prerequisites

Install and authenticate

Create, test, publish

Next steps