> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dedaluslabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Runner Reference

> Complete reference for DedalusRunner.run() parameters

`DedalusRunner` is the core of the Dedalus SDK. It orchestrates local tools, hosted MCP servers, streaming, and any model from any provider into a single agentic loop. Five lines of code, any agent you want.

## Quick Example

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from dedalus_labs import AsyncDedalus, DedalusRunner

client = AsyncDedalus()
runner = DedalusRunner(client)

result = await runner.run(
    input="What's the weather in Tokyo?",
    model="anthropic/claude-sonnet-4-20250514",
    mcp_servers=["windsornguyen/open-meteo-mcp"],
    max_steps=5,
)

print(result.final_output)
```

***

## Parameters

<Expandable title="Core">
  <ParamField body="input" type="string | Message[]" required>
    The user's prompt or a list of messages. Use a string for single-turn requests; use a message list for multi-turn conversations.
  </ParamField>

  <ParamField body="model" type="string | string[]" required>
    Model(s) to use. Format: `provider/model-name` (e.g., `openai/gpt-4o`,
    `anthropic/claude-sonnet-4-20250514`). Pass a list for routing or fallback behavior.
  </ParamField>

  <ParamField body="instructions" type="string">
    System prompt that defines the agent's behavior and personality.
  </ParamField>

  <ParamField body="messages" type="Message[]">
    Existing conversation history. Use with `result.to_input_list()` for multi-turn conversations.
  </ParamField>
</Expandable>

<Expandable title="Tools & MCP">
  <ParamField body="tools" type="Callable[]">
    Local Python/TS functions the model can call. Schema extracted automatically from type hints and docstrings. See [Tools](/sdk/tools).
  </ParamField>

  <ParamField body="mcp_servers" type="string[]">
    Hosted MCP servers to connect. Format: `["owner/server-name"]`.
  </ParamField>

  <ParamField body="credentials" type="Credential[]">
    Credentials for MCP server authentication.
  </ParamField>

  <ParamField body="tool_choice" type="string | object">
    Control tool usage:

    * `"auto"` — Model decides (default)
    * `"none"` — Disable tools
    * `"required"` — Force tool use
    * `{"type": "function", "function": {"name": "..."}}` — Force specific tool
  </ParamField>
</Expandable>

<Expandable title="Model Parameters">
  <ParamField body="temperature" type="float">
    Sampling temperature (0–2). Higher values increase randomness. Default varies by model.
  </ParamField>

  <ParamField body="max_tokens" type="integer">
    Maximum tokens in the response.
  </ParamField>

  <ParamField body="top_p" type="float">
    Nucleus sampling threshold (0–1). Alternative to temperature.
  </ParamField>

  <ParamField body="frequency_penalty" type="float">
    Penalize repeated tokens based on frequency (-2.0 to 2.0).
  </ParamField>

  <ParamField body="presence_penalty" type="float">
    Penalize tokens that have appeared at all (-2.0 to 2.0).
  </ParamField>

  <ParamField body="logit_bias" type="object">
    Adjust likelihood of specific tokens. Maps token IDs to bias values (-100 to 100).
  </ParamField>
</Expandable>

<Expandable title="Output Control">
  <ParamField body="response_format" type="type | object">
    Enforce structured output. Pass a Pydantic model or JSON schema. See [Structured Outputs](/sdk/structured-outputs).
  </ParamField>

  <ParamField body="stream" type="boolean" default="false">
    Return an async iterator for streaming responses. See [Streaming](/sdk/streaming).
  </ParamField>

  <ParamField body="return_intent" type="boolean" default="false">
    Include model's intent analysis in result.
  </ParamField>
</Expandable>

<Expandable title="Execution">
  <ParamField body="max_steps" type="integer" default="10">
    Maximum agentic loop iterations. The loop runs until the model stops calling tools or hits this limit.
  </ParamField>

  <ParamField body="transport" type="string" default="http">
    Transport protocol: `"http"` or `"realtime"`.
  </ParamField>
</Expandable>

<Expandable title="Advanced">
  <ParamField body="policy" type="PolicyInput">
    Runtime policies for dynamic model selection or behavior modification.
  </ParamField>

  <ParamField body="handoff_config" type="object">
    Configuration for agent-to-agent handoffs. See [Handoffs](/sdk/handoffs).
  </ParamField>

  <ParamField body="agent_attributes" type="object">
    Attributes for agent routing and selection. Maps attribute names to float values.
  </ParamField>

  <ParamField body="model_attributes" type="object">
    Per-model attribute overrides. Maps model names to attribute dictionaries.
  </ParamField>

  <ParamField body="available_models" type="string[]">
    Restrict which models the agent can use.
  </ParamField>

  <ParamField body="strict_models" type="boolean" default="true">
    Enforce strict model validation.
  </ParamField>

  <ParamField body="guardrails" type="object[]">
    Input/output guardrail configurations.
  </ParamField>
</Expandable>

<Expandable title="Debugging">
  <ParamField body="verbose" type="boolean">
    Enable verbose logging.
  </ParamField>

  <ParamField body="debug" type="boolean">
    Enable debug mode with detailed traces and conversation snapshots.
  </ParamField>

  <ParamField body="on_tool_event" type="Callable">
    Callback fired when tools are called. Receives tool call details as a dictionary.
  </ParamField>
</Expandable>

***

## Return Value

<ResponseField name="RunResult" type="object">
  Response object returned by `runner.run()`.

  <Expandable title="Properties">
    <ParamField path="final_output" type="string" required>
      The final text response from the agent.
    </ParamField>

    <ParamField path="tool_results" type="ToolResult[]" required>
      Results from local tool executions. Each contains `name`, `result`, `step`, and optionally `error`.
    </ParamField>

    <ParamField path="mcp_results" type="MCPToolResult[]" required>
      Results from MCP server tool calls.
    </ParamField>

    <ParamField path="tools_called" type="string[]" required>
      Names of tools that were invoked during the run.
    </ParamField>

    <ParamField path="steps_used" type="integer" required>
      Number of agentic loop iterations used.
    </ParamField>

    <ParamField path="messages" type="Message[]" required>
      Full conversation history including tool calls. Useful for debugging or continuing conversations.
    </ParamField>

    <ParamField path="intents" type="object[]">
      Model's intent analysis (only present if `return_intent=true`).
    </ParamField>

    <ParamField path="output" type="string">
      Alias for `final_output`.
    </ParamField>

    <ParamField path="content" type="string">
      Alias for `final_output`.
    </ParamField>
  </Expandable>

  <Expandable title="Methods">
    <ParamField path="to_input_list()" type="method">
      Returns a copy of the conversation history for use in follow-up runs. Enables multi-turn conversations.
    </ParamField>
  </Expandable>
</ResponseField>

```python Multi-turn Chat theme={"theme":{"light":"github-light","dark":"github-dark"}}
import asyncio
from dedalus_labs import AsyncDedalus, DedalusRunner

async def main():
    client = AsyncDedalus()
    runner = DedalusRunner(client)
    messages: list[dict] = []

    while True:
        user_input = input("You: ").strip()
        if not user_input:
            break

        messages.append({"role": "user", "content": user_input})

        result = await runner.run(
            model="openai/gpt-4o",
            messages=messages,
        )

        messages = result.to_input_list()
        print(f"Assistant: {result.final_output}\n")

asyncio.run(main())
```

```json Example Response theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "final_output": "The weather in Tokyo is currently 18°C with clear skies.",
  "tool_results": [],
  "mcp_results": [
    {
      "name": "get_current_weather",
      "result": {"temperature": 18, "conditions": "clear"},
      "server": "windsornguyen/open-meteo-mcp"
    }
  ],
  "tools_called": ["get_current_weather"],
  "steps_used": 2,
  "messages": [...]
}
```

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Tools" icon="wrench" href="/sdk/tools">
    Define local functions the model can call.
  </Card>

  <Card title="Handoffs" icon="shuffle" href="/sdk/handoffs">
    Route between models mid-conversation.
  </Card>

  <Card title="Structured Outputs" icon="brackets-curly" href="/sdk/structured-outputs">
    Validate responses against schemas.
  </Card>

  <Card title="Streaming" icon="play" href="/sdk/streaming">
    Stream responses as they generate.
  </Card>
</CardGroup>