Agent playground

Mark your agent as an entrypoint

Mark your agent’s main function as an entrypoint. Opik automatically detects the function signature and registers it as a runnable agent. Load your prompts from the Prompt Library inside the entrypoint, so that you can edit them from the playground.

import threading
import opik
client = opik.Opik()
# Create the prompt in the Prompt Library if it does not exist yet
if client.get_chat_prompt("my-agent-prompt", project_name="my-agent") is None:
    client.create_chat_prompt(
        name="my-agent-prompt",
        messages=[
            {"role": "system", "content": "You are a helpful assistant."},
            {"role": "user", "content": "{{query}}"},
        ],
        project_name="my-agent",
    )
@opik.track(entrypoint=True, project_name="my-agent")
def my_agent(query: str, max_results: int = 5) -> str:
    prompt = client.get_chat_prompt("my-agent-prompt", project_name="my-agent")
    messages = prompt.format(variables={"query": query})
    # Your agent logic here
    return result
if __name__ == "__main__":
    # Keep the process alive so the runner can pick up jobs
    threading.Event().wait()

Parameter types are displayed as input fields in the UI. In Python they are inferred from type hints; in TypeScript, provide them explicitly via the params option.

The example creates the prompt only when it is not in the Prompt Library. If you restart your agent, the code does not replace the prompt versions that you saved from the playground.

The process must keep running so the runner can pick up jobs. If your agent is not already served by a web framework (for example FastAPI, Flask, Express, or Fastify), block the main thread as shown in the Python example.

Start the playground

opik endpoint --project my-agent -- python3 my_agent.py

The CLI validates that an entrypoint exists, opens a browser-based pairing flow, registers your agents, and begins polling for jobs.

Talk to your agent

Once connected, the Agent Playground page shows a Connected badge and an input field for each of your agent’s parameters in the Test input panel. Fill in the inputs and click Run (or press Shift+Enter). The agent executes locally on your machine, and its output appears in the Result panel. Click View trace to open the full trace of the run.

Iterate on prompts

The Prompts panel, next to Test input, shows each prompt in your project’s Prompt Library. Edit a prompt’s messages, or pick a different version from the version selector next to the prompt name. You don’t need to leave the playground or change your code.

Edits are not saved right away: the prompt shows Unsaved changes. Click Run again and your agent uses the edited prompt for that run, so you can see the impact immediately. Try different wordings and compare results across runs. When you’re satisfied, click the save icon next to Unsaved changes to save the edit as a new prompt version. Later runs in the playground use the saved version.