Getting started with Agent Configuration

<Steps>
  <Step title="Install the Opik skill">
    ```bash
    npx skills add comet-ml/opik-skills
    ```

    This skill is compatible with all coding agents including Claude Code, Codex, Cursor, OpenCode and more.
  </Step>
  <Step title="Run the integration">
    Once the skill is installed, you can integrate with Opik using the following prompt:
    ```
    Version my prompts and agent parameters in Opik using the /instrument:agent-configuration command.
    ```
  </Step>
</Steps>

### Step 1 — Define and push your first configuration

Start by defining what your agent needs — model name, temperature, prompts, etc. — and push it to Opik. You only do this once (or whenever you want to create a new version from code).

<CodeBlocks>

```python title="Python"
import opik

client = opik.Opik()

# Define your configuration schema with default values
class MyConfig(opik.Config):
    model: str = "gpt-4o-mini"
    temperature: float = 0.7
    system_prompt: opik.Prompt = None

# Push the first version
client.create_config(
    config=MyConfig(
        model="gpt-4o-mini",
        temperature=0.7,
        system_prompt=opik.Prompt(
            name="system_prompt",
            prompt="You are a helpful assistant specializing in {{domain}}.",
        ),
    ),
    project_name="my-agent",
)
```

```ts title="TypeScript"
import { Opik } from "opik";

const client = new Opik();

// Create a versioned prompt
const systemPrompt = await client.createPrompt({
  name: "system_prompt",
  prompt: "You are a helpful assistant specializing in {{domain}}.",
});

// Push the first version
await client.createConfig(
  {
    model: "gpt-4o-mini",
    temperature: 0.7,
    system_prompt: systemPrompt,
  },
  { projectName: "my-agent" },
);
```
</CodeBlocks>

### Step 2 — Fetch the configuration at runtime

Now use `get_or_create_config` / `getOrCreateConfig` inside your agent to pull the active configuration. The `fallback` gives your agent safe defaults to use if Opik is temporarily unreachable.

<CodeBlocks>
  ```python title="Python"
  import opik

  client = opik.Opik()

  class MyConfig(opik.Config):
      model: str = "gpt-4o-mini"
      temperature: float = 0.7
      system_prompt: opik.Prompt = None

  @opik.track(project_name="my-agent")
  def run_agent(user_input: str):
      cfg = client.get_or_create_config(
          fallback=MyConfig(
              model="gpt-4o-mini",
              temperature=0.7,
              system_prompt=opik.Prompt(
                  name="system_prompt",
                  prompt="You are a helpful assistant.",
              ),
          ),
      )

      # Use the config values in your agent
      response = call_llm(
          model=cfg.model,
          temperature=cfg.temperature,
          system_prompt=cfg.system_prompt.format(domain="customer support"),
      )
      return response
  ```

  ```ts title="TypeScript"
  import { Opik, track } from "opik";

  const client = new Opik();

  const runAgent = track(
    { name: "run_agent", projectName: "my-agent" },
    async (userInput: string) => {
      const cfg = await client.getOrCreateConfig({
        fallback: {
          model: "gpt-4o-mini",
          temperature: 0.7,
          system_prompt: "You are a helpful assistant.",
        },
      });

      // Use the config values in your agent
      const response = await callLlm({
        model: cfg.model as string,
        temperature: cfg.temperature as number,
        systemPrompt: String(cfg.system_prompt),
      });
      return response;
    },
  );
  ```
</CodeBlocks>

<Warning>
  `get_or_create_config` / `getOrCreateConfig` **must** be called inside a tracked function
  (`@opik.track` in Python, `track()` in TypeScript). We need this to link the configuration
  version to the trace automatically.
</Warning>

<Tip>
  When you don't pass `env` or `version`, the SDK defaults to the version labeled `prod`.
  See [Managing versions](#managing-agent-configuration-versions) below for how to control this.
</Tip>

const runAgent = track(
  { name: "run_agent", projectName: "my-agent" },
  async (userInput: string) => {
    // Fetch the staging version
    const cfg = await client.getOrCreateConfig({
      fallback: {
        model: "gpt-4o-mini",
        temperature: 0.7,
        system_prompt: "You are a helpful assistant.",
      },
      env: "staging",
    });
    // ...
  },
);

const systemPrompt = await client.createPrompt({
  name: "system_prompt",
  prompt: "You are a helpful assistant specializing in {{domain}}.",
});

const chatPrompt = await client.createChatPrompt({
  name: "chat_prompt",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "{{user_query}}" },
  ],
});

await client.createConfig(
  {
    model: "gpt-4o-mini",           // string field
    tool_definition: "{}",           // string field
  },
  { projectName: "my-agent" }
);

await client.createConfig(
  {
    temperature: 0.7,               // float field
    similarity_threshold: 0.8,       // float field
  },
  { projectName: "my-agent" }
);