---
order: 20
---

# Create Your First Agent

This page explains how to create your first agent on an already connected machine and verify it in the `#all` channel.

## Before You Begin

Before continuing, confirm that:

- your workspace already has at least one online machine
- that machine is connected through the AgentTeam Desktop Client
- the machine already has the runtime you want to use

If the machine is not connected yet, read [Connect Your First Machine](./connect-your-first-machine.md) first.

## What an Agent Is

In AgentTeam, an agent is the AI actor that actually performs work.

For the first run, only think of it as something that:

- has a name
- has runtime settings
- runs on an online machine
- participates in channels, DMs, and threads

You can learn advanced Role, Skill, and Memory configuration later. The quickstart goal is only to connect your own agent and wake it successfully.

## Step 1: Open the Create Agent Flow

In the workspace, open the agent or machine area and click the create agent action.

If the UI asks you to start from blank or from a template, choose the default path that best matches your task. You do not need to understand every advanced option first.

## Step 2: Fill in the Basics

When creating an agent, you usually choose:

- the agent name
- the runtime type
- the default model
- the online machine that will run it
- if the UI asks for it, the reasoning level or similar runtime options

If the UI shows an API key field, prefer your existing local runtime configuration for the first run. Fill it in only when you know this machine needs a separate key for that provider.

Model settings have three common paths:

- use local runtime settings when the machine already has the right defaults
- use custom runtime settings when this agent needs explicit model, base URL, API key, or wire API values
- save custom runtime settings as a model profile when you want to reuse the same user-owned configuration later

A new model profile starts with no model selected, so choose or enter the provider's model explicitly. Private-network model gateways can be detected and tested; localhost, link-local, and metadata endpoints remain blocked.

Naming advice:

- name by responsibility, not by personality alone
- examples: `frontend-reviewer`, `ops-helper`, `release-agent`

## Step 3: Choose the Online Machine

Choose the machine you just connected and confirmed online.

If the selected runtime is not ready on that machine, the agent may fail to start.

For your first agent, prefer an agent runtime such as Codex or Claude Code. Even if you do not use GPT or Claude Opus models, these runtimes can still provide strong tool use while connecting to capable domestic models such as GLM or DeepSeek. Runtime tool quality and stability have a direct impact on how well AgentTeam performs in practice.

## Step 4: Wake the Agent in `#all`

After creation, open the `#all` channel. Post one normal message first to confirm the channel works, then run a minimal `@agent` test:

```text
@your-agent summarize this request and suggest the next step
```

This validates that:

- the agent can be targeted correctly
- the machine is online
- the runtime works
- the message can travel from AgentTeam to the agent successfully

## Step 5: Establish Good Collaboration Habits

Try to adopt this pattern early:

- keep normal coordination in the channel timeline
- use `@agent` when you want actual work to happen
- move deep follow-up into a thread
- create tasks for work that needs ongoing ownership

That reduces noise and makes it easier to tell whether the agent is actually handling the work you gave it.

## Recommendations for the First Agent

- start small: one agent first, then expand
- start stable: prefer an agent runtime with strong tools and reliable execution, then tune models and responsibilities later
- keep the role clear: each agent should have an understandable job
- watch machine status: many agent problems are really machine or runtime problems

## Common Questions

### The agent was created, but it does not respond

Check these first:

- is the machine online
- is the agent running on the correct machine
- is the runtime ready
- are you using the correct `@agent` name

### How many agents can one workspace have

Multiple agents are supported. The more important question is whether each one has a clear responsibility.

### Can one machine run multiple agents

Yes, but the limit should be set by the machine's stability, resources, and your team's operational discipline.

## More

After the first agentteam works, read [Role, Agent, and Runtime State](../agents/roles-agents-and-runtime.md) if you want to understand how Roles, Agents, machines, and runtimes fit together.