Scriptling Scriptling

scriptling.ai.agent.interact

Interactive terminal interface for AI agents. This library exports Agent, a subclass of scriptling.ai.agent.Agent that adds an interact() method providing a REPL-like interface for conversing with AI agents using the TUI console.

Availability

CLI registration is mode-dependent: the ordinary non-server CLI execution path adds scriptling.ai.agent.interact, while evaluator factories and server-style execution do not add it automatically. Embedders must register it explicitly, together with scriptling.console. Instances of scriptling.ai.agent.Agent do not have interact(), even after this library is imported: create the agent with interact.Agent(...).

Available Functions

Function Description
Agent(...) Subclass of scriptling.ai.agent.Agent; same constructor arguments
agent.interact(max_iterations=25) Method on interact.Agent: starts an interactive TUI session

The module exports only the Agent subclass; it has no standalone module-level functions.

Overview

interact.Agent behaves exactly like scriptling.ai.agent.Agent (including trigger()), plus an interact() method. When interact() is called it uses the shared console singleton, registers commands and handlers, then calls console.run() to start the TUI event loop.

During each turn, the interactive loop:

  • Streams reasoning and assistant text into the main panel as it arrives.
  • Keeps the spinner running until the turn is fully complete.
  • Shows tool call and result messages with status and preview.
  • Uses ai.collect_stream() for streaming with configurable timeouts.
  • Preserves conversation state for follow-up requests.

Functions

agent.interact(max_iterations=25)

Runs an interactive CLI session for the agent. Requires scriptling.console to be registered, and is designed for use with the scriptling CLI.

Parameters:

  • max_iterations (int, optional): Maximum number of tool call rounds per user message. Prevents infinite loops if the agent gets stuck. Default: 25.

Returns: None

import scriptling.ai as ai
import scriptling.ai.agent.interact as interact

client = ai.Client("https://api.openai.com/v1", api_key="your-key")

my_agent = interact.Agent(
    client=client,
    model="gpt-4",
    system_prompt="You are a helpful assistant."
)

# Start interactive session
my_agent.interact()

# Custom limit for complex tasks
my_agent.interact(max_iterations=50)

When the iteration limit is reached, a message is displayed:

[Reached max iterations (25). Type 'continue' or ask me to proceed.]

You can then type “continue” or ask the agent to proceed, and it will continue from where it left off.

Pre-configuring the Console

You can set up the console before calling interact() using module-level functions from scriptling.console:

import scriptling.console as console
import scriptling.ai.agent.interact as interact

console.set_status("MyApp", "v1.0")
main = console.main_panel()
main.add_message(
    console.styled(console.PRIMARY, "MyApp") + ": type your requests.\n" +
    console.styled(console.DIM, "Type '/exit' to quit.")
)

bot = interact.Agent(client, model="gpt-4o", system_prompt="You are helpful.")
bot.interact()

The console is a singleton, so any configuration applied before interact() will be preserved.

Interactive Commands

Commands are registered with the TUI palette when interact() is called. Type / to open the command palette.

Command Description
/clear Clear conversation history and screen
/model <name> Switch model (none to reset to default)
/history Show conversation history
/exit Exit (registered by the CLI)
Esc Cancel the current request

Security Considerations

This is an extended library, requiring registration in Go, see Library Registration.

scriptling.ai.agent.interact inherits the network and agentic-execution risk of scriptling.ai.agent: it streams completions from the configured AI provider and runs the same tool-calling loop, just with a terminal UI on top. Never register it for untrusted code. See Security Considerations on the ai.agent page, the Security Guide, and Library Registration.

See Also