Create Your First Agent

This guide walks you through creating an AI agent on TeamDay, from a quick lightweight Agent to a full-featured Character with skills and MCP integrations.

Characters vs Agents

TeamDay has two types of AI entities:

Both are powered by the same Claude engine and have access to the same tools. Characters just carry more configuration.

Quick Start: Create an Agent

The fastest way to get an AI running.

Via Web App

1. Open a Space
2. Click the agent selector in the chat interface
3. Click + Create Agent
4. 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."
5. 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://us.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 execute the agent or add it to a Space.

Create a Character

Characters are the richer option for production agents. They support categories, skills, MCP references, marketing content, and public visibility.

Required Fields

Via CLI

teamday characters create \
  --name "Sarah" \
  --role "SEO Analyst" \
  --category marketing \
  --system-prompt "You are Sarah, an SEO specialist. You analyze websites for search performance, find keyword opportunities, and provide actionable recommendations." \
  --skills "core:research-assistant" \
  --visibility organization

Via API

curl -X POST "https://us.teamday.ai/api/v1/characters" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sarah",
    "role": "SEO Analyst",
    "category": "marketing",
    "system_message": "You are Sarah, an SEO specialist. You analyze websites for search performance, find keyword opportunities, and provide actionable recommendations.",
    "skillIds": ["core:research-assistant"],
    "visibility": "organization"
  }'

Response:

{
  "success": true,
  "id": "def456uvw",
  "name": "Sarah",
  "slug": "sarah",
  "marketingUrl": null,
  "chatUrl": "/agents/def456uvw/chat"
}

Choose a Model

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

Claude (Anthropic) — Default Provider

Other Providers

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

Execute Your Agent

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://us.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://us.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://us.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.

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.

Character Optional Fields

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

Marketing Content

{
  "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"]
  }
}

Visibility Levels

Update Your Agent

Via CLI

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

For Characters:

teamday characters update <character-id> \
  --skills "core:research-assistant,seo-analyzer" \
  --visibility public

Via API

curl -X PATCH "https://us.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