Visualization & Response Display

Learn how to display agent outputs, stream tokens, view execution traces, and render Mermaid workflow flowcharts.

Everything Kern produces — agent responses, workflow diagrams, debug traces, and streaming output — can be rendered visually. This guide covers how to display responses in your application, inspect execution traces, and generate visual diagrams from your workflows.

Agent Response Display

Every call to agent.run() returns a RunOutput object. This object contains structured metadata, token usage, and media contents.

Basic Response Inspection

1from kern import Agent
2from kern.models.openai import OpenAIChat
3
4agent = Agent(
5    model=OpenAIChat(id="gpt-4o-mini"),
6    description="You are a research assistant.",
7)
8
9response = agent.run("Explain quantum computing in one sentence")
10
11print(response.content)      # The raw text response
12print(response.model)        # "gpt-4o-mini"
13print(response.usage.total)  # Total token count

The RunOutput Attributes

Attribute	Type	Description
`content`	`str \| BaseModel`	The main response content (a string, or a Pydantic object if `output_schema` is set).
`messages`	`list[Message]`	The full chat history, including system instructions and assistant turns.
`tool_calls`	`list[ToolCall]`	Any tools that were called during execution.
`usage`	`TokenUsage`	Tokens consumed (input, output, and total).

Response Formatting

Markdown Rendering

Set markdown=True on your agent to instruct the model to produce clean, structured markdown output.

1agent = Agent(
2    model=OpenAIChat(id="gpt-4o-mini"),
3    markdown=True,
4    description="Write in markdown format.",
5)

Streaming Display

For real-time typewriter effects, use agent.run_stream() to yield tokens as they are generated, or call agent.print_response() to stream directly to stdout:

1# Stream to console
2agent.print_response("Explain binary search", stream=True)

Observability & Tracing Dashboard

Kern includes a local, lightweight control plane and dashboard. You can log all agent sessions, tool calls, and execution steps to a local database and inspect them in real time.

Enable Tracing

Enable tracing=True when initializing AgentOS to capture runs automatically:

1from kern.os import AgentOS
2from kern.db.sqlite import SqliteDb
3
4db = SqliteDb(db_file="traces.db")
5
6agent_os = AgentOS(
7    agents=[agent],
8    db=db,
9    tracing=True,  # Log every request and tool invocation
10)
11
12app = agent_os.get_app()

Run your FastAPI application using fastapi dev and visit http://localhost:8000/traces to inspect the trace logs in the reliability dashboard.

Workflow Flowchart Generation

Beyond text outputs, Kern can generate visual diagrams from your workflow pipelines. Every Workflow has a .visualize() method that creates a Mermaid flowchart.

Generate a Flowchart

1from kern.workflow import Workflow
2from kern.workflow.step import Step, Parallel, Condition
3
4# Define step connections
5workflow = Workflow(
6    name="Content Generation Pipeline",
7    steps=[
8        Step(name="Research", agent=researcher),
9        Parallel(
10            name="Drafting",
11            steps=[
12                Step(name="Draft A", agent=writer),
13                Step(name="Draft B", agent=writer),
14            ]
15        ),
16        Condition(
17            name="Quality Check",
18            condition="score > 8",
19            true_step=Step(name="Publish", agent=publisher),
20            false_step=Step(name="Revise", agent=editor),
21        )
22    ]
23)
24
25# Export as a PNG or SVG image
26workflow.visualize(output_file="pipeline.png", theme="default")

Visual Themes

You can customize the design of your flowchart by choosing a theme:

"default": Colorful nodes that distinguish step types.
"monotone": A sleek, single-hue design perfect for reports.
"black": A high-contrast theme suited for dark-mode slides and presentations.