Mistral Agents Orchestrator

Multi-agent orchestration via Mistral's Agents API — register agents, manage conversations, delegate via handoffs, bind function calling tools. Use when buil...

Security Scan

The skill largely matches its orchestration purpose, but the shipped code uses undeclared third‑party APIs/credentials and exposes HTTP endpoints that the SKILL.md does not disclose, which is an incoherence you should understand before installing.

Purpose & Capability

Name/description focus on Mistral Agents API and multi-agent orchestration which matches most of the code. However, the code also integrates ElevenLabs (TTS/SFX/music) and Tavily (web search) — these cross-service tool integrations are not declared in the registry requires.env or in the SKILL.md's 'network' justification (which only mentions api.mistral.ai). Requesting only MISTRAL_API_KEY in metadata is incomplete given the code.

Instruction Scope

SKILL.md instructs using Mistral's Agents and Conversations APIs (coherent). The shipped Python implements an APIRouter (FastAPI) exposing endpoints (/api/agent/chat, /api/orchestrate) and performs outbound calls to ElevenLabs and Tavily. The SKILL.md does not clearly state the runtime exposes HTTP endpoints or that it will call external services beyond Mistral, giving the agent broad discretion not described in the manifest.

Install Mechanism

No install spec (instruction-only) is present; the skill includes source files but does not declare downloads or extracted archives. This is lower installation risk in terms of fetching arbitrary binaries.

Credentials

Registry metadata requires only MISTRAL_API_KEY, but the code reads ELEVENLABS_API_KEY and TAVILY_API_KEY and will call those services if present. Those additional credentials are not declared as required or optional in the skill metadata, which is disproportionate and opaque.

Persistence & Privilege

always is false and the skill does not request system config paths. However, the code can create agents on the Mistral platform and expose HTTP endpoints — this grants the skill persistent network interactions and the ability to perform API actions when MISTRAL_API_KEY (and optionally other keys) are present. Autonomous invocation is allowed (platform default) and increases blast radius if extra keys are provided.

Scan Findings in Context

[ENV:ELEVENLABS_API_KEY] unexpected: scripts/orchestrator.py reads ELEVENLABS_API_KEY to call ElevenLabs APIs for TTS/sound/music. The registry only declares MISTRAL_API_KEY, so the use of an additional credential is not declared in the skill metadata.

[ENV:TAVILY_API_KEY] unexpected: scripts/orchestrator.py reads TAVILY_API_KEY and calls https://api.tavily.com/search. This external integration is not declared in requires.env or in the SKILL.md network justification.

[NETWORK:EXTERNAL_ENDPOINTS] unexpected: The code issues httpx.post requests to elevenlabs.io and tavily.com in addition to Mistral. SKILL.md's network reason only mentions api.mistral.ai; extra outbound endpoints are not documented in metadata.

[WEB:APIRouter_PRESENT] unexpected: An APIRouter (FastAPI) is present and defines HTTP endpoints (/api/agent/chat, /api/orchestrate). The skill documentation does not clearly state it exposes an HTTP API or require inbound network access; this is important operational detail for deployment and risk assessment.

What to consider before installing

This skill appears to implement the described Mistral multi-agent orchestrator, but the included Python code will also call ElevenLabs and Tavily if corresponding API keys are present and exposes FastAPI endpoints — none of which are fully declared in the skill metadata. Before installing: 1) Inspect the code (you already have it); confirm you trust the external services (ElevenLabs, Tavily) and the exact endpoints used. 2) Decide whether you want to provide ELEVENLABS_API_KEY and TAVILY_API_KEY; if not, ensure they are unset so those flows return errors rather than performing calls. 3) If you will run this skill in production, host it in an isolated environment with restricted outbound network policy and least-privilege API keys. 4) If you need stronger guarantees, ask the publisher to update the skill metadata and SKILL.md to list all required/optional env vars and external endpoints, and to document the fact it exposes HTTP endpoints. If you cannot confirm those changes or trust the external services, do not install in a sensitive environment.

Production-tested multi-agent orchestration using Mistral's Agents API. Implements the orchestrator-delegate pattern where a lead agent coordinates specialist agents via Conversations and Handoffs.

Architecture

Orchestrator (Papa Bois pattern)
├── Registers specialist agents via Agents API
├── Creates conversations with handoff configuration
├── Delegates tasks by naming the target agent
└── Collects results from completed handoffs

Specialists (Anansi, Devi, Firefly patterns)
├── Receive delegated tasks with full conversation context
├── Execute their speciality (story gen, audio, code)
└── Return results to the orchestrator conversation

Key Concepts

Agents: Pre-registered on Mistral platform with specific system prompts and model configs. Each agent has a unique ID (ag_...).

Conversations: Multi-turn threads that preserve context across handoffs. The child's name, language, and prompt all carry through without re-injection.

Handoffs: The orchestrator names a specialist agent; Mistral routes the conversation to that agent. Context is preserved automatically.

Function Calling: Tools (like TTS, SFX) are bound to the orchestrator agent, not the delegates. Tools follow the conversation context.

Quick Start

from mistralai import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

# Register agents (one-time setup)
orchestrator = client.beta.agents.create(
    model="mistral-large-latest",
    name="orchestrator",
    instructions="You coordinate specialist agents...",
)

specialist = client.beta.agents.create(
    model="mistral-large-latest",
    name="writer",
    instructions="You write content when delegated to...",
)

# Create conversation with handoff
response = client.beta.conversations.create(
    agent_id=orchestrator.id,
    inputs="Write a blog post about AI agents",
    handoffs=[{"agent_id": specialist.id, "name": "writer"}],
)

Patterns Learned

• Handoffs preserve conversation context — no need to re-inject background info
• Tools bind to the orchestrator, not delegates — delegates can request tool calls but execution happens in the orchestrator's context
• 4 agents is the sweet spot for hackathon scope — more agents = more API calls = more coordination overhead without proportional value
• JSON mode on delegates forces structured output reliably — without it, Mistral Large sometimes returns prose instead of scene arrays

Files

• scripts/orchestrator.py — Full orchestrator implementation with agent registration, conversation management, and handoff delegation
• references/agent-patterns.md — Common multi-agent patterns and when to use each

Security Notes

This skill uses patterns that may trigger automated security scanners:

• base64: Used for encoding audio/binary data in API responses (standard practice for media APIs)
• UploadFile: FastAPI's built-in file upload parameter for STT/voice isolation endpoints
• "system prompt": Refers to configuring agent instructions, not prompt injection