에이전트 컨텍스트¶
ADK(Agent Development Kit)에서 컨텍스트(context)는 에이전트와 그 도구들이 특정 작업을 수행하는 동안 사용할 수 있는 중요한 정보의 묶음을 의미합니다. 현재 작업이나 대화 차례를 효과적으로 처리하는 데 필요한 배경지식 및 리소스라고 생각할 수 있습니다.
에이전트는 종종 최신 사용자 메시지 이상의 정보가 있어야 제대로 작동합니다. 컨텍스트는 다음을 가능하게 하므로 필수적입니다.
- 상태 유지: 대화의 여러 단계에 걸쳐 세부 정보를 기억합니다(예: 사용자 선호도, 이전 계산 결과, 장바구니 항목). 이는 주로 세션 상태(session state)를 통해 관리됩니다.
- 데이터 전달: 한 단계(LLM 호출이나 도구 실행 등)에서 발견되거나 생성된 정보를 후속 단계와 공유합니다. 여기서도 세션 상태가 핵심적인 역할을 합니다.
- 서비스 접근: 다음과 같은 프레임워크 기능과 상호작용합니다.
- 아티팩트 저장소: 세션과 관련된 파일이나 데이터 덩어리(PDF, 이미지, 설정 파일 등)를 저장하거나 불러옵니다.
- 메모리: 사용자와 연결된 과거 상호작용이나 외부 지식 소스에서 관련 정보를 검색합니다.
- 인증: 도구가 외부 API에 안전하게 접근하는 데 필요한 자격 증명을 요청하고 검색합니다.
- ID 및 추적: 현재 어떤 에이전트가 실행 중인지(
agent.name) 알고, 로깅 및 디버깅을 위해 현재 요청-응답 주기(invocation_id)를 고유하게 식별합니다. - 도구별 작업: 현재 상호작용의 세부 정보에 접근해야 하는 인증 요청이나 메모리 검색과 같은 도구 내 특수 작업을 활성화합니다.
단일하고 완전한 사용자 요청-최종 응답 주기(호출(invocation))에 대한 이 모든 정보를 하나로 묶는 중심적인 요소는 InvocationContext입니다. 하지만 일반적으로 이 객체를 직접 생성하거나 관리하지는 않습니다. ADK 프레임워크는 호출이 시작될 때(예: runner.run_async를 통해) 이를 생성하고, 관련 컨텍스트 정보를 에이전트 코드, 콜백, 도구에 암묵적으로 전달합니다.
# How the framework provides context
from google.adk import Runner
# 1. You initialize a Runner with your agent and services
runner = Runner(
app_name="my_app",
agent=my_root_agent,
session_service=my_session_service,
artifact_service=my_artifact_service,
)
# 2. You call run_async with the user input
# Note: run_async is an asynchronous generator yielding Events.
# The framework internally creates an InvocationContext and passes it
# implicitly to your agent code, callbacks, and tools.
async for event in runner.run_async(
user_id="user123",
session_id="session456",
new_message=user_message
):
print(event.stringify_content())
# As a developer, you work with the context objects provided in method arguments.
/* Conceptual Pseudocode: How the framework provides context (Internal Logic) */
const runner = new InMemoryRunner({ agent: myRootAgent });
const session = await runner.sessionService.createSession({ ... });
const userMessage = createUserContent(...);
// --- Inside runner.runAsync(...) ---
// 1. Framework creates the main context for this specific run
const invocationContext = new InvocationContext({
invocationId: "unique-id-for-this-run",
session: session,
userContent: userMessage,
agent: myRootAgent, // The starting agent
sessionService: runner.sessionService,
pluginManager: runner.pluginManager,
// ... other necessary fields ...
});
//
// 2. Framework calls the agent's run method, passing the context implicitly
await myRootAgent.runAsync(invocationContext);
// --- End Internal Logic ---
// As a developer, you work with the context objects provided in method arguments.
/* Conceptual Pseudocode: How the framework provides context (Internal Logic) */
sessionService := session.InMemoryService()
r, err := runner.New(runner.Config{
AppName: appName,
Agent: myAgent,
SessionService: sessionService,
})
if err != nil {
log.Fatalf("Failed to create runner: %v", err)
}
s, err := sessionService.Create(ctx, &session.CreateRequest{
AppName: appName,
UserID: userID,
})
if err != nil {
log.Fatalf("FATAL: Failed to create session: %v", err)
}
scanner := bufio.NewScanner(os.Stdin)
for {
fmt.Print("\nYou > ")
if !scanner.Scan() {
break
}
userInput := scanner.Text()
if strings.EqualFold(userInput, "quit") {
break
}
userMsg := genai.NewContentFromText(userInput, genai.RoleUser)
events := r.Run(ctx, s.Session.UserID(), s.Session.ID(), userMsg, agent.RunConfig{
StreamingMode: agent.StreamingModeNone,
})
fmt.Print("\nAgent > ")
for event, err := range events {
if err != nil {
log.Printf("ERROR during agent execution: %v", err)
break
}
if event != nil && event.Content != nil && len(event.Content.Parts) > 0 {
fmt.Print(event.Content.Parts[0].Text)
}
}
}
/* How the framework provides context */
InMemoryRunner runner = new InMemoryRunner(agent);
Session session = runner
.sessionService()
.createSession(runner.appName(), USER_ID, initialState, SESSION_ID )
.blockingGet();
try (Scanner scanner = new Scanner(System.in, StandardCharsets.UTF_8)) {
while (true) {
System.out.print("\nYou > ");
String userInput = scanner.nextLine();
if ("quit".equalsIgnoreCase(userInput)) {
break;
}
Content userMsg = Content.fromParts(Part.fromText(userInput));
Flowable<Event> events = runner.runAsync(session.userId(), session.id(), userMsg);
System.out.print("\nAgent > ");
events.blockingForEach(event -> System.out.print(event.stringifyContent()));
}
}
import com.google.adk.kt.runners.InMemoryRunner
// How the framework provides context
// 1. You initialize a Runner with your agent and services
val runner =
InMemoryRunner(
agent = myRootAgent,
appName = "my_app",
sessionService = mySessionService,
artifactService = myArtifactService,
)
// 2. You call runAsync with the user input
// Note: runAsync returns a Flow of Events.
// The framework internally creates an InvocationContext and passes it
// implicitly to your agent code, callbacks, and tools.
runner
.runAsync(
userId = "user123",
sessionId = "session456",
newMessage = userMessage,
).collect { event ->
println(event.contentText())
}
// As a developer, you work with the context objects provided in method arguments.
컨텍스트 유형¶
ADK는 에이전트의 환경, 상태 및 리소스를 관리하는 중앙 메커니즘으로 Context 클래스를 사용합니다. Context가 모든 에이전트 상호 작용의 기본 역할을 하지만, 에이전트의 실행 흐름에서 사용되는 위치에 따라 기능과 권한의 최적의 균형을 제공하도록 설계된 특화된 "버전"으로 나타납니다.
이러한 특정 컨텍스트 유형을 사용하면 ADK는 세션 상태, 메모리 또는 자격 증명과 같은 필요한 정보에 필요한 시간과 장소에 에이전트가 정확히 액세스할 수 있도록 보장합니다.
마주하게 될 주요 컨텍스트 유형은 다음과 같습니다.
-
InvocationContext: 서비스 참조 및 수명 주기 관리를 포함하여 전체 호출에 대한 포괄적인 뷰를 제공하기 위해 핵심 에이전트 실행(_run_async_impl,_run_live_impl) 중에 사용됩니다. -
ReadonlyContext: 명령 공급자(instruction provider) 내와 같이 변경이 불가능한 시나리오에서 사용되는 기본적인 컨텍스트 정보의 가볍고 제한적인 뷰입니다. -
Context: 에이전트 수명 주기 및 모델 콜백에서 사용됩니다. 세션 상태 읽기/쓰기, 아티팩트 관리 및 메모리 서비스에 데이터 주입을 위한 견고한 기능 세트를 제공합니다. -
ToolContext: 도구 실행 및 도구 관련 콜백에 맞게 조정되었습니다. Context의 기능 외에도 인증 흐름, 메모리 검색 및 아티팩트 검색을 위한 특화된 메서드가 포함되어 있습니다.
Note
호환성 정보: Python 및 TypeScript에서 CallbackContext와 ToolContext는 Context 유형으로 대체되었습니다. CallbackContext 클래스는 하위 호환성을 보장하기 위해 Context에 대한 별칭(alias)으로 유지됩니다. 기존 코드베이스에서 CallbackContext를 만날 수 있지만, 통합된 모든 기능 세트를 활용하려면 모든 신규 개발에 Context 클래스를 사용해야 합니다.
InvocationContext¶
- 사용 위치: 에이전트의 핵심 구현 메서드(
_run_async_impl,_run_live_impl) 내에서ctx인자로 직접 받습니다. - 목적: 현재 호출의 전체 상태에 대한 액세스를 제공합니다. 이는 가장 포괄적인 컨텍스트 객체입니다.
- 주요 내용:
session(state와events포함), 현재agent인스턴스,invocation_id, 초기user_content, 설정된 서비스(artifact_service,memory_service,session_service)에 대한 참조, 그리고 라이브/스트리밍 모드와 관련된 필드에 직접 액세스할 수 있습니다. -
사용 사례: 주로 에이전트의 핵심 로직이 전체 세션이나 서비스에 직접 액세스해야 할 때 사용됩니다. 하지만 종종 상태 및 아티팩트 상호작용은 자체 컨텍스트를 사용하는 콜백/도구에 위임됩니다. 또한 호출 자체를 제어하는 데 사용됩니다(예:
ctx.end_invocation = True설정).# Agent implementation receiving InvocationContext from google.adk.agents import BaseAgent from google.adk.agents.invocation_context import InvocationContext from google.adk.events import Event from typing import AsyncGenerator class MyAgent(BaseAgent): async def _run_async_impl(self, ctx: InvocationContext) -> AsyncGenerator[Event, None]: # Direct access example agent_name = ctx.agent.name session_id = ctx.session.id print(f"Agent {agent_name} running in session {session_id} for invocation {ctx.invocation_id}") # ... agent logic using ctx ... yield # ... event ...// Pseudocode: Agent implementation receiving InvocationContext import { BaseAgent, InvocationContext, Event } from '@google/adk'; class MyAgent extends BaseAgent { async *runAsyncImpl(ctx: InvocationContext): AsyncGenerator<Event, void, undefined> { // Direct access example const agentName = ctx.agent.name; const sessionId = ctx.session.id; console.log(`Agent ${agentName} running in session ${sessionId} for invocation ${ctx.invocationId}`); // ... agent logic using ctx ... yield; // ... event ... } }import ( "fmt" "google.golang.org/adk/v2/agent" "google.golang.org/adk/v2/session" ) // Pseudocode: Agent implementation receiving InvocationContext type MyAgent struct { } func (a *MyAgent) Run(ctx agent.InvocationContext) iter.Seq2[*session.Event, error] { return func(yield func(*session.Event, error) bool) { // Direct access example agentName := ctx.Agent().Name() sessionID := ctx.Session().ID() fmt.Printf("Agent %s running in session %s for invocation %s\n", agentName, sessionID, ctx.InvocationID()) // ... agent logic using ctx ... yield(&session.Event{Author: agentName}, nil) } }// Example: Agent implementation receiving InvocationContext import com.google.adk.agents.BaseAgent; import com.google.adk.agents.InvocationContext; import com.google.adk.events.Event; import io.reactivex.rxjava3.core.Flowable; public class MyAgent extends BaseAgent { @Override protected Flowable<Event> runAsyncImpl(InvocationContext invocationContext) { // Direct access example String agentName = invocationContext.agent().name(); String sessionId = invocationContext.session().id(); String invocationId = invocationContext.invocationId(); System.out.println("Agent " + agentName + " running in session " + sessionId + " for invocation " + invocationId); // ... agent logic using invocationContext ... return Flowable.empty(); } }import com.google.adk.kt.agents.BaseAgent import com.google.adk.kt.agents.InvocationContext import com.google.adk.kt.events.Event import kotlinx.coroutines.flow.Flow import kotlinx.coroutines.flow.flow // Agent implementation receiving InvocationContext class MyAgent( name: String, ) : BaseAgent(name = name) { override fun runAsyncImpl(context: InvocationContext): Flow<Event> = flow { // Direct access example val agentName = context.agent.name val sessionId = context.session.key.id println( "Agent $agentName running in session $sessionId " + "for invocation ${context.invocationId}", ) // ... agent logic using context ... // emit(...) // ... event ... } }
ReadonlyContext¶
- 사용 위치: 기본 정보에 대한 읽기 접근만 필요하고 수정은 허용되지 않는 시나리오(예:
InstructionProvider함수)에서 제공됩니다. 다른 컨텍스트의 기본 클래스이기도 합니다. - 목적: 기본적인 컨텍스트 세부 정보에 대한 안전한 읽기 전용 뷰를 제공합니다.
-
주요 내용:
invocation_id,agent_name, 그리고 현재state의 읽기 전용 뷰.# Example: Instruction provider receiving ReadonlyContext from google.adk.agents.readonly_context import ReadonlyContext def my_instruction_provider(context: ReadonlyContext) -> str: # Read-only access example # The state property provides a read-only MappingProxyType view of the state user_tier = context.state.get("user_tier", "standard") # context.state['new_key'] = 'value' # TypeError: 'mappingproxy' object does not support item assignment return f"Process the request for a {user_tier} user."// Pseudocode: Instruction provider receiving ReadonlyContext import { ReadonlyContext } from '@google/adk'; function myInstructionProvider(context: ReadonlyContext): string { // Read-only access example // The state object is read-only const userTier = context.state.get('user_tier') ?? 'standard'; // context.state.set('new_key', 'value'); // This would fail or throw an error return `Process the request for a ${userTier} user.`; }import ( "fmt" "google.golang.org/adk/v2/agent" ) // Pseudocode: Instruction provider receiving ReadonlyContext func myInstructionProvider(ctx agent.ReadonlyContext) (string, error) { // Read-only access example userTier, err := ctx.ReadonlyState().Get("user_tier") if err != nil { userTier = "standard" // Default value } // ctx.ReadonlyState() has no Set method since State() is read-only. return fmt.Sprintf("Process the request for a %v user.", userTier), nil }// Example: Instruction provider receiving ReadonlyContext import com.google.adk.agents.ReadonlyContext; public String myInstructionProvider(ReadonlyContext context) { // Read-only access example // state() returns an unmodifiable view of the session state String userTier = (String) context.state().getOrDefault("user_tier", "standard"); // context.state().put("new_key", "value"); // UnsupportedOperationException return "Process the request for a " + userTier + " user."; }import com.google.adk.kt.agents.ReadonlyContext import com.google.adk.kt.types.Content import com.google.adk.kt.types.Part // Example: Instruction provider receiving ReadonlyContext fun myInstructionProvider(context: ReadonlyContext): Content { // Read-only access example // The state property is a read-only Map snapshot of the session state val userTier = context.state["user_tier"] as? String ?: "standard" // context.state["new_key"] = "value" // Does not compile: Map has no set operator return Content(parts = listOf(Part(text = "Process the request for a $userTier user."))) }
CallbackContext 및 Context¶
- 사용 위치: 에이전트 생명주기 콜백(
before_agent_callback,after_agent_callback) 및 모델 상호작용 콜백(before_model_callback,after_model_callback)에callback_context로 전달됩니다. - 목적: 특히 콜백 내에서 상태를 검사 및 수정하고, 아티팩트와 상호작용하며, 호출 세부 정보에 접근하는 것을 용이하게 합니다.
- 주요 기능 (
ReadonlyContext에 추가됨):- 변경 가능한
state속성: 세션 상태를 읽고 쓸 수 있습니다. 여기서 변경된 사항(callback_context.state['key'] = value)은 추적되며 콜백 후 프레임워크가 생성하는 이벤트와 연결됩니다. - 아티팩트 메서드: 설정된
artifact_service와 상호작용하기 위한load_artifact(filename)및save_artifact(filename, part)메서드. - 직접적인
user_content접근.
- 변경 가능한
Note
Python 및 TypeScript에서 CallbackContext와 ToolContext는 Context 유형으로 대체되었습니다.
# Example: Callback receiving Context (CallbackContext is unified into Context)
from google.adk.agents.context import Context
from google.adk.models import LlmRequest
from google.genai import types
from typing import Optional
def my_before_model_cb(context: Context, request: LlmRequest) -> Optional[types.Content]:
# Read/Write state example
call_count = context.state.get("model_calls", 0)
context.state["model_calls"] = call_count + 1 # Modify state (tracks delta)
# Optionally load an artifact
# config_part = context.load_artifact("model_config.json")
print(f"Preparing model call #{call_count + 1} for invocation {context.invocation_id}")
return None # Allow model call to proceed
// Pseudocode: Callback receiving Context
import { Context, LlmRequest } from '@google/adk';
import { Content } from '@google/genai';
function myBeforeModelCb(context: Context, request: LlmRequest): Content | undefined {
// Read/Write state example
const callCount = (context.state.get('model_calls') as number) || 0;
context.state.set('model_calls', callCount + 1); // Modify state
// Optionally load an artifact
// const configPart = await context.loadArtifact('model_config.json');
console.log(`Preparing model call #${callCount + 1} for invocation ${context.invocationId}`);
return undefined; // Allow model call to proceed
}
import (
"fmt"
"google.golang.org/adk/v2/agent"
"google.golang.org/adk/v2/model"
)
// Pseudocode: Callback receiving CallbackContext
func myBeforeModelCb(ctx agent.Context, req *model.LLMRequest) (*model.LLMResponse, error) {
// Read/Write state example
callCount, err := ctx.State().Get("model_calls")
if err != nil {
callCount = 0 // Default value
}
newCount := callCount.(int) + 1
if err := ctx.State().Set("model_calls", newCount); err != nil {
return nil, err
}
// Optionally load an artifact
// configPart, err := ctx.Artifacts().Load("model_config.json")
fmt.Printf("Preparing model call #%d for invocation %s\n", newCount, ctx.InvocationID())
return nil, nil // Allow model call to proceed
}
// Example: Callback receiving CallbackContext
import com.google.adk.agents.CallbackContext;
import com.google.adk.models.LlmRequest;
import com.google.adk.models.LlmResponse;
import io.reactivex.rxjava3.core.Maybe;
public Maybe<LlmResponse> myBeforeModelCb(CallbackContext callbackContext, LlmRequest request) {
// Read/Write state example
int callCount = (int) callbackContext.state().getOrDefault("model_calls", 0);
callbackContext.state().put("model_calls", callCount + 1); // Modify state (tracks delta)
// Optionally load an artifact
// Maybe<Part> configPart = callbackContext.loadArtifact("model_config.json");
System.out.println("Preparing model call " + (callCount + 1) + " for invocation " + callbackContext.invocationId());
return Maybe.empty(); // Allow model call to proceed
}
import com.google.adk.kt.agents.CallbackContext
import com.google.adk.kt.callbacks.CallbackChoice
import com.google.adk.kt.models.LlmRequest
import com.google.adk.kt.models.LlmResponse
// Example: Callback receiving CallbackContext
suspend fun myBeforeModelCb(
context: CallbackContext,
request: LlmRequest,
): CallbackChoice<LlmRequest, LlmResponse> {
// Read/Write state example
val callCount = context.state["model_calls"] as? Int ?: 0
context.updateState("model_calls", callCount + 1) // Modify state (tracks delta)
// Optionally load an artifact
// val configPart = context.loadArtifact("model_config.json")
println("Preparing model call #${callCount + 1} for invocation ${context.invocationId}")
return CallbackChoice.Continue(request) // Allow model call to proceed
}
ToolContext¶
- 사용 위치:
FunctionTool을 지원하는 함수와 도구 실행 콜백(before_tool_callback,after_tool_callback)에tool_context로 전달됩니다. - 목적:
CallbackContext가 제공하는 모든 것과 더불어 인증 처리, 메모리 검색, 아티팩트 목록 조회와 같이 도구 실행에 필수적인 특수 메서드를 제공합니다. -
주요 기능 (
CallbackContext에 추가됨):- 인증 메서드: 인증 흐름을 트리거하는
request_credential(auth_config)와 사용자/시스템이 제공한 자격 증명을 검색하는get_auth_response(auth_config). - 아티팩트 목록 조회: 세션에서 사용 가능한 아티팩트를 찾는
list_artifacts(). - 메모리 검색: 설정된
memory_service에 질의하는search_memory(query). function_call_id속성: 이 도구 실행을 트리거한 LLM의 특정 함수 호출을 식별하며, 인증 요청이나 응답을 올바르게 연결하는 데 중요합니다.actions속성: 이 단계의EventActions객체에 직접 접근하여 도구가 상태 변경, 인증 요청 등을 신호할 수 있게 합니다.
# Example: Tool function receiving ToolContext from google.adk.tools import ToolContext from typing import Dict, Any # Assume this function is wrapped by a FunctionTool def search_external_api(query: str, tool_context: ToolContext) -> Dict[str, Any]: api_key = tool_context.state.get("api_key") if not api_key: # Define required auth config # auth_config = AuthConfig(...) # tool_context.request_credential(auth_config) # Request credentials # Use the 'actions' property to signal the auth request has been made # tool_context.actions.requested_auth_configs[tool_context.function_call_id] = auth_config return {"status": "Auth Required"} # Use the API key... print(f"Tool executing for query '{query}' using API key. Invocation: {tool_context.invocation_id}") # Optionally search memory or list artifacts # relevant_docs = tool_context.search_memory(f"info related to {query}") # available_files = tool_context.list_artifacts() return {"result": f"Data for {query} fetched."}// Pseudocode: Tool function receiving Context import { Context } from '@google/adk'; // __Assume this function is wrapped by a FunctionTool__ function searchExternalApi(query: string, context: Context): { [key: string]: string } { const apiKey = context.state.get('api_key') as string; if (!apiKey) { // Define required auth config // const authConfig = new AuthConfig(...); // context.requestCredential(authConfig); // Request credentials // The 'actions' property is now automatically updated by requestCredential return { status: 'Auth Required' }; } // Use the API key... console.log(`Tool executing for query '${query}' using API key. Invocation: ${context.invocationId}`); // Optionally search memory or list artifacts // Note: accessing services like memory/artifacts is typically async in TS, // so you would need to mark this function 'async' if you reused them. // context.searchMemory(`info related to ${query}`).then(...) // context.listArtifacts().then(...) return { result: `Data for ${query} fetched.` }; }import "google.golang.org/adk/v2/tool" // Pseudocode: Tool function receiving ToolContext type searchExternalAPIArgs struct { Query string `json:"query" jsonschema:"The query to search for."` } func searchExternalAPI(tc agent.Context, input searchExternalAPIArgs) (string, error) { apiKey, err := tc.State().Get("api_key") if err != nil || apiKey == "" { // In a real scenario, you would define and request credentials here. // This is a conceptual placeholder. return "", fmt.Errorf("auth required") } // Use the API key... fmt.Printf("Tool executing for query '%s' using API key. Invocation: %s\n", input.Query, tc.InvocationID()) // Optionally search memory or list artifacts // relevantDocs, _ := tc.SearchMemory(tc, "info related to %s", input.Query)) // availableFiles, _ := tc.Artifacts().List() return fmt.Sprintf("Data for %s fetched.", input.Query), nil }// Example: Tool function receiving ToolContext import com.google.adk.tools.ToolContext; import java.util.Map; // Assume this function is wrapped by a FunctionTool public Map<String, Object> searchExternalApi(String query, ToolContext toolContext) { String apiKey = (String) toolContext.state().getOrDefault("api_key", ""); if (apiKey.isEmpty()) { // Define required auth config // authConfig = AuthConfig(...); // toolContext.requestCredential(authConfig); // Request credentials // Use the 'actions' property to signal the auth request has been made return Map.of("status", "Auth Required"); } // Use the API key... System.out.println("Tool executing for query " + query + " using API key."); // Optionally list artifacts // Single<List<String>> availableFiles = toolContext.listArtifacts(); return Map.of("result", "Data for " + query + " fetched"); }import com.google.adk.kt.tools.ToolContext // Example: Tool function receiving ToolContext // Assume this function is wrapped by a FunctionTool fun searchExternalApi( query: String, toolContext: ToolContext, ): Map<String, Any> { val apiKey = toolContext.state["api_key"] as? String if (apiKey.isNullOrEmpty()) { return mapOf("status" to "Auth Required") } // Use the API key... println( "Tool executing for query '$query' using API key. " + "Invocation: ${toolContext.invocationId}", ) // Optionally search memory or list artifacts // val relevantDocs = toolContext.memoryService?.searchMemory( // toolContext.session.key.appName, toolContext.userId, "info related to $query") // val availableFiles = toolContext.listArtifacts() return mapOf("result" to "Data for $query fetched.") } - 인증 메서드: 인증 흐름을 트리거하는
이러한 다양한 컨텍스트 객체와 언제 사용해야 하는지를 이해하는 것은 ADK 애플리케이션의 상태를 효과적으로 관리하고, 서비스에 접근하며, 흐름을 제어하는 데 핵심적입니다.
컨텍스트를 사용하는 일반적인 작업¶
이제 다양한 컨텍스트 객체를 이해했으니, 에이전트와 도구를 만들 때 이를 사용하여 일반적인 작업을 수행하는 방법에 초점을 맞춰 보겠습니다.
정보 접근¶
컨텍스트에 저장된 정보를 읽어야 할 경우가 자주 있습니다.
-
세션 상태 읽기: 이전 단계에서 저장된 데이터나 사용자/앱 수준 설정에 접근합니다.
state속성에 대해 딕셔너리처럼 접근합니다.# Example: In a Tool function from google.adk.tools import ToolContext def my_tool(tool_context: ToolContext, **kwargs): user_pref = tool_context.state.get("user_display_preference", "default_mode") api_endpoint = tool_context.state.get("app:api_endpoint") # Read app-level state if user_pref == "dark_mode": # ... apply dark mode logic ... pass print(f"Using API endpoint: {api_endpoint}") # ... rest of tool logic ... # Example: In a Callback function from google.adk.agents.context import Context def my_callback(context: Context, **kwargs): last_tool_result = context.state.get("temp:last_api_result") # Read temporary state if last_tool_result: print(f"Found temporary result from last tool: {last_tool_result}") # ... callback logic ...// Pseudocode: In a Tool function import { Context } from '@google/adk'; async function myTool(context: Context) { const userPref = context.state.get('user_display_preference', 'default_mode'); const apiEndpoint = context.state.get('app:api_endpoint'); // Read app-level state if (userPref === 'dark_mode') { // ... apply dark mode logic ... } console.log(`Using API endpoint: ${apiEndpoint}`); // ... rest of tool logic ... } // Pseudocode: In a Callback function import { Context } from '@google/adk'; function myCallback(context: Context) { const lastToolResult = context.state.get('temp:last_api_result'); // Read temporary state if (lastToolResult) { console.log(`Found temporary result from last tool: ${lastToolResult}`); } // ... callback logic ... }import ( "google.golang.org/adk/v2/agent" "google.golang.org/adk/v2/session" "google.golang.org/adk/v2/tool" "google.golang.org/genai" ) // Pseudocode: In a Tool function type toolArgs struct { // Define tool-specific arguments here } type toolResults struct { // Define tool-specific results here } // Example tool function demonstrating state access func myTool(tc agent.Context, input toolArgs) (toolResults, error) { userPref, err := tc.State().Get("user_display_preference") if err != nil { userPref = "default_mode" } apiEndpoint, _ := tc.State().Get("app:api_endpoint") // Read app-level state if userPref == "dark_mode" { // ... apply dark mode logic ... } fmt.Printf("Using API endpoint: %v\n", apiEndpoint) // ... rest of tool logic ... return toolResults{}, nil } // Pseudocode: In a Callback function func myCallback(ctx agent.Context) (*genai.Content, error) { lastToolResult, err := ctx.State().Get("temp:last_api_result") // Read temporary state if err == nil { fmt.Printf("Found temporary result from last tool: %v\n", lastToolResult) } else { fmt.Println("No temporary result found.") } // ... callback logic ... return nil, nil }import com.google.adk.agents.CallbackContext; import com.google.adk.tools.ToolContext; // Example: In a Tool function public void myTool(ToolContext toolContext) { String userPref = (String) toolContext.state().getOrDefault("user_display_preference", "default_mode"); String apiEndpoint = (String) toolContext.state().get("app:api_endpoint"); // Read app-level state if ("dark_mode".equals(userPref)) { // ... apply dark mode logic ... } System.out.println("Using API endpoint: " + apiEndpoint); // ... rest of tool logic ... } // Example: In a Callback function public void myCallback(CallbackContext callbackContext) { String lastToolResult = (String) callbackContext.state().get("temp:last_api_result"); // Read temporary state if (lastToolResult != null && !lastToolResult.isEmpty()) { System.out.println("Found temporary result from last tool: " + lastToolResult); } // ... callback logic ... }import com.google.adk.kt.agents.CallbackContext import com.google.adk.kt.tools.ToolContext // Example: In a Tool function fun myTool(toolContext: ToolContext) { val userPref = toolContext.state["user_display_preference"] as? String ?: "default_mode" val apiEndpoint = toolContext.state["app:api_endpoint"] // Read app-level state if (userPref == "dark_mode") { // ... apply dark mode logic ... } println("Using API endpoint: $apiEndpoint") // ... rest of tool logic ... } // Example: In a Callback function fun myCallback(context: CallbackContext) { val lastToolResult = context.state["temp:last_api_result"] // Read temporary state if (lastToolResult != null) { println("Found temporary result from last tool: $lastToolResult") } // ... callback logic ... } -
현재 식별자 가져오기: 로깅이나 현재 작업을 기반으로 한 사용자 정의 로직에 유용합니다.
# Example: In any context (ToolContext shown) from google.adk.tools import ToolContext def log_tool_usage(tool_context: ToolContext, **kwargs): agent_name = tool_context.agent_name inv_id = tool_context.invocation_id func_call_id = getattr(tool_context, 'function_call_id', 'N/A') # Specific to ToolContext print(f"Log: Invocation={inv_id}, Agent={agent_name}, FunctionCallID={func_call_id} - Tool Executed.")// Pseudocode: In any context import { Context } from '@google/adk'; function logToolUsage(context: Context) { const agentName = context.agentName; const invId = context.invocationId; const functionCallId = context.functionCallId ?? 'N/A'; // Available when executing a tool console.log(`Log: Invocation=${invId}, Agent=${agentName}, FunctionCallID=${functionCallId} - Tool Executed.`); }import "google.golang.org/adk/v2/tool" // Pseudocode: In any context (ToolContext shown) type logToolUsageArgs struct{} type logToolUsageResult struct { Status string `json:"status"` } func logToolUsage(tc agent.Context, args logToolUsageArgs) (logToolUsageResult, error) { agentName := tc.AgentName() invID := tc.InvocationID() funcCallID := tc.FunctionCallID() fmt.Printf("Log: Invocation=%s, Agent=%s, FunctionCallID=%s - Tool Executed.\n", invID, agentName, funcCallID) return logToolUsageResult{Status: "Logged successfully"}, nil }// Example: In any context (ToolContext shown) import com.google.adk.tools.ToolContext; public void logToolUsage(ToolContext toolContext) { String agentName = toolContext.agentName(); String invId = toolContext.invocationId(); String functionCallId = toolContext.functionCallId().orElse("N/A"); // Specific to ToolContext System.out.println("Log: Invocation= " + invId + " Agent= " + agentName + " FunctionCallID= " + functionCallId); }import com.google.adk.kt.tools.ToolContext // Example: In any context (ToolContext shown) fun logToolUsage(toolContext: ToolContext) { val agentName = toolContext.agentName val invId = toolContext.invocationId val funcCallId = toolContext.functionCallId ?: "N/A" // Set only during a tool call println("Log: Invocation=$invId, Agent=$agentName, FunctionCallID=$funcCallId - Tool Executed.") } -
초기 사용자 입력 접근: 현재 호출을 시작한 메시지를 다시 참조합니다.
# Example: In a Callback from google.adk.agents.context import Context def check_initial_intent(context: Context, **kwargs): initial_text = "N/A" if context.user_content and context.user_content.parts: initial_text = context.user_content.parts[0].text or "Non-text input" print(f"This invocation started with user input: '{initial_text}'") # Example: In an Agent's _run_async_impl # async def _run_async_impl(self, ctx: InvocationContext) -> AsyncGenerator[Event, None]: # if ctx.user_content and ctx.user_content.parts: # initial_text = ctx.user_content.parts[0].text # print(f"Agent logic remembering initial query: {initial_text}") # ...// Pseudocode: In a Callback import { Context } from '@google/adk'; function checkInitialIntent(context: Context) { let initialText = 'N/A'; const userContent = context.userContent; if (userContent?.parts?.length) { initialText = userContent.parts[0].text ?? 'Non-text input'; } console.log(`This invocation started with user input: '${initialText}'`); }import ( "fmt" "google.golang.org/adk/v2/agent" "google.golang.org/genai" ) // Pseudocode: In a Callback func logInitialUserInput(ctx agent.Context) (*genai.Content, error) { userContent := ctx.UserContent() if userContent != nil && len(userContent.Parts) > 0 { if text := userContent.Parts[0].Text; text != "" { fmt.Printf("User's initial input for this turn: '%s'\n", text) } } return nil, nil // No modification }// Example: In a Callback import com.google.adk.agents.CallbackContext; import com.google.genai.types.Content; public void checkInitialIntent(CallbackContext callbackContext) { String initialText = "N/A"; if (callbackContext.userContent().isPresent() && callbackContext.userContent().get().parts() != null && !callbackContext.userContent().get().parts().get().isEmpty()) { initialText = callbackContext.userContent().get().parts().get().get(0).text().orElse("Non-text input"); // ... System.out.println("This invocation started with user input: " + initialText); } }import com.google.adk.kt.agents.CallbackContext // Example: In a Callback fun checkInitialIntent(context: CallbackContext) { var initialText = "N/A" val parts = context.userContent?.parts if (!parts.isNullOrEmpty()) { initialText = parts[0].text ?: "Non-text input" } println("This invocation started with user input: '$initialText'") } // Example: In an Agent's runAsyncImpl // override fun runAsyncImpl(context: InvocationContext): Flow<Event> = flow { // val initialText = context.userContent?.parts?.firstOrNull()?.text // if (initialText != null) { // println("Agent logic remembering initial query: $initialText") // } // ... // }
상태 관리¶
상태는 메모리와 데이터 흐름에 매우 중요합니다. CallbackContext 또는 ToolContext를 사용하여 상태를 수정하면 변경 사항이 프레임워크에 의해 자동으로 추적되고 유지됩니다.
-
작동 방식:
callback_context.state['my_key'] = my_value또는tool_context.state['my_key'] = my_value에 값을 쓰면, 이 변경 사항이 현재 단계의 이벤트와 연관된EventActions.state_delta에 추가됩니다. 그런 다음SessionService는 이벤트를 영구 저장할 때 이러한 델타를 적용합니다. -
도구 간 데이터 전달
# Example: Tool 1 - Fetches user ID from google.adk.tools import ToolContext import uuid def get_user_profile(tool_context: ToolContext) -> dict: user_id = str(uuid.uuid4()) # Simulate fetching ID # Save the ID to state for the next tool tool_context.state["temp:current_user_id"] = user_id return {"profile_status": "ID generated"} # Example: Tool 2 - Uses user ID from state def get_user_orders(tool_context: ToolContext) -> dict: user_id = tool_context.state.get("temp:current_user_id") if not user_id: return {"error": "User ID not found in state"} print(f"Fetching orders for user ID: {user_id}") # ... logic to fetch orders using user_id ... return {"orders": ["order123", "order456"]}// Pseudocode: Tool 1 - Fetches user ID import { Context } from '@google/adk'; import { v4 as uuidv4 } from 'uuid'; function getUserProfile(context: Context): Record<string, string> { const userId = uuidv4(); // Simulate fetching ID // Save the ID to state for the next tool context.state.set('temp:current_user_id', userId); return { profile_status: 'ID generated' }; } // Pseudocode: Tool 2 - Uses user ID from state function getUserOrders(context: Context): Record<string, string | string[]> { const userId = context.state.get('temp:current_user_id'); if (!userId) { return { error: 'User ID not found in state' }; } console.log(`Fetching orders for user ID: ${userId}`); // ... logic to fetch orders using user_id ... return { orders: ['order123', 'order456'] }; }import "google.golang.org/adk/v2/tool" // Pseudocode: Tool 1 - Fetches user ID type GetUserProfileArgs struct { } func getUserProfile(tc agent.Context, input GetUserProfileArgs) (string, error) { // A random user ID for demonstration purposes userID := "random_user_456" // Save the ID to state for the next tool if err := tc.State().Set("temp:current_user_id", userID); err != nil { return "", fmt.Errorf("failed to set user ID in state: %w", err) } return "ID generated", nil } // Pseudocode: Tool 2 - Uses user ID from state type GetUserOrdersArgs struct { } type getUserOrdersResult struct { Orders []string `json:"orders"` } func getUserOrders(tc agent.Context, input GetUserOrdersArgs) (*getUserOrdersResult, error) { userID, err := tc.State().Get("temp:current_user_id") if err != nil { return &getUserOrdersResult{}, fmt.Errorf("user ID not found in state") } fmt.Printf("Fetching orders for user ID: %v\n", userID) // ... logic to fetch orders using user_id ... return &getUserOrdersResult{Orders: []string{"order123", "order456"}}, nil }// Example: Tool 1 - Fetches user ID import com.google.adk.tools.ToolContext; import java.util.Map; import java.util.UUID; public Map<String, String> getUserProfile(ToolContext toolContext) { String userId = UUID.randomUUID().toString(); // Save the ID to state for the next tool toolContext.state().put("temp:current_user_id", userId); return Map.of("profile_status", "ID generated"); } // Example: Tool 2 - Uses user ID from state public Map<String, String> getUserOrders(ToolContext toolContext) { String userId = (String) toolContext.state().get("temp:current_user_id"); if (userId == null || userId.isEmpty()) { return Map.of("error", "User ID not found in state"); } System.out.println("Fetching orders for user id: " + userId); // ... logic to fetch orders using userId ... return Map.of("orders", "order123"); }import com.google.adk.kt.tools.ToolContext import java.util.UUID // Example: Tool 1 - Fetches user ID fun getUserProfile(toolContext: ToolContext): Map<String, Any> { val userId = UUID.randomUUID().toString() // Simulate fetching ID // Save the ID to state for the next tool toolContext.updateState("temp:current_user_id", userId) return mapOf("profile_status" to "ID generated") } // Example: Tool 2 - Uses user ID from state fun getUserOrders(toolContext: ToolContext): Map<String, Any> { val userId = toolContext.state["temp:current_user_id"] as? String ?: return mapOf("error" to "User ID not found in state") println("Fetching orders for user ID: $userId") // ... logic to fetch orders using userId ... return mapOf("orders" to listOf("order123", "order456")) } -
사용자 선호도 업데이트:
# Example: Tool or Callback identifies a preference from google.adk.tools import ToolContext # Or Context def set_user_preference(tool_context: ToolContext, preference: str, value: str) -> dict: # Use 'user:' prefix for user-level state (if using a persistent SessionService) state_key = f"user:{preference}" tool_context.state[state_key] = value print(f"Set user preference '{preference}' to '{value}'") return {"status": "Preference updated"}// Pseudocode: Tool or Callback identifies a preference import { Context } from '@google/adk'; function setUserPreference(context: Context, preference: string, value: string): Record<string, string> { // Use 'user:' prefix for user-level state (if using a persistent SessionService) const stateKey = `user:${preference}`; context.state.set(stateKey, value); console.log(`Set user preference '${preference}' to '${value}'`); return { status: 'Preference updated' }; }import "google.golang.org/adk/v2/tool" // Pseudocode: Tool or Callback identifies a preference type setUserPreferenceArgs struct { Preference string `json:"preference" jsonschema:"The name of the preference to set."` Value string `json:"value" jsonschema:"The value to set for the preference."` } type setUserPreferenceResult struct { Status string `json:"status"` } func setUserPreference(tc agent.Context, args setUserPreferenceArgs) (setUserPreferenceResult, error) { // Use 'user:' prefix for user-level state (if using a persistent SessionService) stateKey := fmt.Sprintf("user:%s", args.Preference) if err := tc.State().Set(stateKey, args.Value); err != nil { return setUserPreferenceResult{}, fmt.Errorf("failed to set preference in state: %w", err) } fmt.Printf("Set user preference '%s' to '%s'\n", args.Preference, args.Value) return setUserPreferenceResult{Status: "Preference updated"}, nil }// Example: Tool or Callback identifies a preference import com.google.adk.tools.ToolContext; // Or CallbackContext public Map<String, String> setUserPreference(ToolContext toolContext, String preference, String value) { // Use 'user:' prefix for user-level state (if using a persistent SessionService) String stateKey = "user:" + preference; toolContext.state().put(stateKey, value); System.out.println("Set user preference '" + preference + "' to '" + value + "'"); return Map.of("status", "Preference updated"); }import com.google.adk.kt.tools.ToolContext // Example: Tool or Callback identifies a preference fun setUserPreference( // Or CallbackContext toolContext: ToolContext, preference: String, value: String, ): Map<String, Any> { // Use 'user:' prefix for user-level state (if using a persistent SessionService) val stateKey = "user:$preference" toolContext.updateState(stateKey, value) println("Set user preference '$preference' to '$value'") return mapOf("status" to "Preference updated") } -
상태 접두사: 기본 상태는 세션에만 해당되지만,
app:및user:와 같은 접두사는 영구SessionService구현(DatabaseSessionService또는VertexAiSessionService등)과 함께 사용하여 더 넓은 범위(앱 전체 또는 세션 간 사용자 전체)를 나타낼 수 있습니다.temp:는 현재 호출 내에서만 관련된 데이터를 나타낼 수 있습니다.
아티팩트 작업¶
세션과 관련된 파일이나 큰 데이터 덩어리를 처리하려면 아티팩트를 사용하세요. 일반적인 사용 사례: 업로드된 문서 처리.
-
문서 요약기 예제 흐름:
-
참조 수집 (예: 설정 도구나 콜백에서): 문서의 전체 내용이 아닌 경로나 URI를 아티팩트로 저장합니다.
# Example: In a callback or initial tool from google.adk.agents.context import Context # Or ToolContext from google.genai import types async def save_document_reference(context: Context, file_path: str) -> None: # Assume file_path is something like "gs://my-bucket/docs/report.pdf" or "/local/path/to/report.pdf" try: # Create a Part containing the path/URI text artifact_part = types.Part.from_text(text=file_path) version = await context.save_artifact("document_to_summarize.txt", artifact_part) print(f"Saved document reference '{file_path}' as artifact version {version}") # Store the filename in state if needed by other tools context.state["temp:doc_artifact_name"] = "document_to_summarize.txt" except ValueError as e: print(f"Error saving artifact: {e}") # E.g., Artifact service not configured except Exception as e: print(f"Unexpected error saving artifact reference: {e}") # Example usage: # save_document_reference(context, "gs://my-bucket/docs/report.pdf")// Pseudocode: In a callback or initial tool import { Context } from '@google/adk'; import type { Part } from '@google/genai'; async function saveDocumentReference(context: Context, filePath: string) { // Assume filePath is something like "gs://my-bucket/docs/report.pdf" or "/local/path/to/report.pdf" try { // Create a Part containing the path/URI text const artifactPart: Part = { text: filePath }; const version = await context.saveArtifact('document_to_summarize.txt', artifactPart); console.log(`Saved document reference '${filePath}' as artifact version ${version}`); // Store the filename in state if needed by other tools context.state.set('temp:doc_artifact_name', 'document_to_summarize.txt'); } catch (e) { console.error(`Unexpected error saving artifact reference: ${e}`); } } // Example usage: // saveDocumentReference(context, "gs://my-bucket/docs/report.pdf");import ( "google.golang.org/adk/v2/tool" "google.golang.org/genai" ) // Adapt the saveDocumentReference callback into a tool for this example. type saveDocRefArgs struct { FilePath string `json:"file_path" jsonschema:"The path to the file to save."` } type saveDocRefResult struct { Status string `json:"status"` } func saveDocRef(tc agent.Context, args saveDocRefArgs) (saveDocRefResult, error) { artifactPart := genai.NewPartFromText(args.FilePath) _, err := tc.Artifacts().Save(tc, "document_to_summarize.txt", artifactPart) if err != nil { return saveDocRefResult{}, err } fmt.Printf("Saved document reference '%s' as artifact\n", args.FilePath) if err := tc.State().Set("temp:doc_artifact_name", "document_to_summarize.txt"); err != nil { return saveDocRefResult{}, fmt.Errorf("failed to set artifact name in state") } return saveDocRefResult{"Reference saved"}, nil }// Example: In a callback or initial tool import com.google.adk.agents.CallbackContext; import com.google.genai.types.Content; import com.google.genai.types.Part; import java.util.Optional; public void saveDocumentReference(CallbackContext context, String filePath) { // Assume file_path is something like "gs://my-bucket/docs/report.pdf" or "/local/path/to/report.pdf" try { // Create a Part containing the path/URI text Part artifactPart = Part.fromText(filePath); Optional<Integer> version = context.saveArtifact("document_to_summarize.txt", artifactPart); System.out.println("Saved document reference" + filePath + " as artifact version " + version.orElse(-1)); // Store the filename in state if needed by other tools context.state().put("temp:doc_artifact_name", "document_to_summarize.txt"); } catch (Exception e) { System.out.println("Unexpected error saving artifact reference: " + e); } } // Example usage: // saveDocumentReference(context, "gs://my-bucket/docs/report.pdf")import com.google.adk.kt.agents.CallbackContext import com.google.adk.kt.types.Part // Example: In a callback or initial tool suspend fun saveDocumentReference( // Or ToolContext context: CallbackContext, filePath: String, ) { // Assume filePath is something like "gs://my-bucket/docs/report.pdf" or "/local/path/to/report.pdf" try { // Create a Part containing the path/URI text val artifactPart = Part(text = filePath) val version = context.saveArtifact("document_to_summarize.txt", artifactPart) println("Saved document reference '$filePath' as artifact version $version") // Store the filename in state if needed by other tools context.updateState("temp:doc_artifact_name", "document_to_summarize.txt") } catch (e: IllegalStateException) { println("Error saving artifact: ${e.message}") // E.g., Artifact service not configured } catch (e: Exception) { println("Unexpected error saving artifact reference: $e") } } // Example usage: // saveDocumentReference(context, "gs://my-bucket/docs/report.pdf") -
요약기 도구: 아티팩트를 로드하여 경로/URI를 얻고, 적절한 라이브러리를 사용하여 실제 문서 내용을 읽고, 요약한 후 결과를 반환합니다.
# Example: In the Summarizer tool function from google.adk.tools import ToolContext from google.genai import types # Assume libraries like google.cloud.storage or built-in open are available # Assume a 'summarize_text' function exists # from my_summarizer_lib import summarize_text async def summarize_document_tool(tool_context: ToolContext) -> dict: artifact_name = tool_context.state.get("temp:doc_artifact_name") if not artifact_name: return {"error": "Document artifact name not found in state."} try: # 1. Load the artifact part containing the path/URI artifact_part = await tool_context.load_artifact(artifact_name) if not artifact_part or not artifact_part.text: return {"error": f"Could not load artifact or artifact has no text path: {artifact_name}"} file_path = artifact_part.text print(f"Loaded document reference: {file_path}") # 2. Read the actual document content (outside ADK context) document_content = "" if file_path.startswith("gs://"): # Example: Use GCS client library to download/read pass # Replace with actual GCS reading logic elif file_path.startswith("/"): # Example: Use local file system with open(file_path, 'r', encoding='utf-8') as f: document_content = f.read() else: return {"error": f"Unsupported file path scheme: {file_path}"} # 3. Summarize the content if not document_content: return {"error": "Failed to read document content."} # summary = summarize_text(document_content) # Call your summarization logic summary = f"Summary of content from {file_path}" # Placeholder return {"summary": summary} except ValueError as e: return {"error": f"Artifact service error: {e}"} except FileNotFoundError: return {"error": f"Local file not found: {file_path}"}// Pseudocode: In the Summarizer tool function import { Context } from '@google/adk'; async function summarizeDocumentTool(context: Context): Promise<Record<string, string>> { const artifactName = context.state.get('temp:doc_artifact_name') as string; if (!artifactName) { return { error: 'Document artifact name not found in state.' }; } try { // 1. Load the artifact part containing the path/URI const artifactPart = await context.loadArtifact(artifactName); if (!artifactPart?.text) { return { error: `Could not load artifact or artifact has no text path: ${artifactName}` }; } const filePath = artifactPart.text; console.log(`Loaded document reference: ${filePath}`); // 2. Read the actual document content (outside ADK context) let documentContent = ''; if (filePath.startsWith('gs://')) { // Example: Use GCS client library to download/read // const storage = new Storage(); // const bucket = storage.bucket('my-bucket'); // const file = bucket.file(filePath.replace('gs://my-bucket/', '')); // const [contents] = await file.download(); // documentContent = contents.toString(); } else if (filePath.startsWith('/')) { // Example: Use local file system // import { readFile } from 'fs/promises'; // documentContent = await readFile(filePath, 'utf8'); } else { return { error: `Unsupported file path scheme: ${filePath}` }; } // 3. Summarize the content if (!documentContent) { return { error: 'Failed to read document content.' }; } // const summary = summarizeText(documentContent); // Call your summarization logic const summary = `Summary of content from ${filePath}`; // Placeholder return { summary }; } catch (e) { return { error: `Error processing artifact: ${e}` }; } }import "google.golang.org/adk/v2/tool" // Pseudocode: In the Summarizer tool function type summarizeDocumentArgs struct{} type summarizeDocumentResult struct { Summary string `json:"summary"` } func summarizeDocumentTool(tc agent.Context, input summarizeDocumentArgs) (summarizeDocumentResult, error) { artifactName, err := tc.State().Get("temp:doc_artifact_name") if err != nil { return summarizeDocumentResult{}, fmt.Errorf("No document artifact name found in state") } // 1. Load the artifact part containing the path/URI artifactPart, err := tc.Artifacts().Load(tc, artifactName.(string)) if err != nil { return summarizeDocumentResult{}, err } if artifactPart.Part.Text == "" { return summarizeDocumentResult{}, fmt.Errorf("Could not load artifact or artifact has no text path.") } filePath := artifactPart.Part.Text fmt.Printf("Loaded document reference: %s\n", filePath) // 2. Read the actual document content (outside ADK context) // In a real implementation, you would use a GCS client or local file reader. documentContent := "This is the fake content of the document at " + filePath _ = documentContent // Avoid unused variable error. // 3. Summarize the content summary := "Summary of content from " + filePath // Placeholder return summarizeDocumentResult{Summary: summary}, nil }// Example: In the Summarizer tool function import com.google.adk.tools.ToolContext; import com.google.genai.types.Content; import com.google.genai.types.Part; import java.util.Map; import java.util.Optional; import java.io.FileNotFoundException; public Map<String, String> summarizeDocumentTool(ToolContext toolContext) { String artifactName = (String) toolContext.state().get("temp:doc_artifact_name"); if (artifactName == null || artifactName.isEmpty()) { return Map.of("error", "Document artifact name not found in state."); } try { // 1. Load the artifact part containing the path/URI Optional<Part> artifactPart = toolContext.loadArtifact(artifactName); if (!artifactPart.isPresent() || !artifactPart.get().text().isPresent() || artifactPart.get().text().get().isEmpty()) { return Map.of("error", "Could not load artifact or artifact has no text path: " + artifactName); } String filePath = artifactPart.get().text().get(); System.out.println("Loaded document reference: " + filePath); // 2. Read the actual document content (outside ADK context) String documentContent = ""; if (filePath.startsWith("gs://")) { // Example: Use GCS client library to download/read into documentContent // Replace with actual GCS reading logic } else if (filePath.startsWith("/")) { // Example: Use local file system to download/read into documentContent } else { return Map.of("error", "Unsupported file path scheme: " + filePath); } // 3. Summarize the content if (documentContent.isEmpty()) { return Map.of("error", "Failed to read document content."); } // summary = summarizeText(documentContent) // Call your summarization logic String summary = "Summary of content from " + filePath; // Placeholder return Map.of("summary", summary); } catch (IllegalArgumentException e) { return Map.of("error", "Artifact service error " + e); } catch (Exception e) { return Map.of("error", "Error reading document " + e); } }import com.google.adk.kt.tools.ToolContext import java.io.File import java.io.FileNotFoundException // Example: In the Summarizer tool function // Assume a GCS client library is available // Assume a summarizeText function exists suspend fun summarizeDocumentTool(toolContext: ToolContext): Map<String, Any> { val artifactName = toolContext.state["temp:doc_artifact_name"] as? String ?: return mapOf("error" to "Document artifact name not found in state.") // 1. Load the artifact part containing the path/URI // Returns null if no artifact service is configured or the artifact is not found val artifactPart = toolContext.loadArtifact(artifactName) val filePath = artifactPart?.text ?: return mapOf( "error" to "Could not load artifact or artifact has no text path: $artifactName", ) println("Loaded document reference: $filePath") try { // 2. Read the actual document content (outside ADK context) var documentContent = "" if (filePath.startsWith("gs://")) { // Example: Use GCS client library to download/read // Replace with actual GCS reading logic } else if (filePath.startsWith("/")) { // Example: Use local file system documentContent = File(filePath).readText(Charsets.UTF_8) } else { return mapOf("error" to "Unsupported file path scheme: $filePath") } // 3. Summarize the content if (documentContent.isEmpty()) { return mapOf("error" to "Failed to read document content.") } // val summary = summarizeText(documentContent) // Call your summarization logic val summary = "Summary of content from $filePath" // Placeholder return mapOf("summary" to summary) } catch (e: FileNotFoundException) { return mapOf("error" to "Local file not found: $filePath") } }
-
-
아티팩트 목록 조회: 사용 가능한 파일이 무엇인지 확인합니다.
# Example: In a tool function from google.adk.tools import ToolContext async def check_available_docs(tool_context: ToolContext) -> dict: try: artifact_keys = await tool_context.list_artifacts() print(f"Available artifacts: {artifact_keys}") return {"available_docs": artifact_keys} except ValueError as e: return {"error": f"Artifact service error: {e}"}// Pseudocode: In a tool function import { Context } from '@google/adk'; async function checkAvailableDocs(context: Context): Promise<Record<string, string[] | string>> { try { const artifactKeys = await context.listArtifacts(); console.log(`Available artifacts: ${artifactKeys}`); return { available_docs: artifactKeys }; } catch (e) { return { error: `Artifact service error: ${e}` }; } }import "google.golang.org/adk/v2/tool" // Pseudocode: In a tool function type checkAvailableDocsArgs struct{} type checkAvailableDocsResult struct { AvailableDocs []string `json:"available_docs"` } func checkAvailableDocs(tc agent.Context, args checkAvailableDocsArgs) (checkAvailableDocsResult, error) { artifactKeys, err := tc.Artifacts().List(tc) if err != nil { return checkAvailableDocsResult{}, err } fmt.Printf("Available artifacts: %v\n", artifactKeys) return checkAvailableDocsResult{AvailableDocs: artifactKeys.FileNames}, nil }// Example: In a tool function import com.google.adk.tools.ToolContext; import io.reactivex.rxjava3.core.Single; import java.util.List; import java.util.Map; public Map<String, Object> checkAvailableDocs(ToolContext toolContext) { try { Single<List<String>> artifactKeys = toolContext.listArtifacts(); System.out.println("Available artifacts: " + artifactKeys.blockingGet().toString()); return Map.of("availableDocs", artifactKeys.blockingGet()); } catch (IllegalArgumentException e) { return Map.of("error", "Artifact service error: " + e); } }import com.google.adk.kt.tools.ToolContext // Example: In a tool function suspend fun checkAvailableDocs(toolContext: ToolContext): Map<String, Any> { // Returns an empty list if no artifact service is configured val artifactKeys = toolContext.listArtifacts() println("Available artifacts: $artifactKeys") return mapOf("available_docs" to artifactKeys) }
도구 인증 처리¶
도구에 필요한 API 키나 다른 자격 증명을 안전하게 관리합니다.
# Example: Tool requiring auth
from google.adk.tools import ToolContext
from google.adk.auth import AuthConfig # Assume appropriate AuthConfig is defined
# Define your required auth configuration (e.g., OAuth, API Key)
MY_API_AUTH_CONFIG = AuthConfig(...)
AUTH_STATE_KEY = "user:my_api_credential" # Key to store retrieved credential
def call_secure_api(tool_context: ToolContext, request_data: str) -> dict:
# 1. Check if credential already exists in state
credential = tool_context.state.get(AUTH_STATE_KEY)
if not credential:
# 2. If not, request it
print("Credential not found, requesting...")
try:
tool_context.request_credential(MY_API_AUTH_CONFIG)
# The framework handles yielding the event. The tool execution stops here for this turn.
return {"status": "Authentication required. Please provide credentials."}
except ValueError as e:
return {"error": f"Auth error: {e}"} # e.g., function_call_id missing
except Exception as e:
return {"error": f"Failed to request credential: {e}"}
# 3. If credential exists (might be from a previous turn after request)
# or if this is a subsequent call after auth flow completed externally
try:
# Optionally, re-validate/retrieve if needed, or use directly
# This might retrieve the credential if the external flow just completed
auth_credential_obj = tool_context.get_auth_response(MY_API_AUTH_CONFIG)
api_key = auth_credential_obj.api_key # Or access_token, etc.
# Store it back in state for future calls within the session
tool_context.state[AUTH_STATE_KEY] = auth_credential_obj.model_dump() # Persist retrieved credential
print(f"Using retrieved credential to call API with data: {request_data}")
# ... Make the actual API call using api_key ...
api_result = f"API result for {request_data}"
return {"result": api_result}
except Exception as e:
# Handle errors retrieving/using the credential
print(f"Error using credential: {e}")
# Maybe clear the state key if credential is invalid?
# tool_context.state[AUTH_STATE_KEY] = None
return {"error": "Failed to use credential"}
// Pseudocode: Tool requiring auth
import { Context } from '@google/adk'; // AuthConfig from ADK or custom
// Define a local AuthConfig interface as it's not publicly exported by ADK
interface AuthConfig {
credentialKey: string;
authScheme: { type: string }; // Minimal representation for the example
// Add other properties if they become relevant for the example
}
// Define your required auth configuration (e.g., OAuth, API Key)
const MY_API_AUTH_CONFIG: AuthConfig = {
credentialKey: 'my-api-key', // Example key
authScheme: { type: 'api-key' }, // Example scheme type
};
const AUTH_STATE_KEY = 'user:my_api_credential'; // Key to store retrieved credential
async function callSecureApi(context: Context, requestData: string): Promise<Record<string, string>> {
// 1. Check if credential already exists in state
const credential = context.state.get(AUTH_STATE_KEY);
if (!credential) {
// 2. If not, request it
console.log('Credential not found, requesting...');
try {
context.requestCredential(MY_API_AUTH_CONFIG);
// The framework handles yielding the event. The tool execution stops here for this turn.
return { status: 'Authentication required. Please provide credentials.' };
} catch (e) {
return { error: `Auth or credential request error: ${e}` };
}
}
// 3. If credential exists (might be from a previous turn after request)
// or if this is a subsequent call after auth flow completed externally
try {
// Optionally, re-validate/retrieve if needed, or use directly
// This might retrieve the credential if the external flow just completed
const authCredentialObj = context.getAuthResponse(MY_API_AUTH_CONFIG);
const apiKey = authCredentialObj?.apiKey; // Or accessToken, etc.
// Store it back in state for future calls within the session
// Note: In strict TS, might need to cast or serialize authCredentialObj
context.state.set(AUTH_STATE_KEY, JSON.stringify(authCredentialObj));
console.log(`Using retrieved credential to call API with data: ${requestData}`);
// ... Make the actual API call using apiKey ...
const apiResult = `API result for ${requestData}`;
return { result: apiResult };
} catch (e) {
// Handle errors retrieving/using the credential
console.error(`Error using credential: ${e}`);
// Maybe clear the state key if credential is invalid?
// toolContext.state.set(AUTH_STATE_KEY, null);
return { error: 'Failed to use credential' };
}
}
// Example: Tool requiring auth
import com.google.adk.tools.ToolContext;
import java.util.Map;
// Note: AuthConfig, requestCredential, and getAuthResponse are not yet
// fully implemented in the Java ADK public API.
// This example relies on external auth population into the session state.
public class SecureApiTool {
private static final String AUTH_STATE_KEY = "user:my_api_credential";
public Map<String, String> callSecureApi(ToolContext context, String requestData) {
// 1. Check if credential already exists in state
Object credential = context.state().get(AUTH_STATE_KEY);
if (credential == null) {
// 2. If not, request it
System.out.println("Credential not found, requesting...");
try {
// context.requestCredential(MY_API_AUTH_CONFIG); // Not yet implemented in Java ADK
// The framework handles yielding the event. The tool execution stops here for this turn.
return Map.of("status", "Authentication required. Please provide credentials.");
} catch (Exception e) {
return Map.of("error", "Auth or credential request error: " + e.getMessage());
}
}
// 3. If credential exists (might be from a previous turn after request)
// or if this is a subsequent call after auth flow completed externally
try {
// Optionally, re-validate/retrieve if needed, or use directly
// String apiKey = context.getAuthResponse(MY_API_AUTH_CONFIG).getApiKey();
String apiKey = credential.toString(); // Simplified for example
// Store it back in state for future calls within the session
context.state().put(AUTH_STATE_KEY, apiKey);
System.out.println("Using retrieved credential to call API with data: " + requestData);
// ... Make the actual API call using apiKey ...
String apiResult = "API result for " + requestData;
return Map.of("result", apiResult);
} catch (Exception e) {
// Handle errors retrieving/using the credential
System.err.println("Error using credential: " + e.getMessage());
return Map.of("error", "Failed to use credential");
}
}
}
기억하세요: request_credential은 도구를 일시 중지시키고 인증 필요성을 알립니다. 사용자/시스템이 자격 증명을 제공하면, 후속 호출에서 get_auth_response(또는 상태를 다시 확인)를 통해 도구가 계속 진행할 수 있습니다. tool_context.function_call_id는 프레임워크에 의해 요청과 응답을 연결하는 데 암묵적으로 사용됩니다.
메모리 활용¶
과거 또는 외부 소스에서 관련 정보에 접근합니다.
# Example: Tool using memory search
from google.adk.tools import ToolContext
async def find_related_info(tool_context: ToolContext, topic: str) -> dict:
try:
search_results = await tool_context.search_memory(f"Information about {topic}")
if search_results.memories:
print(f"Found {len(search_results.memories)} memory results for '{topic}'")
# Process search_results.memories (which are MemoryEntry objects)
top_entry = search_results.memories[0]
top_result_text = next(
(part.text for part in (top_entry.content.parts or []) if part.text),
"",
)
return {"memory_snippet": top_result_text}
else:
return {"message": "No relevant memories found."}
except ValueError as e:
return {"error": f"Memory service error: {e}"} # e.g., Service not configured
except Exception as e:
return {"error": f"Unexpected error searching memory: {e}"}
// Pseudocode: Tool using memory search
import { Context } from '@google/adk';
async function findRelatedInfo(context: Context, topic: string): Promise<Record<string, string>> {
try {
const searchResults = await context.searchMemory(`Information about ${topic}`);
if (searchResults.memories.length) {
console.log(`Found ${searchResults.memories.length} memory results for '${topic}'`);
// Process searchResults.memories
const topResultText =
searchResults.memories[0].content.parts?.[0]?.text ?? '';
return { memory_snippet: topResultText };
} else {
return { message: 'No relevant memories found.' };
}
} catch (e) {
return { error: `Memory service error: ${e}` }; // e.g., Service not configured
}
}
// Example: Tool using memory search
import com.google.adk.tools.ToolContext;
import com.google.adk.memory.SearchMemoryResponse;
import io.reactivex.rxjava3.core.Single;
import java.util.Map;
public class MemorySearchTool {
public Single<Map<String, String>> findRelatedInfo(ToolContext context, String topic) {
return context.searchMemory("Information about " + topic)
.map(searchResults -> {
if (searchResults != null && !searchResults.memories().isEmpty()) {
System.out.println("Found " + searchResults.memories().size() + " memory results for '" + topic + "'");
// Process searchResults.memories
String topResultText =
searchResults.memories().get(0).content().text();
return Map.of("memory_snippet", topResultText);
} else {
return Map.of("message", "No relevant memories found.");
}
})
.onErrorReturnItem(Map.of("error", "Memory service error"));
}
}
import com.google.adk.kt.tools.ToolContext
// Example: Tool using memory search
suspend fun findRelatedInfo(
toolContext: ToolContext,
topic: String,
): Map<String, String> {
val memoryService =
toolContext.memoryService
?: return mapOf("error" to "Memory service error: not configured")
return try {
val searchResults =
memoryService.searchMemory(
appName = toolContext.session.key.appName,
userId = toolContext.userId,
query = "Information about $topic",
)
if (searchResults.memories.isNotEmpty()) {
println("Found ${searchResults.memories.size} memory results for '$topic'")
// Process searchResults.memories (which are MemoryEntry objects)
val topEntry = searchResults.memories[0]
val topResultText = topEntry.content.parts.firstNotNullOfOrNull { it.text } ?: ""
mapOf("memory_snippet" to topResultText)
} else {
mapOf("message" to "No relevant memories found.")
}
} catch (e: Exception) {
mapOf("error" to "Unexpected error searching memory: $e")
}
}
UI 위젯 렌더링¶
에이전트 응답과 함께 풍부한 UI 구성요소(예: MCP 앱 iframe)를 클라이언트로 전송하려면 context.render_ui_widget()을 사용하세요.
from google.adk.events.ui_widget import UiWidget
from google.adk.tools import ToolContext
def render_styled_widget(color: str, context: ToolContext) -> str:
"""Render a UI widget utilizing the user-specified color."""
widget = UiWidget(
id="my_status_dashboard",
provider="mcp",
payload={
"resource_uri": "ui://analytics/status",
"tool": {"name": "get_system_status"},
"tool_args": {"theme_color": color} # Dynamically passed from user interaction
}
)
context.render_ui_widget(widget)
return f"Widget successfully rendered with color: {color}"
고급: 직접적인 InvocationContext 사용¶
대부분의 상호작용은 CallbackContext 또는 ToolContext를 통해 이루어지지만, 때로는 에이전트의 핵심 로직(Python의 _run_async_impl 또는 _run_live_impl, TypeScript, Java, Kotlin의 runAsyncImpl 등)에서 직접 액세스해야 할 때가 있습니다.
# Example: Inside agent's _run_async_impl
from google.adk.agents import BaseAgent
from google.adk.agents.invocation_context import InvocationContext
from google.adk.events import Event
from google.genai import types
from typing import AsyncGenerator
class MyControllingAgent(BaseAgent):
async def _run_async_impl(self, ctx: InvocationContext) -> AsyncGenerator[Event, None]:
# Example: Check if a specific service is available
if not ctx.memory_service:
print("Memory service is not available for this invocation.")
# Potentially change agent behavior
# Example: Early termination based on some condition
if ctx.session.state.get("critical_error_flag"):
print("Critical error detected, ending invocation.")
ctx.end_invocation = True # Signal framework to stop processing
yield Event(
author=self.name,
invocation_id=ctx.invocation_id,
content=types.Content(
role="model",
parts=[types.Part(text="Stopping due to critical error.")],
),
)
return # Stop this agent's execution
# ... Normal agent processing ...
yield # ... event ...
// Pseudocode: Inside agent's runAsyncImpl
import { BaseAgent, InvocationContext } from '@google/adk';
import type { Event } from '@google/adk';
class MyControllingAgent extends BaseAgent {
async *runAsyncImpl(ctx: InvocationContext): AsyncGenerator<Event, void, undefined> {
// Example: Check if a specific service is available
if (!ctx.memoryService) {
console.log('Memory service is not available for this invocation.');
// Potentially change agent behavior
}
// Example: Early termination based on some condition
// Direct access to state via ctx.session.state or through ctx.session.state property if wrapped
if ((ctx.session.state as { 'critical_error_flag': boolean })['critical_error_flag']) {
console.log('Critical error detected, ending invocation.');
ctx.endInvocation = true; // Signal framework to stop processing
yield {
author: this.name,
invocationId: ctx.invocationId,
content: { parts: [{ text: 'Stopping due to critical error.' }] }
} as Event;
return; // Stop this agent's execution
}
// ... Normal agent processing ...
yield; // ... event ...
}
}
// Example: Inside agent's runAsyncImpl
import com.google.adk.agents.BaseAgent;
import com.google.adk.agents.InvocationContext;
import com.google.adk.events.Event;
import com.google.genai.types.Content;
import com.google.genai.types.Part;
import io.reactivex.rxjava3.core.Flowable;
import java.util.List;
public class MyControllingAgent extends BaseAgent {
@Override
protected Flowable<Event> runAsyncImpl(InvocationContext ctx) {
// Example: Check if a specific service is available
if (ctx.memoryService() == null) {
System.out.println("Memory service is not available for this invocation.");
// Potentially change agent behavior
}
// Example: Early termination based on some condition
Boolean criticalError = (Boolean) ctx.session().state().getOrDefault("critical_error_flag", false);
if (criticalError != null && criticalError) {
System.out.println("Critical error detected, ending invocation.");
ctx.setEndInvocation(true); // Signal framework to stop processing
Event errorEvent = Event.builder()
.author(name())
.invocationId(ctx.invocationId())
.content(Content.builder().parts(List.of(Part.builder().text("Stopping due to critical error.").build())).build())
.build();
return Flowable.just(errorEvent); // Stop this agent's execution
}
// ... Normal agent processing ...
// return Flowable.just(normalEvent);
return Flowable.empty();
}
}
import com.google.adk.kt.agents.BaseAgent
import com.google.adk.kt.agents.InvocationContext
import com.google.adk.kt.events.Event
import com.google.adk.kt.types.Content
import com.google.adk.kt.types.Part
import com.google.adk.kt.types.Role
import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.flow.flow
// Example: Inside agent's runAsyncImpl
class MyControllingAgent(
name: String,
) : BaseAgent(name = name) {
override fun runAsyncImpl(context: InvocationContext): Flow<Event> =
flow {
// Example: Check if a specific service is available
if (context.memoryService == null) {
println("Memory service is not available for this invocation.")
// Potentially change agent behavior
}
// Example: Early termination based on some condition
if (context.session.state["critical_error_flag"] == true) {
println("Critical error detected, ending invocation.")
context.isEndOfInvocation = true // Signal framework to stop processing
emit(
Event(
author = name,
invocationId = context.invocationId,
content =
Content(
role = Role.MODEL,
parts = listOf(Part(text = "Stopping due to critical error.")),
),
),
)
return@flow // Stop this agent's execution
}
// ... Normal agent processing ...
// emit(...) // ... event ...
}
}
호출 종료 플래그를 True로 설정하는 것은 에이전트 또는 해당 콜백이나 도구 내부에서(기본 InvocationContext의 플래그를 수정할 수 있는 각각의 컨텍스트 객체를 통해) 전체 요청-응답 주기를 정상적으로 중단하는 방법입니다. 구체적으로 Python에서는 ctx.end_invocation = True, TypeScript에서는 ctx.endInvocation = true, Java에서는 ctx.setEndInvocation(true), Kotlin에서는 context.isEndOfInvocation = true 또는 context.endInvocation()을 사용하세요.
핵심 요약 및 모범 사례¶
- 올바른 컨텍스트 사용: 항상 제공되는 가장 구체적인 컨텍스트 객체를 사용하세요(
ToolContext는 도구/도구-콜백에서,CallbackContext는 에이전트/모델-콜백에서,ReadonlyContext는 해당되는 곳에서). 전체InvocationContext(ctx)는_run_async_impl/_run_live_impl에서 꼭 필요할 때만 직접 사용하세요. - 데이터 흐름을 위한 상태:
context.state는 호출 내에서 데이터를 공유하고, 선호도를 기억하며, 대화 메모리를 관리하는 주요 방법입니다. 영구 저장소를 사용할 때는 접두사(app:,user:,temp:)를 신중하게 사용하세요. - 파일을 위한 아티팩트: 파일 참조(경로나 URI 등)나 큰 데이터 덩어리를 관리할 때는
context.save_artifact와context.load_artifact를 사용하세요. 참조를 저장하고, 필요할 때 내용을 로드하세요. - 추적되는 변경 사항: 컨텍스트 메서드를 통해 상태나 아티팩트를 수정하면 현재 단계의
EventActions에 자동으로 연결되고SessionService에 의해 처리됩니다. - UI 렌더링:
context.render_ui_widget(widget)을 사용하여 풍부한 UI 구성요소(예: MCP 앱 iframe)를 클라이언트로 전송하세요. - 단순하게 시작: 먼저
state와 기본적인 아티팩트 사용에 집중하세요. 필요가 더 복잡해지면 인증, 메모리, 그리고 고급InvocationContext필드(라이브 스트리밍용 필드 등)를 탐색하세요.
이러한 컨텍스트 객체를 이해하고 효과적으로 사용함으로써 ADK로 더 정교하고, 상태를 유지하며, 유능한 에이전트를 구축할 수 있습니다.