Go SDK

Go SDK

Docker Agent를 Go 라이브러리로 사용해 에이전트를 애플리케이션에 내장해요.

출처: 문서

본문

Docker Agent를 Go 라이브러리로 사용해 AI 에이전트를 Go 애플리케이션에 직접 구축할 수 있어요. 에이전트 생성, 도구 통합, 실행에 대한 완전한 프로그래매틱 제어를 제공해요.

참고 — 임포트 경로:

import "github.com/docker/docker-agent/pkg/..."

핵심 패키지 (Core Packages)

패키지 용도
pkg/agent 에이전트 생성·구성
pkg/runtime 에이전트 실행·이벤트 스트리밍
pkg/session 대화 상태 관리
pkg/team 멀티 에이전트 팀 구성
pkg/tools 도구 인터페이스와 유틸리티
pkg/tools/builtin 내장 도구(shell, filesystem 등)
pkg/model/provider/* 모델 provider 클라이언트
pkg/config/latest 구성 타입
pkg/environment 환경과 시크릿
pkg/embeddedchat 커스텀 UI에 에이전트 런타임을 내장하기 위한 헤드리스 채팅 세션
pkg/tui/components/toolconfirm 도구 확인 정책: Decision enum, BuildPermissionPattern, 키 바인딩, 거부 이유 사전 설정. 권한 패턴 로직을 복사하는 대신 이걸 공유하세요.
pkg/tui/service StaticSessionState — 보수적 고정 값을 가진 SessionStateReader. 전체 TUI 앱 밖에서 메시지/도구 뷰를 렌더링할 때 사용. 손으로 만든 9개 메서드 스텁을 대체해요.
pkg/tui/animation Stopper / StopView — 애니메이션 라이프사이클 계약. UI에서 제거된 뷰에 StopAnimation을 호출해 누수된 tick 구독을 방지해요.
pkg/tui/components/transcript 읽기 전용 Messages() 접근자가 있는 내장 트랜스크립트 뷰. 호스트 테스트와 영속 레이어에서 대화 구조 관찰용.

TUI 컴포넌트 내장 (Embedding TUI Components)

Docker Agent의 TUI 프리미티브 위에 커스텀 UI를 구축할 때, 런타임과 UI를 동기화 상태로 유지하는 계약을 정의하는 네 개의 패키지가 있어요:

  • pkg/tui/components/toolconfirm — 패턴 구축 로직을 복사하지 말고 이 패키지를 가져와 권한 결정 정책에 사용하세요. Decision enum, BuildPermissionPattern 헬퍼, 거부 이유 사전 설정이 정식 소스예요: 확인 대화상자에서 사용자에게 보여주는 패턴이 런타임에 부여하는 패턴과 정확히 같아요.
  • pkg/tui/service — 전체 TUI 앱 밖에서 개별 메시지나 도구 뷰를 렌더링할 때 StaticSessionState를 스텁 SessionStateReader로 사용하세요. 아홉 인터페이스 메서드 모두에 보수적 고정 값을 반환해 손으로 만든 스텁이 필요 없어요.
  • pkg/tui/animation — tick 기반 애니메이션을 소유한 어떤 뷰에든 animation.Stopper를 구현하세요. 뷰가 UI 계층에서 제거될 때마다 StopAnimation을 호출해 죽은 뷰에 대해 발화하는 누수된 time.Tick 구독을 방지하세요.
  • pkg/tui/components/transcript — 대화 기록 표시용 트랜스크립트 뷰를 내장하세요. 현재 트랜스크립트 메시지 슬라이스를 읽으려면 Messages() 메서드를 사용하세요(읽기 전용 취급 — 변경은 렌더를 역동기화해요). 채팅 기록을 단언하는 호스트 측 테스트와 대화 상태를 스냅샷해야 하는 영속 레이어에 유용해요.

헤드리스 내장 채팅 (Headless Embedded Chat, pkg/embeddedchat)

pkg/embeddedchat은 Docker Agent 런타임을 둘러싼 얇은 래퍼로, Docker Agent의 Bubble Tea 애플리케이션을 실행하는 대신 자신의 UI에서 에이전트를 구동하게 해줘요. 런타임 구성, 이벤트 투영, 대화 상태를 처리하고 단순한 Send / Confirm / Restart / Close API를 노출해요.

세션 만들기 (Creating a session)

import (
  "context"
  "fmt"
  "strings"

  dagentcfg "github.com/docker/docker-agent/pkg/config"
  dagentruntime "github.com/docker/docker-agent/pkg/runtime"
  "github.com/docker/docker-agent/pkg/embeddedchat"
)

chat, err := embeddedchat.New(ctx, embeddedchat.Config{
  // AgentSource can be a file path, raw YAML bytes, or an OCI reference.
  AgentSource: dagentcfg.NewBytesSource("agent", []byte(agentYAML)),
})
if err != nil {
  return err
}
defer chat.Close()

메시지 보내고 이벤트 읽기 (Sending a message and reading events)

Send는 사용자 메시지를 대화에 추가하고 Event 값의 채널을 반환해요. 채널이 닫힐 때까지 배출하세요.

events, err := chat.Send(ctx, "Hello! What can you do?")
if err != nil {
  return err
}

var response strings.Builder
for ev := range events {
  switch {
  case ev.Text != "":
    response.WriteString(ev.Text)
  case ev.Tool != nil && ev.Tool.NeedsConfirmation:
    // Approve the pending tool call (use ResumeApproveSession to allow all).
    if err := chat.Confirm(ctx, dagentruntime.ResumeApprove()); err != nil {
      return err
    }
  case ev.Tool != nil && ev.Tool.Finished:
    fmt.Printf("[tool %s finished]\n", ev.Tool.Def.Name)
  case ev.Err != nil:
    fmt.Printf("error: %v\n", ev.Err)
  case ev.Done:
    fmt.Println("\n[turn complete]")
  }
}
fmt.Print(response.String())

대화 재시작 (Restarting the conversation)

런타임을 다시 만들지 않고 새 대화를 시작하려면:

if err := chat.Restart(); err != nil {
  return err
}

이벤트 유형 (Event types)

필드 설정 시점
Text 어시스턴트 텍스트 델타; 전체 답을 위해 문자열로 누적.
Tool 도구 호출 시작, 확인 필요, 또는 완료.
Tool.NeedsConfirmation Confirm이 호출될 때까지 런타임 차단.
Tool.Finished 도구 호출 완료; 오류가 나면 Tool.IsError가 true.
Err 사용자 대면 런타임 오류; 이후 콘텐츠 이벤트 없음.
Done 턴의 깨끗한 종료; 더 이상 이벤트 없음.
RuntimeEvent 전체 스트림이 필요한 호출자를 위한 원본 runtime.Event.

고급 사용(커스텀 elicitation, 원시 이벤트 검사)을 위해 chat.Runtime()을 호출해 기본 runtime.Runtime에 직접 접근할 수 있어요.

경고 — 호환성 파괴 변경: Runtime.ResumeElicitation (#3584): Runtime.ResumeElicitation은 특정 동시 elicitation 요청과 응답을 연관시킬 수 있도록 elicitationID 파라미터를 얻었어요(여러 백그라운드 작업이 동시에 입력을 eliciting할 수 있게 된 후 필요). 특히 기존 3-인자 형식 호출자가 변경 없이 컴파일되도록 variadic(elicitationID ...string)으로 선언됐어요 — rt.ResumeElicitation(ctx, action, content)는 여전히 동작하고 유일한 보류 요청을 해결하는 것으로 폴백해요.

자체 runtime.Runtime을 구현한다면(runtime.LocalRuntime / runtime.RemoteRuntime을 내장하는 대신) 메서드 시그니처를 일치하도록 업데이트해야 하고, OnElicitationRequest(handler func(runtime.Event)) 메서드도 추가해야 해요(런타임이 elicitation을 절대 발생시키지 않으면 no-op으로 충분) — 둘 다 필수 인터페이스 메서드이고 OnToolsChanged / OnBackgroundEvent가 이미 쓰는 기존 no-op 가능 패턴과 일치해요.

선택적 Provider 빌드 태그 (Optional Provider Build Tags)

기본적으로 Docker Agent는 네 개의 클라우드 provider(OpenAI, Anthropic, Google, Amazon Bedrock)를 모두 포함해요. Docker Agent를 자신의 바이너리에 내장할 때 필요 없는 provider를 — 그들의 전이 SDK 의존성과 함께 — 컴파일에서 빼내 바이너리 크기를 줄일 수 있어요.

각 provider는 자신 프로젝트의 태그와 충돌을 피하기 위해 docker_agent_ 접두사가 붙은 부정 빌드 태그로 게이팅돼요:

빌드 태그 제거되는 provider 제거되는 주요 의존성
docker_agent_no_openai OpenAI github.com/openai/openai-go
docker_agent_no_anthropic Anthropic github.com/anthropics/anthropic-sdk-go (부분 — 참고)
docker_agent_no_google Google / Vertex AI google.golang.org/genai, Vertex 인증 스택, 그리고 Vertex Model Garden을 경유한 Anthropic과 OpenAI SDK 간접
docker_agent_no_bedrock Amazon Bedrock github.com/aws/aws-sdk-go-v2 스택(가장 큰 provider 의존성 트리)

Bedrock과 OpenAI 없이 빌드하려면:

go build -tags 'docker_agent_no_bedrock docker_agent_no_openai' ./...

컴파일에서 빠진 provider의 모델을 요청하면 구성 시점에 명확한 "not compiled into this build" 오류로 실패해요. dmr(Docker Model Runner) provider와 규칙 기반 라우터는 항상 컴파일돼요.

경고 — Anthropic + Google 의존성: Google provider의 Vertex Model Garden 지원도 Anthropic SDK를 임포트하므로 Anthropic 의존성은 docker_agent_no_anthropic과 docker_agent_no_google이 둘 다 설정될 때만 완전히 제거돼요.

RAG 도구셋 (옵트아웃) (RAG Toolset, opt-out)

RAG toolset(type: rag)은 NewDefaultToolsetRegistry()(pkg/teamloader/toolsets에서)와 loaderdefaults.Opts()(pkg/teamloader/defaults에서, 관례적 임포트 별칭 loaderdefaults 사용)에 포함돼요.

기본 tree-sitter 코드 파서는 cgo를 사용하지만 pkg/rag/treesitter의 빌드 태그 가드는 CGO_ENABLED와 무관하게 패키지 임포트가 안전하게 해줘요: CGO_ENABLED=0이면 파서 스텁이 컴파일되고 첫 사용 시 컴파일 시점이 아닌 런타임 오류를 반환해요.

RAG toolset을 바이너리에서 완전히 제외하려면(팀로더 Load에 전달하기 전에 레지스트리에서 제거) — !cgo 스텁의 지연된 런타임 오류 대신 에이전트에 로드 시점 경고를 표면화해요:

import (
  "github.com/docker/docker-agent/pkg/teamloader"
  loadertoolsets "github.com/docker/docker-agent/pkg/teamloader/toolsets"
)

// Opt out of the RAG toolset; a config that declares type: rag attaches
// a load-time warning to the agent instead of failing at document processing.
creators := loadertoolsets.DefaultToolsetCreators()
delete(creators, "rag")
registry := teamloader.NewToolsetRegistry(creators)

teamloader.Load를 호출할 때 teamloader.WithToolsetRegistry(registry)로 커스텀 레지스트리를 전달하세요. teamloader.Load()는 알 수 없는 toolset 유형에 대해 오류를 반환하지 않는다는 점에 주의하세요 — 실패는 로드 시점 경고로 기록되고 agent.DrainWarnings()로 검색할 수 있으며, 로깅과 TUI 알림으로도 표면화돼요.

커스텀 내장 테마 등록 (Registering Custom Built-in Themes)

Docker Agent를 내장할 때 styles.RegisterBuiltinThemes로 자신의 내장 테마를 기여할 수 있어요. 등록된 테마는 기존 테마 피커, /theme 명령, settings.theme 구성 키와 완벽히 통합돼요 — Docker Agent 자체의 번들 테마처럼 동작해요.

import (
  "embed"

  "github.com/docker/docker-agent/pkg/tui/styles"
)

//go:embed themes/*.yaml
var brandThemes embed.FS

// Call at startup, before applying any persisted theme:
if err := styles.RegisterBuiltinThemes(brandThemes); err != nil {
  return err
}

각 테마 파일은 내장 파일시스템 안의 themes/<name>.yaml에 있고 부분 재정의예요 — 바꾸고 싶은 색만 필요하고 나머지는 DefaultTheme()로 폴백해요.

# themes/brand.yaml
name: Brand
colors:
  accent: "#FF6A00"
  background: "#1A0F0A"

name:을 생략하면 Docker Agent는 테마 피커의 표시 이름으로 파일명 스템을 사용해요(예: themes/brand.yaml에서 brand).

Docker Agent의 기본 테마를 완전히 교체하려면 파일을 themes/default.yaml로 제공하세요 — 설정하지 않은 색은 상속하면서 번들 기본을 가려요.

의미:

  • 등록된 소스가 번들 테마보다 우선해요. 등록된 참조는 같은 이름의 번들 테마를 재정의해요.
  • 여러 등록 소스 사이에서 충돌 시 마지막 등록이 이겨요.
  • RegisterBuiltinThemes는 즉시 검증해요(nil fs, 누락된 themes/ dir) — 오류가 피커 시점이 아니라 등록 시점에 표면화돼요.

MCP OAuth 토큰 영속성 (MCP OAuth Token Persistence)

기본적으로 MCP OAuth 토큰은 메모리에만 저장되고 프로세스 재시작에 걸쳐 영속되지 않아요. CLI는 시작 시 키링 기반 저장소를 자동으로 등록해요. Docker Agent를 라이브러리로 내장할 때 토큰이 재시작을 견디게 하려면 직접 해야 해요.

어떤 MCP toolset이 초기화되기 전에 keyringstore.Register()를 호출해 OS 키링 기반 토큰 저장소를 활성화해요:

import "github.com/docker/docker-agent/pkg/tools/mcp/keyringstore"

func main() {
  // Must be called before teamloader.Load() on configs with remote MCP
  // toolsets; calling it after the store is created panics.
  keyringstore.Register()
  // ... rest of your startup code
}

경고 — 호출 순서가 중요해요: keyringstore.Register()가 기본 토큰 저장소가 이미 지연 초기화된 후에 호출되면 Docker Agent가 패닉해요. 저장소는 원격 MCP toolset이 구성될 때 초기화되는데, 이는 teamloader.Load() 안에서 일어나요. 원격 MCP toolset을 포함한 구성에서 항상 keyringstore.Register()를 teamloader.Load()보다 먼저 호출하세요.

영구 OAuth 토큰이 필요 없다면(예: 단기 배치 작업이나 테스트), 호출을 생략하고 토큰을 프로세스 수명 동안 메모리에 유지해요.

JavaScript 명령 표현식 (옵트인) (JavaScript Command Expressions, opt-in)

슬래시 명령 지시는 ${...} JavaScript 표현식을 임베드할 수 있어요(${args[0]}, ${args.join(" ")}, ${tool({...})}). 이를 평가하려면 goja JavaScript 엔진이 필요한데, 의도적으로 pkg/runtime의 임포트 그래프 밖에 유지돼 코드 기반 임베더가 기본적으로 링크하지 않게 해요.

CLI, teamloader.Load(), pkg/cli.Run(), embeddedchat/defaults는 자동으로 활성화해요. 코드로 팀을 구축하고 명령에 ${...} 표현식을 사용한다면(또는 runtime.ResolveCommand / cli.PrepareUserMessage를 직접 호출한다면) 평가자를 직접 등록하세요:

import "github.com/docker/docker-agent/pkg/runtime/jscommands"

func main() {
  jscommands.Register()
  // ... rest of your startup code
}

등록이 없으면 ${...} 표현식은 확장되지 않은 채 남고 수정 방법을 명명하는 경고가 로그돼요. 명령 해석의 다른 모든 것(레거시 !tool(...) 문법 포함)은 평소대로 동작해요.

기본 예제 (Basic Example)

간단한 에이전트를 만들고 실행해요:

package main

import (
  "context"
  "fmt"
  "log"
  "os/signal"
  "syscall"

  "github.com/docker/docker-agent/pkg/agent"
  "github.com/docker/docker-agent/pkg/config/latest"
  "github.com/docker/docker-agent/pkg/environment"
  "github.com/docker/docker-agent/pkg/model/provider/openai"
  "github.com/docker/docker-agent/pkg/runtime"
  "github.com/docker/docker-agent/pkg/session"
  "github.com/docker/docker-agent/pkg/team"
)

func main() {
  ctx, cancel := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
  defer cancel()

  if err := run(ctx); err != nil {
    log.Fatal(err)
  }
}

func run(ctx context.Context) error {
  // Create model provider
  llm, err := openai.NewClient(
    ctx,
    &latest.ModelConfig{
      Provider: "openai",
      Model:    "gpt-4o",
    },
    environment.NewDefaultProvider(),
  )
  if err != nil {
    return err
  }

  // Create agent
  assistant := agent.New(
    "root",
    "You are a helpful assistant.",
    agent.WithModel(llm),
    agent.WithDescription("A helpful assistant"),
  )

  // Create team and runtime
  t := team.New(team.WithAgents(assistant))
  rt, err := runtime.New(t)
  if err != nil {
    return err
  }

  // Run with a user message
  sess := session.New(
    session.WithUserMessage("What is 2 + 2?"),
  )

  messages, err := rt.Run(ctx, sess)
  if err != nil {
    return err
  }

  // Print the response
  fmt.Println(messages[len(messages)-1].Message.Content)
  return nil
}

커스텀 도구 (Custom Tools)

에이전트를 위한 커스텀 도구를 정의해요:

package main

import (
  "context"
  "encoding/json"
  "fmt"

  "github.com/docker/docker-agent/pkg/tools"
)

// Define the tool's input schema
type AddNumbersArgs struct {
  A int `json:"a"`
  B int `json:"b"`
}

// Implement the tool handler
func addNumbers(_ context.Context, toolCall tools.ToolCall) (*tools.ToolCallResult, error) {
  var args AddNumbersArgs
  if err := json.Unmarshal([]byte(toolCall.Function.Arguments), &args); err != nil {
    return nil, err
  }

  result := args.A + args.B
  return tools.ResultSuccess(fmt.Sprintf("%d", result)), nil
}

func main() {
  // Create the tool definition
  addTool := tools.Tool{
    Name:        "add",
    Category:    "math",
    Description: "Add two numbers together",
    Parameters:  tools.MustSchemaFor[AddNumbersArgs](),
    Handler:     addNumbers,
  }

  // Use with an agent
  calculator := agent.New(
    "root",
    "You are a calculator. Use the add tool for arithmetic.",
    agent.WithModel(llm),
    agent.WithTools(addTool),
  )
  // ...
}

스트리밍 응답 (Streaming Responses)

이벤트가 발생할 때 처리해요:

func runStreaming(ctx context.Context, rt runtime.Runtime, sess *session.Session) error {
  events := rt.RunStream(ctx, sess)

  for event := range events {
    switch e := event.(type) {
    case *runtime.StreamStartedEvent:
      fmt.Println("Stream started")

    case *runtime.AgentChoiceEvent:
      // Print response chunks as they arrive
      fmt.Print(e.Content)

    case *runtime.ToolCallEvent:
      fmt.Printf("\n[Tool call: %s]\n", e.ToolCall.Function.Name)

    case *runtime.ToolCallConfirmationEvent:
      // Auto-approve tool calls
      rt.Resume(ctx, runtime.ResumeRequest{
        Type: runtime.ResumeTypeApproveSession,
      })

    case *runtime.ToolCallResponseEvent:
      fmt.Printf("[Tool response: %s]\n", e.Response)

    case *runtime.StreamStoppedEvent:
      fmt.Println("\nStream stopped")

    case *runtime.ErrorEvent:
      return fmt.Errorf("error: %s", e.Error)
    }
  }

  return nil
}

멀티 에이전트 팀 (Multi-Agent Teams)

하위 에이전트에 위임하는 에이전트를 만들어요:

package main

import (
  "github.com/docker/docker-agent/pkg/agent"
  "github.com/docker/docker-agent/pkg/team"
  "github.com/docker/docker-agent/pkg/tools/builtin"
)

func createTeam(llm provider.Provider) *team.Team {
  // Create a child agent
  researcher := agent.New(
    "researcher",
    "You research topics thoroughly.",
    agent.WithModel(llm),
    agent.WithDescription("Research specialist"),
  )

  // Create root agent with sub-agents
  coordinator := agent.New(
    "root",
    "You coordinate research tasks.",
    agent.WithModel(llm),
    agent.WithDescription("Team coordinator"),
    agent.WithSubAgents(researcher),
    agent.WithToolSets(builtin.NewTransferTaskTool()),
  )

  return team.New(team.WithAgents(coordinator, researcher))
}

내장 도구 (Built-in Tools)

Docker Agent의 내장 도구를 사용해요:

import (
  "github.com/docker/docker-agent/pkg/config"
  "github.com/docker/docker-agent/pkg/tools/builtin"
)

func createAgentWithBuiltinTools(llm provider.Provider) *agent.Agent {
  // Runtime config for tools that need it
  rtConfig := &config.RuntimeConfig{
    Config: config.Config{
      WorkingDir: "/path/to/workdir",
    },
  }

  return agent.New(
    "root",
    "You are a developer assistant.",
    agent.WithModel(llm),
    agent.WithToolSets(
      // Shell tool for running commands
      builtin.NewShellTool(os.Environ(), rtConfig),
      // Filesystem tools
      builtin.NewFilesystemTool(rtConfig.Config.WorkingDir),
      // Think tool for reasoning
      builtin.NewThinkTool(),
      // Todo tool for task tracking
      builtin.NewTodoTool(),
    ),
  )
}

HTTP 미들웨어 / Transport 래퍼 (HTTP Middleware / Transport Wrappers)

options.WithHTTPTransportWrapper를 사용해 Docker Agent가 만드는 모든 provider 클라이언트의 transport 체인에 HTTP 미들웨어를 주입해요. 요청 추적, 커스텀 헤더 주입, 메트릭 수집 또는 HTTP 레이어의 다른 어떤 횡단 관심사에도 유용해요.

import (
  "net/http"

  "github.com/docker/docker-agent/pkg/model/provider/options"
)

type headerTransport struct {
  base http.RoundTripper
}

func (t *headerTransport) RoundTrip(req *http.Request) (*http.Response, error) {
  req = req.Clone(req.Context())
  req.Header.Set("X-Request-Source", "my-app")
  return t.base.RoundTrip(req)
}

// Example: add a custom header to every outbound LLM request
wrapper := options.WithHTTPTransportWrapper(
  func(base http.RoundTripper) http.RoundTripper {
    return &headerTransport{base: base}
  },
)

client, err := openai.NewClient(ctx, &latest.ModelConfig{
  Provider: "openai",
  Model:    "gpt-4o",
}, env, wrapper)

래퍼는 이미 계측된 transport(OpenTelemetry, SSE 압축 해제, Desktop 프록시 지원)를 base 인자로 받으므로, 래핑해도 모든 내장 동작이 보존돼요.

지원 provider: Anthropic, OpenAI, Gemini(GeminiAPI 백엔드), Bedrock. 직접·게이트웨이/프록시 모드 둘 다에서 동작해요.

경고 — Vertex AI는 지원되지 않아요: Vertex AI는 Docker Agent가 가로챌 수 없는 ADC 관리 HTTP 클라이언트를 사용해요. transport 래퍼가 설정되면 Docker Agent는 Vertex AI 대신 GeminiAPI 백엔드로 폴백하고 디버그 메시지가 로그돼요.

게이트웨이 모드에서 래퍼는 단기 인증 토큰 때문에 게이트웨이 클라이언트가 호출마다 재구축되므로 모든 LLM 요청에 호출돼요. 직접 모드에서는 클라이언트 구성 시점에 한 번 호출돼요. 속도 제한 응답(HTTP 429)은 런타임이 비재시도로 분류하고 모델 체인이 다음 폴백으로 건너뛰게 하므로, 요청별 결과를 추적하는 래퍼는 이런 것을 재시도된 호출이 아닌 실패로 관찰할 거예요.

래퍼 함수에서 nil을 반환하는 것은 허용되지 않아요. Docker Agent는 경고를 로그하고 원래 transport를 유지해요.

다른 Provider 사용 (Using Different Providers)

import (
  "github.com/docker/docker-agent/pkg/model/provider/anthropic"
  "github.com/docker/docker-agent/pkg/model/provider/gemini"
  "github.com/docker/docker-agent/pkg/model/provider/openai"
)

// OpenAI
openaiClient, _ := openai.NewClient(ctx, &latest.ModelConfig{
  Provider: "openai",
  Model:    "gpt-4o",
}, env)

// Anthropic
anthropicClient, _ := anthropic.NewClient(ctx, &latest.ModelConfig{
  Provider: "anthropic",
  Model:    "claude-sonnet-4-5",
}, env)

// Google Gemini
geminiClient, _ := gemini.NewClient(ctx, &latest.ModelConfig{
  Provider: "google",
  Model:    "gemini-3.5-flash",
}, env)

세션 옵션 (Session Options)

import "github.com/docker/docker-agent/pkg/session"

sess := session.New(
  // Set a title for the session
  session.WithTitle("Code Review Task"),

  // Add user message
  session.WithUserMessage("Review this code for bugs"),

  // Limit iterations
  session.WithMaxIterations(20),
)

오류 처리 (Error Handling)

messages, err := rt.Run(ctx, sess)
if err != nil {
  if errors.Is(err, context.Canceled) {
    // User cancelled
    log.Println("Operation cancelled")
    return nil
  }
  if errors.Is(err, context.DeadlineExceeded) {
    // Timeout
    log.Println("Operation timed out")
    return nil
  }
  // Other error
  return fmt.Errorf("runtime error: %w", err)
}

// Check for errors in the event stream
for event := range rt.RunStream(ctx, sess) {
  if errEvent, ok := event.(*runtime.ErrorEvent); ok {
    return fmt.Errorf("stream error: %s", errEvent.Error)
  }
}

완전한 예제 (Complete Example)

examples/golibrary 디렉토리에서 완전한 동작 예제를 확인하세요:

  • simple/ — 도구 없는 기본 에이전트
  • tool/ — 커스텀 도구 구현
  • stream/ — 스트리밍 이벤트 처리
  • multi/ — 하위 에이전트가 있는 멀티 에이전트
  • builtintool/ — 내장 도구 사용

더 알아보기 (Learn more)