에이전트용 프로젝트를 즉시 프로비저닝하기

사용자가 만드는 각 에이전트마다 전용 Confident AI 프로젝트를 만들고, 모든 에이전트를 격리된 상태로 트레이스·평가해요.

출처: 문서

본문

개요

이 가이드는 플랫폼 UI에서 수동으로 만들지 않고 프로그래밍 방식으로 Confident AI 프로젝트를 만들고 싶은 팀을 위한 것이에요. 특히 내부 에이전트 구축 플랫폼, 멀티테넌트 제품, 그리고 각 에이전트(또는 테넌트, 고객)마다 자체 격리된 Confident AI 프로젝트를 가져야 하는 개념 증명에 유용해요.

예를 들어 모든 사용자가 자기 에이전트를 만드는 엔터프라이즈 플랫폼을 상상해 보세요. 각 에이전트는 자체 Confident AI 프로젝트를 얻어서, 그 트레이스와 평가가 플랫폼의 다른 모든 에이전트와 격리되게 해요.

이 가이드에서 배울 것:

Admin SDK를 하나의 Organization API Key로 구성해요.
각 에이전트가 만들어지는 순간 코드에서 프로젝트를 생성해요.
반환된 Project API Key를 프로젝트 ID와 함께 저장해서 나중에 트레이스 라우팅에 써요.
각 요청을 자체 Project API Key로 스코프해서 confident-trace로 트레이스를 올바른 프로젝트로 라우팅해요.

끝나면 플랫폼이 요청 시 에이전트당 격리된 Confident AI 프로젝트를 프로비저닝하고, 각 에이전트의 트레이스·데이터셋·평가를 올바른 워크스페이스로 보낼 수 있어요.

flowchart TB
    Org["Your Confident AI Organization"]

    Org --> AppA["Application A Project"]
    Org --> AppB["Application B Project"]
    Org --> AppC["Application C Project"]

    AppA --> AppAData["Application A traces<br/>Application A datasets<br/>Application A evaluations"]
    AppB --> AppBData["Application B traces<br/>Application B datasets<br/>Application B evaluations"]
    AppC --> AppCData["Application C traces<br/>Application C datasets<br/>Application C evaluations"]

    classDef org fill:#f8fafc,stroke:#334155,stroke-width:2px
    classDef project fill:#eef2ff,stroke:#4f46e5,stroke-width:1px
    classDef data fill:#f0fdf4,stroke:#16a34a,stroke-width:1px
    class Org org
    class AppA,AppB,AppC project
    class AppAData,AppBData,AppCData data

만들어 보기

SDK 설치하기

Admin SDK는 confidentai로 Python과 TypeScript 모두에서 사용 가능해요. 각 애플리케이션의 트레이스를 자체 프로젝트로 라우팅하려면 confident-trace도 필요해요.

Python

pip install confidentai confident-trace

TypeScript

npm install confidentai confident-trace

Admin SDK 구성하기

시작 전에 Organization API Key가 필요해요. 여기서 가져오세요.

CONFIDENT_ORG_API_KEY를 Organization API Key로 설정해요. Admin SDK는 클라이언트를 만들 때 기본적으로 이 변수를 읽어요.

export CONFIDENT_ORG_API_KEY="confident_us_org_..."

Python

from confidentai import ConfidentAI

confident_ai = ConfidentAI()

TypeScript

import { ConfidentAI } from "confidentai";

export const confidentAI = new ConfidentAI();

프로젝트 프로비저닝하기

각 애플리케이션마다 프로젝트를 만들어요. projects.create(...) 호출이 새 프로젝트와 첫 Project API Key를 반환해요. 두 값을 해당 애플리케이션과 함께 저장해서, 나중에 트레이스가 같은 프로젝트로 라우팅되게 해요.

이 예시의 저장 헬퍼는 여러분의 자체 데이터베이스나 영속성 레이어를 나타내요.

Python

from app.confident import confident_ai
from app.storage import save_application_project

def onboard_application(application_slug: str):
    new_project = confident_ai.projects.create(name=application_slug)

    save_application_project(
        application_slug,
        project_id=new_project.project.id,
        project_api_key=new_project.api_key.value,
    )
    return new_project.project.id

TypeScript

import { confidentAI } from "./confident";
import { saveApplicationProject } from "./storage";

export async function onboardApplication(applicationSlug: string) {
  const newProject = await confidentAI.projects.create({ name: applicationSlug });

  await saveApplicationProject(applicationSlug, {
    projectId: newProject.project.id,
    projectApiKey: newProject.apiKey.value,
  });
  return newProject.project.id;
}

생성 후 프로젝트 접근을 부여하려면 project.invitations.create(...)로 멤버를 초대하고 같은 Admin SDK 클라이언트에서 역할을 배정해요.

트레이스 라우팅하기

Project API Key가 어느 프로젝트가 트레이스를 받는지 결정해요. 서버가 시작할 때 init()을 한 번 호출하고, 요청마다 테넌트의 저장된 키를 불러와 추적된 작업을 project 스코프로 감싸요. 그 스코프 안에서 만들어진 모든 스팬은 테넌트의 프로젝트로 내보내집니다.

Python

from openai import OpenAI
from confident_trace import init, span, project_context
from app.storage import load_application_project

init()
client = OpenAI()

@span(type="agent")
def support_agent(query: str) -> str:
    return client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": query}],
    ).choices[0].message.content

def run_for_application(application_slug: str, query: str):
    application = load_application_project(application_slug)
    with project_context(api_key=application.project_api_key):
        return support_agent(query)

TypeScript

import OpenAI from "openai";
import { init, span, projectContext } from "confident-trace";
import { loadApplicationProject } from "./storage";

export const runtime = init();
const openai = new OpenAI();

const supportAgent = span(
  { name: "support_agent", type: "agent" },
  async (query: string) => {
    const res = await openai.chat.completions.create({
      model: "gpt-4o",
      messages: [{ role: "user", content: query }],
    });
    return res.choices[0].message.content;
  },
);

export async function runForApplication(applicationSlug: string, query: string) {
  const application = await loadApplicationProject(applicationSlug);
  return projectContext({ apiKey: application.projectApiKey }, () => supportAgent(query));
}

Node preload(node --import confident-trace/register dist/server.js)로 서버를 실행해야 OpenAI 호출이 인스트루먼트된다는 걸 기억해요.

추적 작업이 시작되기 전에 스코프를 여세요 — 이미 활성인 스팬 안에서 프로젝트를 바꾸는 것은 거부돼요. 트레이스가 이미 목적지를 배정받았기 때문이에요. 동시 요청은 각자 자기 목적지를 유지하고, 스코프가 끝나면 기본 프로젝트(CONFIDENT_API_KEY에서)가 복원돼요. 키 자체는 서버 측에 남고 스팬 속성에 절대 나타나지 않아요. async with project_context(...)를 포함한 전체 동작은 projects를 보세요.

라우팅 실패는 기본 프로젝트로 폴백하지 않아요. 의도적이에요 — 테넌트 A의 트레이스를 조용히 기본 프로젝트로 보내는 것은 버리는 것보다 더 나쁜 결과니까요. 하지만 저장된 키가 없거나 잘못되면 트레이스 없음으로 나타나지, 잘못된 곳에 트레이스로 나타나지 않아요. 테넌트의 트레이스가 없으면 먼저 저장소에서 불러온 키를 확인하세요.

라우팅 검증하기

애플리케이션용 프로젝트를 만들고, 애플리케이션을 실행하고, 트레이스가 올바른 프로젝트에 나타나는지 확인해요. 두 테넌트의 요청을 연달아 보내서 서로 새지 않는지 확인하세요.

Python

from confident_trace import shutdown
from app.onboarding import onboard_application
from app.agent import run_for_application

onboard_application("support-bot")
onboard_application("sales-bot")

try:
    run_for_application("support-bot", "What's on my agenda today?")
    run_for_application("sales-bot", "Draft a follow-up for the Acme deal.")
finally:
    shutdown()

TypeScript

import { onboardApplication } from "./onboarding";
import { runForApplication, runtime } from "./agent";

await onboardApplication("support-bot");
await onboardApplication("sales-bot");

try {
  await runForApplication("support-bot", "What's on my agenda today?");
  await runForApplication("sales-bot", "Draft a follow-up for the Acme deal.");
} finally {
  await runtime.shutdown();
}

Observatory를 열고 support-bot 프로젝트로 전환해요. 트레이스가 그 프로젝트에, 다른 모든 애플리케이션과 격리되어 나타나요 — sales-bot 프로젝트는 자기 트레이스만 보여줘요.

동영상

Observatory의 트레이스

완료 ✅. 이제 워크플로가 애플리케이션마다 전용 프로젝트를 만들고, 단일 Organization API Key로 트레이스를 라우팅해요.

shutdown()은 기본 프로젝트만이 아니라 런타임이 소유한 모든 프로젝트 목적지를 플러시해요. 그래서 몇 테넌트를 서빙했든 프로세스 종료 시 호출 하나로 충분해요.

다음 단계

이제 각 테넌트나 애플리케이션이 트레이스를 자체 프로젝트로 라우팅할 수 있으니, 다음 섹션으로 워크플로를 확장해 보세요:

에이전트용 프로젝트를 즉시 프로비저닝하기