Exécuter un agent dans votre processus

Une session locale s'exécute dans votre programme Python : le SDK exécute la boucle de l'agent, vos outils et gère l'historique de la session dans votre processus. Une session locale dure aussi longtemps que votre programme : exécutez-la, poursuivez-la et annulez-la lorsque vous n'en avez plus besoin. Pour la conserver après la fin du programme, enregistrez-la dans un fichier (fonctionnalité expérimentale).

Pour commencer, le SDK doit être installé et MISTRAL_API_KEY doit être définie.

Construire l'agent, puis l'exécuter. model est le seul argument requis de agents.Agent(...) : consultez Configurer l'agent pour connaître tous les arguments et leurs valeurs par défaut. agent.run() répond à un seul message ; une session conserve la conversation d'un message à l'autre :

import asyncio

from mistralai import agents

agent = agents.Agent(
    model="mistral-large-4",
    name="trip-planner",
    instructions="Answer in one short sentence.",
)


async def main() -> None:
    state = await agent.run("Name one museum in Lisbon.")
    print(state.text)

    session = await agent.start_session()
    await session.run("My name is Ada.")
    state = await session.run("What is my name?")
    if isinstance(state, agents.Completed):
        print(state.text)
    await session.cancel()  # ends the session


if __name__ == "__main__":
    asyncio.run(main())

import asyncio

from mistralai import agents

agent = agents.Agent(
    model="mistral-large-4",
    name="trip-planner",
    instructions="Answer in one short sentence.",
)


async def main() -> None:
    state = await agent.run("Name one museum in Lisbon.")
    print(state.text)

    session = await agent.start_session()
    await session.run("My name is Ada.")
    state = await session.run("What is my name?")
    if isinstance(state, agents.Completed):
        print(state.text)
    await session.cancel()  # ends the session


if __name__ == "__main__":
    asyncio.run(main())

The Calouste Gulbenkian Museum is one of Lisbon's most famous museums.
Your name is Ada.

The Calouste Gulbenkian Museum is one of Lisbon's most famous museums.
Your name is Ada.

Vous pouvez l'exécuter de deux façons :

• Sous forme de script : uv run python main.py exécute main(), qui envoie les messages à l'agent depuis le code.
• En mode interactif : uv run agents chat, exécuté depuis le répertoire de main.py, charge le même agent et vous permet de saisir chaque message dans votre terminal. Cette commande importe main.py ; la ligne if __name__ == "__main__": empêche donc l'exécution de main() lors de l'import.

agent.run() répond aux demandes d'approbation uniquement via un gestionnaire d'approbation, transmis avec on_approval=. Sans ce gestionnaire, un appel d'outil nécessitant une approbation fait renvoyer agents.Blocked à l'exécution. Le tour attend alors une réponse via un handle de session, jusqu'à l'expiration du délai d'approbation, fixé à 1 heure par défaut. Ensuite, le modèle reçoit un résultat d'expiration du délai lui indiquant de ne pas réessayer l'appel immédiatement, et le tour se poursuit.

Pour poursuivre la conversation, utilisez une session. La session démarrée par agent.run() se ferme une fois son tour terminé, et vous pouvez alors uniquement la lire. Pour poursuivre après un agent.run(), exécutez-le dans un bloc async with agents.local_runtime(), puis ouvrez-y sa session à partir de son identifiant :

# Inside main() of the script above.
async with agents.local_runtime():
    state = await agent.run("Name three hotels in Lisbon, on one line.")
    print(state.text)
    session = agent.session(state.session_id)
    state = await session.run("Which of them is usually the cheapest?")
    if isinstance(state, agents.Completed):
        print(state.text)
    await session.cancel()

# Inside main() of the script above.
async with agents.local_runtime():
    state = await agent.run("Name three hotels in Lisbon, on one line.")
    print(state.text)
    session = agent.session(state.session_id)
    state = await session.run("Which of them is usually the cheapest?")
    if isinstance(state, agents.Completed):
        print(state.text)
    await session.cancel()

Hotel Avenida Palace, Pestana Palace Lisbon, and Four Seasons Hotel Ritz Lisbon.
Pestana Palace Lisbon is usually the cheapest of the three, though rates vary by season.

Hotel Avenida Palace, Pestana Palace Lisbon, and Four Seasons Hotel Ritz Lisbon.
Pestana Palace Lisbon is usually the cheapest of the three, though rates vary by season.

Par défaut, les sessions locales restent en mémoire et se terminent avec votre processus. Pour les conserver sur disque, utilisez le journal expérimental JsonFileSessionJournal.

Une session locale se termine lorsque vous l'annulez, lorsque son tour agent.run() se termine, lorsqu'un bloc local_runtime() se termine ou lorsque sa boucle d'événements s'arrête :

Dans cet exemple, l'exécution renvoie un résultat après une seconde, alors que le tour continue de s'exécuter, et session.cancel() l'arrête :

# Inside main() of the script above.
state = await agent.run("Write a 2,000-word story about a lighthouse.", timeout=1)
print(type(state).__name__)
await agent.session(state.session_id).cancel()  # stops the turn and ends the session

# Inside main() of the script above.
state = await agent.run("Write a 2,000-word story about a lighthouse.", timeout=1)
print(type(state).__name__)
await agent.session(state.session_id).cancel()  # stops the turn and ends the session

Running

Running

Une commande sur une session terminée lève agents.SessionTerminatedError :

SessionTerminatedError: The local Session has ended

SessionTerminatedError: The local Session has ended

Annulez chaque session lorsque vous n'en avez plus besoin. Si une session est encore ouverte à l'arrêt de la boucle d'événements, le SDK consigne l'avertissement agents_sdk_local_runtime_closed_open_sessions, avec les identifiants des sessions.

Une session terminée reste en mémoire jusqu'à l'arrêt de la boucle d'événements ; vous pouvez donc encore lire ses tours. La consommation mémoire d'un serveur qui exécute de nombreuses sessions sur une même boucle d'événements augmente à chaque session.

Chaque boucle d'événements possède un environnement d'exécution local : la partie du SDK qui exécute les sessions locales de cette boucle et leurs sous-agents. agent.run(), agent.start_session() et agent.session(id) l'utilisent tous. Deux appels à asyncio.run dans un même script ont deux environnements d'exécution et ne partagent pas leurs sessions.

agents.local_runtime() renvoie l'environnement d'exécution local de la boucle d'événements. Le récupérer ne démarre rien. Utilisez-le comme bloc async with pour arrêter toutes les opérations locales de la boucle d'événements à la fin du bloc :

# Inside main() of the script above.
async with agents.local_runtime():
    session = await agent.start_session()
    await session.start_turn("Plan a weekend in Lisbon.")
# Every local session of this event loop has stopped: running turns, subagents and sandboxes.

# Inside main() of the script above.
async with agents.local_runtime():
    session = await agent.start_session()
    await session.start_turn("Plan a weekend in Lisbon.")
# Every local session of this event loop has stopped: running turns, subagents and sandboxes.

La fin du bloc arrête aussi les sessions démarrées avant le bloc, ainsi que les tours et sous-agents laissés actifs par une exécution dont vous avez cessé d'attendre le résultat. Si les blocs sont imbriqués, seule la fin du bloc le plus externe arrête les sessions.

À la fin du bloc, toutes les sessions locales qu'il a exécutées se terminent et sont libérées. Ensuite, une lecture ou une commande sur l'une d'elles, comme turn.get() ou session.send_message(...), lève agents.SessionTerminatedError, et session.cancel() se termine. Pour poursuivre, démarrez une nouvelle session. Une session enregistrée avec le journal expérimental est seulement déchargée et peut être rouverte.

Le modèle peut appeler vos outils depuis un programme : du code TypeScript qu'il écrit et exécute avec l'outil run_typescript. Chaque programme dispose de 60 secondes. Cette limite s'applique à l'ensemble du programme, et non à chaque appel d'outil. Un appel d'outil en cours se termine toujours, mais une fois le temps alloué épuisé, le programme s'arrête avant l'étape suivante et le modèle reçoit une erreur ProgramBudgetExceeded. Le temps passé à attendre une approbation ou un hook n'est pas comptabilisé.

Si un programme qui appelle vos outils peut prendre plus de 60 secondes, augmentez le temps alloué pour toutes les sessions locales de la boucle d'événements :

# Wrap the body of main() in the block, before any other local session.
async with agents.local_runtime(program_timeout_seconds=300):
    await agent.run("Build the report")

# Wrap the body of main() in the block, before any other local session.
async with agents.local_runtime(program_timeout_seconds=300):
    await agent.run("Build the report")

Le temps alloué est fixé au démarrage de l'environnement d'exécution. Ouvrez donc le bloc avant la première session locale de la boucle d'événements et exécutez vos sessions à l'intérieur.

• SessionTerminatedError: The local Session has ended. La session a été annulée, ou un bloc async with agents.local_runtime() dans lequel elle s'exécutait s'est terminé. Démarrez une nouvelle session.
• SdkError: This event loop's local runtime already runs with .... Une session locale a démarré l'environnement d'exécution avant le bloc. Ouvrez d'abord le bloc, au début de main().
• L'avertissement agents_sdk_local_runtime_closed_open_sessions. Des sessions étaient encore ouvertes lorsque la boucle d'événements s'est arrêtée. Appelez await session.cancel() sur chacune d'elles lorsque vous n'en avez plus besoin.

• Cycle de vie et liste des sessions : listez les sessions locales de la boucle d'événements.
• Auto-hébergés : agents serve : déployez le même agent sur votre propre infrastructure pour que ses sessions persistent après la fin de votre processus.