com.coze.loop.client

Interface CozeLoopClient

All Superinterfaces:

AutoCloseable

All Known Implementing Classes:

CozeLoopClientImpl

public interface CozeLoopClient
extends AutoCloseable

Main interface for CozeLoop SDK client. Provides trace and prompt functionality.

Method Summary

Modifier and Type	Method and Description
void	close() Close the client (alias for shutdown).
ExecuteResult	execute(ExecuteParam param) Execute a prompt.
StreamReader<ExecuteResult>	executeStreaming(ExecuteParam param) Execute a prompt with streaming response.
CozeLoopContext	extractContext(Map<String,String> headers) Extract context from headers for cross-service propagation.
void	flush() Flush all pending spans to the backend.
List<Message>	formatPrompt(Prompt prompt, Map<String,Object> variables) Format a prompt with variables.
List<Message>	getAndFormatPrompt(GetPromptParam param, Map<String,Object> variables) Get and format a prompt in one call.
Prompt	getPrompt(GetPromptParam param) Get a prompt from the platform.
String	getWorkspaceId() Get the workspace ID.
void	invalidatePromptCache(GetPromptParam param) Invalidate cached prompt.
void	shutdown() Shutdown the client and release resources.
CozeLoopSpan	startSpan(String name) Start a new span with default type "custom".
CozeLoopSpan	startSpan(String name, String spanType) Start a new span with specified type.
CozeLoopSpan	startSpan(String name, String spanType, CozeLoopContext parentContext) Start a new span with specified type and parent context.
CozeLoopSpan	startSpan(String name, String spanType, CozeLoopContext parentContext, String scene)
CozeLoopSpan	startSpan(String name, String spanType, CozeLoopSpan parentSpan) Start a new span with specified type.
CozeLoopSpan	startSpan(String name, String spanType, CozeLoopSpan parentSpan, String scene)
CozeLoopSpan	startSpan(String name, String spanType, String scene)

Method Detail

startSpan

CozeLoopSpan startSpan(String name)

Start a new span with default type "custom".

Parameters:

name - the span name

Returns:

the span wrapper

startSpan

CozeLoopSpan startSpan(String name,
                       String spanType)

Start a new span with specified type.

Parameters:

name - the span name

spanType - the span type (e.g., "llm", "tool", "custom")

Returns:

the span wrapper

startSpan

CozeLoopSpan startSpan(String name,
                       String spanType,
                       String scene)

startSpan

CozeLoopSpan startSpan(String name,
                       String spanType,
                       CozeLoopSpan parentSpan)

Start a new span with specified type.

Parameters:

name - the span name

spanType - the span type (e.g., "llm", "tool", "custom")

Returns:

the span wrapper

startSpan

CozeLoopSpan startSpan(String name,
                       String spanType,
                       CozeLoopSpan parentSpan,
                       String scene)

startSpan

CozeLoopSpan startSpan(String name,
                       String spanType,
                       CozeLoopContext parentContext)

Start a new span with specified type and parent context. Useful for cross-service tracing where you have an extracted Context.

Parameters:

name - the span name

spanType - the span type

parentContext - the parent context

Returns:

the span wrapper

startSpan

CozeLoopSpan startSpan(String name,
                       String spanType,
                       CozeLoopContext parentContext,
                       String scene)

extractContext

CozeLoopContext extractContext(Map<String,String> headers)

Extract context from headers for cross-service propagation.

Parameters:

headers - the map of headers (e.g. from an incoming HTTP request)

Returns:

the extracted context

getPrompt

Prompt getPrompt(GetPromptParam param)

Get a prompt from the platform.

Parameters:

param - the parameters for getting prompt

Returns:

prompt

formatPrompt

List<Message> formatPrompt(Prompt prompt,
                           Map<String,Object> variables)

Format a prompt with variables.

Parameters:

prompt - the prompt to format

variables - the variables to substitute

Returns:

formatted messages

getAndFormatPrompt

List<Message> getAndFormatPrompt(GetPromptParam param,
                                 Map<String,Object> variables)

Get and format a prompt in one call.

Parameters:

param - the parameters for getting prompt

variables - the variables to substitute

Returns:

formatted messages

invalidatePromptCache

void invalidatePromptCache(GetPromptParam param)

Invalidate cached prompt.

Parameters:

param - the parameters identifying the prompt

execute

ExecuteResult execute(ExecuteParam param)

Execute a prompt.

Parameters:

param - the execution parameters

Returns:

the execution result

executeStreaming

StreamReader<ExecuteResult> executeStreaming(ExecuteParam param)

Execute a prompt with streaming response.

Parameters:

param - the execution parameters

Returns:

stream reader for ExecuteResult

getWorkspaceId

String getWorkspaceId()

Get the workspace ID.

Returns:

workspace ID

flush

void flush()

Flush all pending spans to the backend.

shutdown

void shutdown()

Shutdown the client and release resources. This method flushes all pending spans and closes HTTP connections.

close

void close()

Close the client (alias for shutdown).

Specified by:

close in interface AutoCloseable