API Agents

Les agents sont des assistants IA personnalisables qui peuvent effectuer des tâches, analyser des données et automatiser des workflows. Utilisez l’API Agents pour créer et gérer des agents de manière programmatique pour votre organisation.

URL de base : https://us.teamday.ai/api/v1/agents

Authentification : Jeton d’accès personnel requis

Aperçu des endpoints

Méthode	Endpoint	Description	Statut
GET	`/agents`	Lister tous les agents	✅ Fonctionnel
POST	`/agents`	Créer un nouvel agent	✅ Fonctionnel
GET	`/agents/[id]`	Obtenir les détails d’un agent	✅ Fonctionnel
PATCH	`/agents/[id]`	Mettre à jour un agent	✅ Fonctionnel
DELETE	`/agents/[id]`	Supprimer un agent	✅ Fonctionnel
POST	`/agents/[id]/execute`	Exécuter un agent	🔴 En panne (erreur 500)

Résultats des tests : 5/6 endpoints opérationnels (83%)

Objet Agent

Propriétés

{
  id: string              // ID de l'agent (format: agent_xxx)
  name: string            // Nom d'affichage
  role: string            // Rôle/objectif de l'agent
  systemPrompt: string    // Instructions système
  visibility: string      // "private" | "organization" | "public"
  organizationId: string  // Organisation propriétaire
  userId: string          // ID de l'utilisateur créateur
  createdAt: string       // Horodatage ISO 8601
  updatedAt: string       // Horodatage ISO 8601
  deletedAt?: string      // Horodatage de suppression logique (si supprimé)
}

Exemple d’objet

{
  "id": "agent_abc123",
  "name": "Assistant de Recherche",
  "role": "Recherche et analyse de données",
  "systemPrompt": "Vous êtes un assistant de recherche spécialisé dans l'analyse et la synthèse de données.",
  "visibility": "private",
  "organizationId": "org_xyz789",
  "userId": "user_456",
  "createdAt": "2025-12-09T10:30:00Z",
  "updatedAt": "2025-12-09T10:30:00Z"
}

Lister les Agents

Récupérer tous les agents de votre organisation.

Requête

GET /api/v1/agents

En-têtes :

Authorization: Bearer td_xxxxx...

Paramètres de requête : Aucun

Réponse

Succès (200 OK) :

[
  {
    "id": "agent_abc123",
    "name": "Assistant de Recherche",
    "role": "Recherche et analyse",
    "systemPrompt": "Vous êtes un assistant de recherche.",
    "visibility": "private",
    "organizationId": "org_xyz789",
    "userId": "user_456",
    "createdAt": "2025-12-09T10:30:00Z",
    "updatedAt": "2025-12-09T10:30:00Z"
  },
  {
    "id": "agent_def456",
    "name": "Réviseur de Code",
    "role": "Révision de code et suggestions",
    "systemPrompt": "Vous êtes un expert en révision de code.",
    "visibility": "organization",
    "organizationId": "org_xyz789",
    "userId": "user_789",
    "createdAt": "2025-12-08T15:20:00Z",
    "updatedAt": "2025-12-09T09:15:00Z"
  }
]

Résultat vide :

[]

Erreur (401 Non autorisé) :

{
  "error": true,
  "statusCode": 401,
  "statusMessage": "Unauthorized",
  "message": "Jeton invalide ou expiré"
}

Exemple

curl https://us.teamday.ai/api/v1/agents \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

Créer un Agent

Créer un nouvel agent IA pour votre organisation.

Requête

POST /api/v1/agents

En-têtes :

Authorization: Bearer td_xxxxx...
Content-Type: application/json

Corps :

{
  "name": "Assistant de Recherche",
  "role": "Recherche et analyse de données",
  "systemPrompt": "Vous êtes un assistant de recherche spécialisé dans l'analyse et la synthèse de données.",
  "visibility": "private"
}

Champs requis :

name (string) - Nom d’affichage de l’agent
systemPrompt (string) - Instructions système pour l’agent

Champs optionnels :

role (string) - Description du rôle de l’agent (par défaut : chaîne vide)
visibility (string) - Niveau d’accès : "private", "organization", ou "public" (par défaut : "private")

Réponse

Succès (201 Created) :

{
  "id": "agent_abc123",
  "name": "Assistant de Recherche",
  "role": "Recherche et analyse de données",
  "systemPrompt": "Vous êtes un assistant de recherche spécialisé dans l'analyse et la synthèse de données.",
  "visibility": "private",
  "organizationId": "org_xyz789",
  "userId": "user_456",
  "createdAt": "2025-12-09T10:30:00Z",
  "updatedAt": "2025-12-09T10:30:00Z"
}

Erreur (400 Mauvaise requête) :

{
  "error": true,
  "statusCode": 400,
  "statusMessage": "Bad Request",
  "message": "Champ requis manquant : name"
}

Exemple

curl -X POST https://us.teamday.ai/api/v1/agents \
  -H "Authorization: Bearer $TEAMDAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Assistant de Recherche",
    "role": "Recherche et analyse de données",
    "systemPrompt": "Vous êtes un assistant de recherche spécialisé dans l'\''analyse et la synthèse de données.",
    "visibility": "private"
  }'

Obtenir un Agent

Récupérer les détails d’un agent spécifique par ID.

Requête

GET /api/v1/agents/[id]

En-têtes :

Authorization: Bearer td_xxxxx...

Paramètres de chemin :

id (string) - ID de l’agent (format : agent_xxx)

Réponse

Succès (200 OK) :

{
  "id": "agent_abc123",
  "name": "Assistant de Recherche",
  "role": "Recherche et analyse de données",
  "systemPrompt": "Vous êtes un assistant de recherche spécialisé dans l'analyse et la synthèse de données.",
  "visibility": "private",
  "organizationId": "org_xyz789",
  "userId": "user_456",
  "createdAt": "2025-12-09T10:30:00Z",
  "updatedAt": "2025-12-09T10:30:00Z"
}

Erreur (404 Non trouvé) :

{
  "error": true,
  "statusCode": 404,
  "statusMessage": "Not Found",
  "message": "Agent non trouvé"
}

Exemple

curl https://us.teamday.ai/api/v1/agents/agent_abc123 \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

Mettre à jour un Agent

Mettre à jour les propriétés d’un agent existant.

Requête

PATCH /api/v1/agents/[id]

En-têtes :

Authorization: Bearer td_xxxxx...
Content-Type: application/json

Paramètres de chemin :

id (string) - ID de l’agent (format : agent_xxx)

Corps (tous les champs sont optionnels) :

{
  "name": "Assistant de Recherche Amélioré",
  "role": "Recherche et analyse avancées",
  "systemPrompt": "Vous êtes un assistant de recherche expert avec une connaissance approfondie de l'analyse de données.",
  "visibility": "organization"
}

Champs modifiables :

name (string) - Nom d’affichage de l’agent
role (string) - Description du rôle de l’agent
systemPrompt (string) - Instructions système
visibility (string) - Niveau d’accès : "private", "organization", ou "public"

Remarque : Incluez uniquement les champs que vous souhaitez mettre à jour. Les champs omis restent inchangés.

Réponse

Succès (200 OK) :

{
  "id": "agent_abc123",
  "name": "Assistant de Recherche Amélioré",
  "role": "Recherche et analyse avancées",
  "systemPrompt": "Vous êtes un assistant de recherche expert avec une connaissance approfondie de l'analyse de données.",
  "visibility": "organization",
  "organizationId": "org_xyz789",
  "userId": "user_456",
  "createdAt": "2025-12-09T10:30:00Z",
  "updatedAt": "2025-12-09T14:45:00Z"
}

Exemple

curl -X PATCH https://us.teamday.ai/api/v1/agents/agent_abc123 \
  -H "Authorization: Bearer $TEAMDAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Assistant de Recherche Amélioré",
    "visibility": "organization"
  }'

Supprimer un Agent

Suppression logique d’un agent. L’agent est marqué comme supprimé mais n’est pas définitivement retiré de la base de données.

Requête

DELETE /api/v1/agents/[id]

En-têtes :

Authorization: Bearer td_xxxxx...

Paramètres de chemin :

id (string) - ID de l’agent (format : agent_xxx)

Réponse

Succès (200 OK) :

{
  "success": true,
  "message": "Agent supprimé avec succès"
}

Exemple

curl -X DELETE https://us.teamday.ai/api/v1/agents/agent_abc123 \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

Remarques

Comportement de suppression logique :

L’agent est marqué avec un horodatage deletedAt
L’agent n’apparaît plus dans les résultats de liste
L’agent ne peut être ni récupéré ni mis à jour
L’historique d’exécution est préservé
Ne peut pas être restauré via l’API (contactez le support pour restaurer)

Exécuter un Agent (Actuellement indisponible)

Statut : 🔴 EN PANNE - Erreur interne du serveur 500

Exécuter un agent avec un message et recevoir une réponse.

Problème connu

Comportement actuel :

curl -X POST https://us.teamday.ai/api/v1/agents/agent_abc123/execute \
  -H "Authorization: Bearer $TEAMDAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "bonjour",
    "stream": false
  }'

Réponse :

{
  "error": true,
  "statusCode": 500,
  "statusMessage": "Internal Server Error",
  "message": "Échec de l'exécution du chat"
}

Cause principale : Le endpoint interne /api/claude-code/chat renvoie des erreurs 500.

Solution de contournement : Utilisez l’interface web sur us.teamday.ai pour l’exécution d’agents jusqu’à résolution.

Niveaux de visibilité

Les agents prennent en charge trois niveaux de visibilité :

Privé

Niveau : "private"

Accès :

Visible uniquement par le créateur
Seul le créateur peut exécuter
Non visible dans la liste des agents de l’organisation

Cas d’usage :

Assistants personnels
Agents expérimentaux
Workflows sensibles

Organisation

Niveau : "organization"

Accès :

Visible par tous les membres de l’organisation
Tous les membres peuvent exécuter
Apparaît dans les agents partagés de l’organisation

Cas d’usage :

Collaboration d’équipe
Bases de connaissances partagées
Outils à l’échelle de l’entreprise

Public (Futur)

Niveau : "public"

Accès :

Visible par tout le monde (fonctionnalité future)
N’importe qui peut exécuter (fonctionnalité future)
Listé dans le marketplace public d’agents (fonctionnalité future)

Statut : Pas encore implémenté. Actuellement traité comme organization.

Meilleures pratiques

Conception d’agents

Prompts système :

Soyez précis sur le rôle et les capacités de l’agent
Incluez des exemples du comportement souhaité
Définissez des limites claires sur ce que l’agent devrait/ne devrait pas faire
Gardez les prompts sous 2000 caractères pour des performances optimales

Conventions de nommage

Noms d’agents :

Utilisez des noms descriptifs et orientés action
Incluez la spécialité ou le domaine de l’agent
Restez sous 50 caractères

Bons exemples :

“Réviseur de Code Python”
“Assistant Support Client”
“Agent d’Analyse de Données”

Sécurité

Visibilité :

Par défaut sur "private" pour les nouveaux agents
Utilisez "organization" uniquement pour les agents validés par l’équipe
Vérifiez les prompts système avant de rendre les agents accessibles à l’organisation

Données sensibles :

N’incluez pas de clés API ou d’identifiants dans les prompts système
Utilisez plutôt la [gestion des secrets de TeamDay
Les agents héritent des permissions utilisateur - délimitez les jetons de manière appropriée

Ressources associées

Authentification - Configuration et sécurité du jeton PAT
API Executions - Suivre l’historique d’exécution des agents
API Tasks - Gérer les tâches et workflows des agents
Référence des erreurs - Documentation complète des codes d’erreur

Besoin d’aide ?

Problèmes avec les agents ?

Consultez la référence des erreurs pour le dépannage
Vérifiez que le jeton a les bonnes permissions
Testez d’abord avec un agent simple

Questions ?

📧 Email : support at teamday.ai
💬 Discord : Rejoindre la communauté
🐛 Signaler des bugs : GitHub Issues

Dernière mise à jour : 9 décembre 2025