Skip to content

Interactive Shell

The shell() function turns any agent into an interactive terminal session. Instead of hardcoding prompts in your script, you type them live and see the response immediately.

Basic usage

from exagent import shell
from myagent import WeatherAgent

shell(WeatherAgent())

exagent shell  |  gpt-4.1-mini  |  streaming
Type /help for commands, /exit or Ctrl-C to quit.

> What's the weather in Tokyo?
[tool_call] get_weather({'city': 'Tokyo'})
[tool_result:ok] get_weather → Tokyo: 22°C, partly cloudy.
The weather in Tokyo is 22°C and partly cloudy.

> What about London?
[tool_call] get_weather({'city': 'London'})
[tool_result:ok] get_weather → London: 14°C, overcast.
London is currently 14°C with overcast skies.

> /exit

The agent remembers the conversation — each message builds on what was said before.

Parameters

shell(
    agent,           # Agent or OrchestratorAgent — required
    stream=True,     # bool — stream tokens live (True) or wait for full response (False)
    prompt="> ",     # str  — the input prompt shown each turn
)

Tokens appear as they are generated. Tool calls and results are shown inline.

shell(agent)
shell(agent, stream=True)

The full response is printed at once after the model finishes.

shell(agent, stream=False)

Built-in commands

Command What it does
/help Show the list of commands
/clear Reset the conversation (system prompt is preserved)
/exit or /quit Exit the shell
Ctrl-C or Ctrl-D Also exits cleanly

/clear in detail

/clear trims chat_history back to just the system message. The agent's tools, model, and skills are unchanged — only the conversation is forgotten.

> My name is Alice.
Got it, Alice!

> /clear
Conversation cleared.

> What is my name?
I don't have any information about your name.

With an orchestrator

Pass an OrchestratorAgent to shell() and the routing is visible in real time:

from exagent import shell
from myorchestrator import MyOrchestrator

shell(MyOrchestrator())

exagent shell  |  gpt-4.1-mini  |  streaming
Type /help for commands, /exit or Ctrl-C to quit.

> What is 2847 * 193?
[delegate] → calculator({'task': '2847 * 193'})
[result:ok] calculator → 549471
The result of 2847 × 193 is 549,471.

> How many words are in that last sentence?
[delegate] → text_processor({'task': 'The result of 2847 × 193 is 549,471.'})
[result:ok] text_processor → 8 words
That sentence contains 8 words.

The shell automatically uses [delegate] and [result] labels for orchestrators to make the routing clear.

Putting it all together

A complete script that launches directly into an interactive session:

from pathlib import Path
from exagent import Agent, tool, shell

@tool
def get_weather(city: str) -> str:
    """Return the current weather for a city."""
    return f"{city}: 22°C, partly cloudy."

class WeatherAgent(Agent):
    def __init__(self):
        self.system_description = (
            "You are a friendly weather assistant. "
            "Use get_weather to look up conditions for any city."
        )
        self.set_model("openai", "gpt-4.1-mini")
        self.add_tool(get_weather)
        super().__init__()

if __name__ == "__main__":
    shell(WeatherAgent())

Run it:

python weather_agent.py

Next

API Reference →