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

# Initialize and configure Agent Control

> Learn how to set up Agent Control.

## Overview

This tutorial will guide you through initializing the Splunk Agent Observability Logger and Agent Control SDK, running your agent with the Splunk Agent Observability Logger, and decorating your LLM and tool calls. By the end of this guide, you'll be ready to start monitoring your controls.

## Before you begin

This tutorial assumes you have completed the following procedures:

1. [Install the dependencies for Agent Control](/concepts/agent-control/overview)
2. [Create a control](/how-to-guides/agent-control/create-a-control)

## Steps

<Steps>
  <Step title="Set the required environment variables">
    ```bash theme={null}
    # Only required if you are using an on-premises, standalone,
    # or custom deployment
    # export SPLUNK_AO_API_KEY="<your-splunk-ao-api-key>"
    # export SPLUNK_AO_CONSOLE_URL="<your-splunk-ao-url>"
    export SPLUNK_AO_API_URL="<your-api-url>"

    export SPLUNK_AO_PROJECT="<project-name>"
    export SPLUNK_AO_AGENT_STREAM="<agent-stream-name>"
    export AGENT_CONTROL_URL="https://agent-control.<env>.<registered-domain>"
    # The <registered-domain> is derived from your deployment URL
    # Example URL: https://console.subdomain.yourcompany.com
    # Example registered domain: yourcompany.com
    export AGENT_CONTROL_TARGET_TYPE="agent_stream"
    export AGENT_CONTROL_AGENT_NAME="default"
    export AGENT_CONTROL_API_KEY_HEADER="Splunk-AO-API-Key"
    ```
  </Step>

  <Step title="Initialize the Splunk Agent Observability Logger and the Agent Control SDK">
    Use the [Splunk Agent Observability Logger](/sdk-api/logging/splunk-ao-logger) around the agent run to write traces, spans, and control spans to the configured project and Agent Stream. The exact logger API may differ depending on your SDK version. You must initialize Splunk Agent Observability with the same project and Agent Stream that you plan to create controls for.

    The following example shows how to initialize the Splunk Agent Observability Logger.

    Note that:

    * The value for `target_id` should be `logger.agent_stream_id`, not the Agent Stream name. The logger resolves the human-readable project and Agent Stream names to IDs, and Agent Control uses that resolved `agent_stream_id` to fetch the controls.
    * You must use the same API key unless your deployment has a separate Agent Control key. The key must be valid for your targeted Splunk Agent Observability environment.

    ```python theme={null}
    import os
    from uuid import uuid4

    import agent_control
    from splunk_ao.logger import SplunkAOLogger


    def init_splunk_ao_and_agent_control() -> SplunkAOLogger:
        # These names must match the project/Agent stream where controls are bound.
        project_name = os.environ["SPLUNK_AO_PROJECT"]
        agent_stream_name = os.environ["SPLUNK_AO_AGENT_STREAM"]

        logger = SplunkAOLogger(
            project=project_name,
            agent_stream=agent_stream_name,
            mode=os.environ.get("SPLUNK_AO_MODE", "batch"),
        )

        logger.start_session(
            name=os.environ.get("SPLUNK_AO_SESSION_NAME", "agent-control-demo"),
            external_id=f"agent-control-demo-{uuid4()}",
            metadata={"source": "agent-control-demo"},
        )

        if logger.project_id is None or logger.agent_stream_id is None:
            raise RuntimeError("Splunk Agent Observability logger did not resolve project/Agent Stream IDs.")

        # Useful for downstream SDK integrations/debugging.
        os.environ["SPLUNK_AO_PROJECT_ID"] = logger.project_id
        os.environ["SPLUNK_AO_AGENT_STREAM_ID"] = logger.agent_stream_id

        agent_control.init(
            agent_name=os.environ.get("AGENT_CONTROL_AGENT_NAME", "my-agent"),
            agent_description="Agent Control app with Splunk Agent Observability logging",
            server_url=os.environ["AGENT_CONTROL_URL"],
            # Only required if you are using an on-premises, standalone, or custom deployment
            # api_key=os.environ["SPLUNK_AO_API_KEY"],
            api_key_header=os.environ.get("AGENT_CONTROL_API_KEY_HEADER", "Splunk-AO-API-Key"),
            observability_enabled=True,
            observability_sink_name="registered",

            # Controls are usually bound to the Splunk Agent Observability Agent Stream.
            target_type=os.environ.get("AGENT_CONTROL_TARGET_TYPE", "agent_stream"),
            target_id=logger.agent_stream_id,
        )

        return logger
    ```
  </Step>

  <Step title="Run your agent with the Splunk Agent Observability Logger">
    ```python theme={null}
    logger = init_splunk_ao_and_agent_control()

    trace = logger.start_trace(
        name="my-agent-run",
        input={"user_request": "Wire $15,000 to Horizon Robotics."},
    )

    try:
        # Run your decorated agent Steps here.
        result = run_agent()
    finally:
        logger.conclude(output={"result": result})
        logger.flush()
    ```
  </Step>

  <Step title="Decorate your LLM and tool calls">
    Wrap LLM and tool Steps with the SDK decorator so controls can evaluate the right Steps. Use `@control()` on the function that performs the LLM call.

    ```python theme={null}
    from agent_control import control


    @control()
    async def call_llm(message: str) -> str:
        response = client.chat.completions.create(
            model="gpt-4.1",
            messages=[{"role": "user", "content": message}],
        )
        return response.choices[0].message.content
    ```

    For tool call examples and more details, see [Decorate LLM and tool calls](https://docs.agentcontrol.dev/how-to/decorate-llm-tool-calls).
  </Step>
</Steps>

## Next steps

Learn how to monitor controls using the **Controls View** and investigate how a control executed using the **Traces** tab. See [Monitor a control](/how-to-guides/agent-control/monitor-a-control).