Create Your First Agent

This guide walks you through creating an AI agent on TeamDay — from a quick assistant to a fully equipped team member with skills, MCP integrations, and subagents.

Agents are AI employees. They have a name, role, system prompt, model, and equipment. You hire them, equip them, and put them to work.

Quick Start

The fastest way to get an agent running.

Via Web App

From the org home page, click + Create Agent
Fill in:
- Name: “Research Assistant”
- Role: “Research and summarization”
- System Prompt: “You are a research assistant. Find information, summarize it clearly, and cite your sources.”
Start chatting

Via CLI

teamday agents create \
  --name "Research Assistant" \
  --role "Research and summarization" \
  --system-prompt "You are a research assistant. Find information, summarize it clearly, and cite your sources."

Via API

curl -X POST "https://cc.teamday.ai/api/v1/agents" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Research Assistant",
    "systemPrompt": "You are a research assistant. Find information, summarize it clearly, and cite your sources.",
    "role": "Research and summarization"
  }'

Response:

{
  "success": true,
  "id": "abc123xyz",
  "name": "Research Assistant",
  "status": "active",
  "chatUrl": "/agents/abc123xyz/chat"
}

Save the id — you’ll need it to chat with the agent, equip it, or add it to a Space.

Choose a Model

TeamDay supports multiple AI models across providers. Set the model field when creating an agent.

Claude (Anthropic) — Default Provider

Model ID	Name	Best For
`claude-sonnet-4-6`	Claude Sonnet 4.6	Best value — fast, smart, great for coding (default)
`claude-opus-4-6`	Claude Opus 4.6	Most capable — complex reasoning and agentic tasks
`claude-haiku-4-5-20251001`	Claude Haiku 4.5	Fastest — ideal for simple tasks

Other Providers

Model ID	Name	Provider
`gemini-2.5-pro`	Gemini 2.5 Pro	Google
`gemini-2.5-flash`	Gemini 2.5 Flash	Google
`gpt-5.1-2025-11-13`	GPT-5.1 (coming soon)	OpenAI
`gpt-5-mini`	GPT-5 Mini (coming soon)	OpenAI

If you don’t specify a model, agents default to claude-sonnet-4-6.

Equip Your Agent

Agents have four types of equipment, managed via the agent’s detail panel (four tabs):

Equipment	What It Does	Example
Tools	Built-in Claude tools — available by default	Read, Write, Edit, Bash, Glob, Grep, WebSearch, WebFetch
Skills	Reusable capabilities you attach to the agent	Research, data analysis, image generation
MCPs	External service integrations	Google Analytics, Ahrefs, Slack, databases
Subagents	Other agents this agent can delegate work to	A code reviewer agent delegating to a security scanner agent

You “equip” an agent by attaching skills, MCPs, or subagents to it through the detail panel or API.

Attach Skills via CLI

teamday agents add-skill <agent-id> core:research-assistant core:data-analyst

Attach Skills via API

curl -X PATCH "https://cc.teamday.ai/api/v1/agents/<agent-id>" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "skillIds": ["core:research-assistant"]
  }'

Chat With Your Agent

Agents can be chatted with at two levels:

Organization-Level Chat

From the org home page, select an agent and start chatting. The agent uses only its own equipment — skills, MCPs, and subagents attached directly to it. No Space context.

Space-Level Chat

Open a Space, select the agent, and chat. The agent uses its own equipment plus the Space’s installed resources. This is the union of both — the agent’s skills plus the Space’s skills, the agent’s MCPs plus the Space’s MCPs.

Interactive Chat (CLI)

teamday agents chat <agent-id>

Multi-turn conversation with streaming responses. Type exit to quit.

Single Message (CLI)

teamday agents exec <agent-id> "What are the top SEO trends this year?"

Execute in a Space

Give the agent access to files and tools by specifying a Space:

teamday agents exec <agent-id> "Review the code in src/" --space <space-id>

Via API

curl -X POST "https://cc.teamday.ai/api/v1/agents/<agent-id>/execute" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What are the top SEO trends this year?",
    "spaceId": "optional-space-id"
  }'

Response:

{
  "success": true,
  "executionId": "exec-abc123",
  "chatId": "agent-def456-1709123456000",
  "sessionId": "session-1709123456000",
  "result": "Here are the top SEO trends..."
}

Session Continuity

Continue a conversation by passing sessionId or chatId:

curl -X POST "https://cc.teamday.ai/api/v1/agents/<agent-id>/execute" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Can you elaborate on the first point?",
    "sessionId": "session-1709123456000"
  }'

Add to a Space

Agents are created independently, then added to Spaces. This is a two-step process:

# Step 1: Create the agent (already done above)
# Step 2: Add it to a space
teamday spaces add-agent <space-id> <agent-id>

Via API:

curl -X PATCH "https://cc.teamday.ai/api/v1/spaces/<space-id>" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "addAgents": ["<agent-id>"]
  }'

Once added to a Space, the agent can access the Space’s files, installed MCPs, skills, and secrets — in addition to its own equipment.

Writing a Good System Prompt

The system prompt is the most important part of your agent. It defines personality, capabilities, and behavior.

Structure

A good system prompt has three parts:

You are [Name], a [role] who [core capability].

[Behavioral guidelines — how to respond, what tone to use, what to prioritize]

[Constraints — what NOT to do, boundaries, safety rules]

Example: SEO Analyst

You are Sarah, an SEO analyst who helps businesses improve their search rankings.

When analyzing a website:
1. Check current organic keyword rankings
2. Identify quick wins (keywords ranking positions 4-20)
3. Analyze competitor gaps
4. Provide specific, actionable recommendations

Always cite data sources. Use tables for comparisons. Be direct — lead with the most impactful findings.

Do not make promises about specific ranking improvements. Always note that SEO results take time.

Example: Code Reviewer

You are a senior code reviewer. Review code for quality, security, and maintainability.

For each file:
- Check for security vulnerabilities (injection, XSS, auth issues)
- Identify performance bottlenecks
- Flag code style inconsistencies
- Suggest specific improvements with code examples

Be constructive, not critical. Explain WHY something should change, not just WHAT.

See Prompts & Instructions for more advanced prompt engineering techniques.

Agent Optional Fields

When creating agents via the API, you can include additional metadata for discoverability and marketing pages.

Additional Configuration

{
  "category": "marketing",
  "longDescription": "Sarah is an SEO specialist who helps businesses improve their organic search rankings...",
  "useCases": [
    "Website SEO audits",
    "Keyword research and analysis",
    "Competitor gap analysis",
    "Content optimization recommendations"
  ],
  "faq": [
    {
      "question": "What tools does Sarah use?",
      "answer": "Sarah uses Ahrefs for backlink analysis and keyword research, Google Search Console for performance data, and web scraping for competitor analysis."
    }
  ],
  "integrations": ["ahrefs", "google-analytics"],
  "seo": {
    "title": "Sarah - AI SEO Analyst",
    "description": "AI-powered SEO analysis and recommendations",
    "keywords": ["seo", "keyword research", "site audit"]
  }
}

Available categories: marketing, finance, hr, engineering, operations, general, data.

Visibility Levels

Level	Description
`private`	Only you can see and use
`organization`	All team members in your org can see and use
`public`	Listed on the TeamDay marketplace at `/team/{slug}`
`unlisted`	Accessible via direct link but not listed

Visibility controls who can discover the agent. It does not control where the agent is active — for that, the agent must be explicitly attached to a Space.

Update Your Agent

Via CLI

teamday agents update <agent-id> \
  --name "Sarah v2" \
  --system-prompt "Updated instructions..."

Via API

curl -X PATCH "https://cc.teamday.ai/api/v1/agents/<agent-id>" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sarah v2",
    "systemPrompt": "Updated instructions..."
  }'

Only fields you include in the request are updated — everything else stays the same.

Next Steps

Guide	What You’ll Learn
Agent Configuration	Advanced settings, models, and capabilities
Skills	Build custom skills for your agents
MCP Servers	Connect agents to external tools
Spaces & Workspaces	Configure workspaces with files and secrets
Missions	Schedule agents to run automatically