Streaming & Renderers

Control output format and streaming behavior for agent runs.

renderer controls how streaming events are displayed/logged (auto/json/markdown/plain). It does not force the model to produce JSON. For structured output, prompt for JSON or use CLI --view json to stream structured events.

🚀 Quick Start

from glaip_sdk import Client

client = Client()
agent = client.create_agent(
    name="demo-agent",
    instruction="You are a helpful AI assistant."
)

# Default streaming with auto renderer
response = agent.run("Explain quantum computing")

# Non-streaming with JSON output
response = agent.run("List 3 programming languages", stream=False, renderer="json")

# Clean up
agent.delete()

✅ Verify

Check that your renderer settings are working:

# Test different renderers
for renderer in ["auto", "json", "markdown", "plain"]:
    print(f"Testing {renderer} renderer...")
    response = agent.run("Say hello", renderer=renderer)
    print(f"Response type: {type(response)}")
    print()

🧹 Clean Up

Always clean up resources when testing:

# Delete the agent
agent.delete()

🎨 Renderer Options

Auto Renderer (Default)

The auto renderer intelligently chooses the best output format based on context.

# Auto-detect best format (default)
response = agent.run("Explain machine learning")

# Auto with rich output
response = agent.run("Solve math problem", renderer="auto")

JSON Renderer

Get structured, machine-readable output for automation and scripting.

# JSON output for parsing
response = agent.run("List 3 programming languages", renderer="json")

# Parse JSON response
import json
data = json.loads(response)
print(f"Languages: {data.get('languages', [])}")

# JSON output for parsing
response = agent.run("Analyze text", renderer="json")

Markdown Renderer

Get formatted text output suitable for documentation and rich displays.

# Markdown output
response = agent.run("Write a blog post about AI", renderer="markdown")

# Markdown output
response = agent.run("Create documentation", renderer="markdown")

Plain Renderer

Get simple text output suitable for scripts and CI/CD environments.

# Plain text output
response = agent.run("Generate a summary", renderer="plain")

# Plain text output
response = agent.run("Process data", renderer="plain")

🔄 Streaming Control

Enable Streaming (Default)

Streaming provides real-time output as the agent processes your request.

# Streaming enabled (default)
response = agent.run("Explain a complex topic")

# Explicit streaming
response = agent.run("Long analysis", stream=True)

Disable Streaming

Non-streaming mode waits for the complete response before returning.

# Non-streaming mode
response = agent.run("Quick question", stream=False)

# Non-streaming with timeout
response = agent.run("Complex task", stream=False, timeout=900)

🖥️ TTY Behavior

TTY Detection

The renderer automatically detects if you're in an interactive terminal.

# TTY-aware rendering (default)
response = agent.run("Interactive response")

# Force TTY behavior
response = agent.run("Force TTY", tty=True)  # Note: tty parameter exists in SDK but CLI only has --no-tty

# Disable TTY behavior
response = agent.run("No TTY", tty=False)

Non-TTY Environments

For CI/CD, scripts, and non-interactive environments.

# Non-TTY environment
import os
os.environ['TERM'] = 'dumb'

# Use plain renderer for scripts
response = agent.run("Script output", renderer="plain", tty=False)

📡 SSE Event Anatomy

Server-Sent Events (SSE) provide real-time updates during agent execution.

Event Types

{
  "event": "agent_step",
  "data": {
    "step_id": "step-123",
    "agent_name": "math-tutor",
    "message": "Processing mathematical problem...",
    "timestamp": "2024-01-01T00:00:00Z"
  }
}

Common Event Types

Event Type
Description
Data Fields

status

Execution status update

status, message, progress

agent_step

Agent reasoning step

step_id, agent_name, message

tool_call

Tool execution (when tools are executed)

tool_name, input, output

content

Generated content

content, type, format

done

Execution complete

result, usage, duration

Event Processing

# Process streaming events
response = agent.run("Complex task", stream=True)

# Events are automatically processed and displayed
# Rich renderer shows collapsible steps
# JSON renderer provides structured event data

🔧 Advanced Configuration

Verbose Mode

Get detailed information about agent execution steps.

# Rich output with auto renderer
response = agent.run("Explain process")

# JSON output with specific renderer
response = agent.run("Detailed analysis", renderer="json")

Custom Timeouts

Control how long to wait for responses.

# Short timeout for quick responses
response = agent.run("Quick answer", timeout=30)

# Long timeout for complex tasks
response = agent.run("Complex analysis", timeout=1800)

📊 Use Case Examples

Interactive Development

# Rich interactive output for development
response = agent.run(
    "Debug this code and explain the issue",
    renderer="auto"
)

Automation Scripts

# JSON output for automation
response = agent.run(
    "Analyze data and return structured results",
    renderer="json",
    stream=False,
    tty=False
)

# Parse structured response
import json
data = json.loads(response)
process_results(data)

CI/CD Pipelines

# Plain output for CI/CD
response = agent.run(
    "Run tests and report results",
    renderer="plain",
    stream=False,
    tty=False
)

# Simple text processing
if "PASSED" in response:
    print("✅ Tests passed")
else:
    print("❌ Tests failed")

🚨 Common Issues & Solutions

Streaming Hangs

# Problem: Output stops, no response
# Solution: Check network and use non-streaming mode
aip agents run <AGENT_ID> --input "test" --view plain --no-tty

Rich Output Issues

# Problem: Strange characters, formatting problems
# Solution: Use plain output for non-TTY environments
aip agents run <AGENT_ID> --input "test" --view plain --no-tty

JSON Parsing Errors

# Problem: Invalid JSON output
# Solution: Ensure you're using --view json
aip agents run <AGENT_ID> --input "test" --view json

📊 Performance Considerations

Streaming vs Non-Streaming

  • Streaming: Better user experience, real-time feedback

  • Non-streaming: Better for automation, predictable response times

Renderer Performance

  • Auto: Intelligent format selection, slight overhead

  • JSON: Fastest parsing, machine-readable

  • Markdown: Good for documentation, moderate overhead

  • Plain: Fastest output, minimal formatting

TTY Detection

  • TTY: Rich formatting, interactive features

  • Non-TTY: Plain output, script-friendly

🔗 Related Documentation

  • Agents Guide - Create and manage agents

  • File Uploads - Handle file uploads with agents

  • Output & Scripting - Automate with machine-readable output

🔗 Navigation

← Back to Guides Overview

Master output control and streaming with the AIP SDK!

PreviousFile UploadsNextOutput & Scripting