Class LangfuseAgent

Specialized observation wrapper for tracking AI agent workflows and autonomous operations.

LangfuseAgent is designed for observing intelligent agent systems that combine reasoning, tool usage, memory management, and decision-making in autonomous workflows. It captures the complex multi-step nature of agent operations, including planning, execution, and self-correction cycles typical in advanced AI agent architectures.

Primary Use Cases

Autonomous AI Agents: ReAct, AutoGPT, LangGraph agent implementations
Tool-Using Agents: Function calling agents with external API access
Multi-Step Reasoning: Chain-of-thought, tree-of-thought agent workflows
Planning Agents: Goal decomposition and task planning systems
Conversational Agents: Multi-turn dialogue agents with memory
Code Generation Agents: AI assistants that write, test, and debug code

Key Features

Multi-Step Tracking: Captures entire agent workflow from planning to execution
Tool Integration: Records all tool calls and their results within agent context
Decision Logic: Tracks reasoning steps, decisions, and strategy adaptations
Memory Management: Observes how agents maintain and use context across steps
Error Recovery: Monitors how agents handle failures and adapt their approach
Performance Metrics: Measures agent efficiency, success rates, and resource usage

Agent-Specific Patterns

Planning Phase: Initial goal analysis and strategy formulation
Execution Loop: Iterative action-observation-reasoning cycles
Tool Selection: Dynamic tool choice based on context and goals
Self-Correction: Error detection and strategy adjustment
Memory Updates: Context retention and knowledge accumulation
Final Synthesis: Result compilation and quality assessment

Example

// Basic agent workflow
const agent = startObservation('research-agent', {
  input: {
    task: 'Research renewable energy trends',
    tools: ['web-search', 'summarizer'],
    maxIterations: 3
  }
}, { asType: 'agent' });

// Agent uses tools and makes decisions
const searchTool = agent.startObservation('web-search', {
  input: { query: 'renewable energy 2024' }
}, { asType: 'tool' });

const results = await webSearch('renewable energy 2024');
searchTool.update({ output: results });
searchTool.end();

// Agent generates final response
const generation = agent.startObservation('synthesize-findings', {
  input: results,
  model: 'gpt-4'
}, { asType: 'generation' });

const response = await llm.generate(results);
generation.update({ output: response });
generation.end();

agent.update({
  output: {
    completed: true,
    toolsUsed: 1,
    finalResponse: response
  }
});
agent.end();

See

startObservation with { asType: 'agent' } - Factory function
startActiveObservation with { asType: 'agent' } - Function-scoped agent
LangfuseTool - For individual tool executions within agents
LangfuseChain - For structured multi-step workflows

Hierarchy

LangfuseBaseObservation
- LangfuseAgent

Index

Constructors

constructor

new LangfuseAgent(params: LangfuseAgentParams): LangfuseAgent
Parameters
- params: LangfuseAgentParams
Returns LangfuseAgent
Overrides LangfuseBaseObservation.constructor
- Defined in tracing/src/spanWrapper.ts:647

Properties

id

id: string

The span ID from the OpenTelemetry span context

`Readonly`otelSpan

otelSpan: Span

The underlying OpenTelemetry span

traceId

traceId: string

The trace ID from the OpenTelemetry span context

`Readonly`type

type: LangfuseObservationType

The underlying OpenTelemetry span

Accessors

`Protected`tracer

get tracer(): Tracer
Gets the Langfuse OpenTelemetry tracer instance

Returns Tracer
Inherited from LangfuseBaseObservation.tracer
- Defined in tracing/src/spanWrapper.ts:175

Methods

end

end(endTime?: TimeInput): void
Ends the observation, marking it as complete.
Parameters
- OptionalendTime: TimeInput
  Optional end time, defaults to current time
Returns void
Inherited from LangfuseBaseObservation.end
- Defined in tracing/src/spanWrapper.ts:184

startObservation

startObservation(
    name: string,
    attributes: LangfuseGenerationAttributes,
    options: { asType: "generation" },
): LangfuseGeneration

Creates a new child observation within this observation's context with full type safety.

This method enables hierarchical tracing by creating child observations that inherit the parent's trace context. It supports all observation types with automatic TypeScript type inference based on the asType parameter, ensuring compile-time safety for attributes and return types.

Hierarchy & Context

Child observations automatically inherit the parent's trace ID and span context
Creates proper parent-child relationships in the trace structure
Enables distributed tracing across nested operations
Maintains correlation between related operations

Type Safety

Return type is automatically inferred from asType parameter
Attributes parameter is type-checked based on observation type
Compile-time validation prevents type mismatches
Full IntelliSense support for observation-specific attributes

Parameters

name: string
Descriptive name for the child observation
attributes: LangfuseGenerationAttributes
Type-specific attributes (varies by observation type)
options: { asType: "generation" }
Configuration including observation type (defaults to 'span')

Returns LangfuseGeneration

Strongly-typed observation instance based on asType

Example

// Within any observation (span, generation, agent, etc.)
const parentObservation = startObservation('ai-workflow');

// Create child span (default)
const dataProcessing = parentObservation.startObservation('data-processing', {
  input: { userId: '123', dataSize: 1024 },
  metadata: { processor: 'fast-lane', version: '2.1' }
}); // Returns LangfuseSpan

// Create child generation with full LLM attributes
const llmCall = parentObservation.startObservation('openai-gpt-4', {
  input: [{ role: 'system', content: 'You are a helpful assistant' },
          { role: 'user', content: 'Explain machine learning' }],
  model: 'gpt-4-turbo',
  modelParameters: {
    temperature: 0.7,
    maxTokens: 500,
    topP: 1.0
  },
  metadata: { priority: 'high', timeout: 30000 }
}, { asType: 'generation' }); // Returns LangfuseGeneration

// Create child agent for complex reasoning
const reasoningAgent = parentObservation.startObservation('reasoning-agent', {
  input: {
    task: 'Analyze market trends',
    context: 'Q4 2024 financial data'
  },
  metadata: {
    model: 'gpt-4',
    tools: ['calculator', 'web-search', 'data-analysis'],
    maxIterations: 5
  }
}, { asType: 'agent' }); // Returns LangfuseAgent

// Create child tool for external API calls
const apiCall = reasoningAgent.startObservation('market-data-api', {
  input: {
    endpoint: '/market/trends',
    params: { symbol: 'AAPL', period: '1Y' }
  },
  metadata: {
    provider: 'alpha-vantage',
    rateLimit: 5,
    timeout: 10000
  }
}, { asType: 'tool' }); // Returns LangfuseTool

// Create child retriever for document search
const docSearch = parentObservation.startObservation('document-retrieval', {
  input: {
    query: 'sustainable energy solutions',
    filters: { year: '2024', category: 'research' },
    topK: 10
  },
  metadata: {
    vectorStore: 'pinecone',
    embeddingModel: 'text-embedding-ada-002',
    similarity: 'cosine'
  }
}, { asType: 'retriever' }); // Returns LangfuseRetriever

// Create child evaluator for quality assessment
const qualityCheck = parentObservation.startObservation('response-evaluator', {
  input: {
    response: llmCall.output?.content,
    reference: 'Expected high-quality explanation',
    criteria: ['accuracy', 'clarity', 'completeness']
  },
  metadata: {
    evaluator: 'custom-bert-scorer',
    threshold: 0.8,
    metrics: ['bleu', 'rouge', 'semantic-similarity']
  }
}, { asType: 'evaluator' }); // Returns LangfuseEvaluator

// Create child guardrail for safety checking
const safetyCheck = parentObservation.startObservation('content-guardrail', {
  input: {
    text: llmCall.output?.content,
    policies: ['no-harmful-content', 'no-personal-info', 'professional-tone']
  },
  metadata: {
    guardrailVersion: 'v2.1',
    strictMode: true,
    confidence: 0.95
  }
}, { asType: 'guardrail' }); // Returns LangfuseGuardrail

// Create child embedding for vector generation
const textEmbedding = parentObservation.startObservation('text-embedder', {
  input: {
    texts: ['Document summary', 'Key insights', 'Conclusions'],
    batchSize: 3
  },
  model: 'text-embedding-ada-002',
  metadata: {
    dimensions: 1536,
    normalization: 'l2',
    purpose: 'semantic-search'
  }
}, { asType: 'embedding' }); // Returns LangfuseEmbedding

// Create child event for point-in-time logging
const userAction = parentObservation.startObservation('user-interaction', {
  input: {
    action: 'button-click',
    element: 'generate-report',
    timestamp: new Date().toISOString()
  },
  level: 'DEFAULT',
  metadata: {
    sessionId: 'sess_123',
    userId: 'user_456',
    browser: 'Chrome 120.0'
  }
}, { asType: 'event' }); // Returns LangfuseEvent (auto-ended)

// Chain operations - each child inherits context
dataProcessing.update({ output: { processed: true, records: 1000 } });
dataProcessing.end();

llmCall.update({
  output: { role: 'assistant', content: 'Machine learning is...' },
  usageDetails: { promptTokens: 25, completionTokens: 150 }
});
llmCall.end();

parentObservation.update({
  output: {
    workflowCompleted: true,
    childOperations: 8,
    totalDuration: Date.now() - startTime
  }
});
parentObservation.end();

See

startObservation for creating root-level observations
startActiveObservation for function-scoped child observations

startObservation(
    name: string,
    attributes: LangfuseSpanAttributes,
    options: { asType: "event" },
): LangfuseEvent

Creates a new child observation within this observation's context with full type safety.

Hierarchy & Context

Child observations automatically inherit the parent's trace ID and span context
Creates proper parent-child relationships in the trace structure
Enables distributed tracing across nested operations
Maintains correlation between related operations

Type Safety

Return type is automatically inferred from asType parameter
Attributes parameter is type-checked based on observation type
Compile-time validation prevents type mismatches
Full IntelliSense support for observation-specific attributes

Parameters

name: string
Descriptive name for the child observation
attributes: LangfuseSpanAttributes
Type-specific attributes (varies by observation type)
options: { asType: "event" }
Configuration including observation type (defaults to 'span')

Returns LangfuseEvent

Strongly-typed observation instance based on asType

Example

// Within any observation (span, generation, agent, etc.)
const parentObservation = startObservation('ai-workflow');

// Create child span (default)
const dataProcessing = parentObservation.startObservation('data-processing', {
  input: { userId: '123', dataSize: 1024 },
  metadata: { processor: 'fast-lane', version: '2.1' }
}); // Returns LangfuseSpan

// Create child generation with full LLM attributes
const llmCall = parentObservation.startObservation('openai-gpt-4', {
  input: [{ role: 'system', content: 'You are a helpful assistant' },
          { role: 'user', content: 'Explain machine learning' }],
  model: 'gpt-4-turbo',
  modelParameters: {
    temperature: 0.7,
    maxTokens: 500,
    topP: 1.0
  },
  metadata: { priority: 'high', timeout: 30000 }
}, { asType: 'generation' }); // Returns LangfuseGeneration

// Create child agent for complex reasoning
const reasoningAgent = parentObservation.startObservation('reasoning-agent', {
  input: {
    task: 'Analyze market trends',
    context: 'Q4 2024 financial data'
  },
  metadata: {
    model: 'gpt-4',
    tools: ['calculator', 'web-search', 'data-analysis'],
    maxIterations: 5
  }
}, { asType: 'agent' }); // Returns LangfuseAgent

// Create child tool for external API calls
const apiCall = reasoningAgent.startObservation('market-data-api', {
  input: {
    endpoint: '/market/trends',
    params: { symbol: 'AAPL', period: '1Y' }
  },
  metadata: {
    provider: 'alpha-vantage',
    rateLimit: 5,
    timeout: 10000
  }
}, { asType: 'tool' }); // Returns LangfuseTool

// Create child retriever for document search
const docSearch = parentObservation.startObservation('document-retrieval', {
  input: {
    query: 'sustainable energy solutions',
    filters: { year: '2024', category: 'research' },
    topK: 10
  },
  metadata: {
    vectorStore: 'pinecone',
    embeddingModel: 'text-embedding-ada-002',
    similarity: 'cosine'
  }
}, { asType: 'retriever' }); // Returns LangfuseRetriever

// Create child evaluator for quality assessment
const qualityCheck = parentObservation.startObservation('response-evaluator', {
  input: {
    response: llmCall.output?.content,
    reference: 'Expected high-quality explanation',
    criteria: ['accuracy', 'clarity', 'completeness']
  },
  metadata: {
    evaluator: 'custom-bert-scorer',
    threshold: 0.8,
    metrics: ['bleu', 'rouge', 'semantic-similarity']
  }
}, { asType: 'evaluator' }); // Returns LangfuseEvaluator

// Create child guardrail for safety checking
const safetyCheck = parentObservation.startObservation('content-guardrail', {
  input: {
    text: llmCall.output?.content,
    policies: ['no-harmful-content', 'no-personal-info', 'professional-tone']
  },
  metadata: {
    guardrailVersion: 'v2.1',
    strictMode: true,
    confidence: 0.95
  }
}, { asType: 'guardrail' }); // Returns LangfuseGuardrail

// Create child embedding for vector generation
const textEmbedding = parentObservation.startObservation('text-embedder', {
  input: {
    texts: ['Document summary', 'Key insights', 'Conclusions'],
    batchSize: 3
  },
  model: 'text-embedding-ada-002',
  metadata: {
    dimensions: 1536,
    normalization: 'l2',
    purpose: 'semantic-search'
  }
}, { asType: 'embedding' }); // Returns LangfuseEmbedding

// Create child event for point-in-time logging
const userAction = parentObservation.startObservation('user-interaction', {
  input: {
    action: 'button-click',
    element: 'generate-report',
    timestamp: new Date().toISOString()
  },
  level: 'DEFAULT',
  metadata: {
    sessionId: 'sess_123',
    userId: 'user_456',
    browser: 'Chrome 120.0'
  }
}, { asType: 'event' }); // Returns LangfuseEvent (auto-ended)

// Chain operations - each child inherits context
dataProcessing.update({ output: { processed: true, records: 1000 } });
dataProcessing.end();

llmCall.update({
  output: { role: 'assistant', content: 'Machine learning is...' },
  usageDetails: { promptTokens: 25, completionTokens: 150 }
});
llmCall.end();

parentObservation.update({
  output: {
    workflowCompleted: true,
    childOperations: 8,
    totalDuration: Date.now() - startTime
  }
});
parentObservation.end();

See

startObservation for creating root-level observations
startActiveObservation for function-scoped child observations

startObservation(
    name: string,
    attributes: LangfuseSpanAttributes,
    options: { asType: "agent" },
): LangfuseAgent

Creates a new child observation within this observation's context with full type safety.

Hierarchy & Context

Child observations automatically inherit the parent's trace ID and span context
Creates proper parent-child relationships in the trace structure
Enables distributed tracing across nested operations
Maintains correlation between related operations

Type Safety

Return type is automatically inferred from asType parameter
Attributes parameter is type-checked based on observation type
Compile-time validation prevents type mismatches
Full IntelliSense support for observation-specific attributes

Parameters

name: string
Descriptive name for the child observation
attributes: LangfuseSpanAttributes
Type-specific attributes (varies by observation type)
options: { asType: "agent" }
Configuration including observation type (defaults to 'span')

Returns LangfuseAgent

Strongly-typed observation instance based on asType

Example

// Within any observation (span, generation, agent, etc.)
const parentObservation = startObservation('ai-workflow');

// Create child span (default)
const dataProcessing = parentObservation.startObservation('data-processing', {
  input: { userId: '123', dataSize: 1024 },
  metadata: { processor: 'fast-lane', version: '2.1' }
}); // Returns LangfuseSpan

// Create child generation with full LLM attributes
const llmCall = parentObservation.startObservation('openai-gpt-4', {
  input: [{ role: 'system', content: 'You are a helpful assistant' },
          { role: 'user', content: 'Explain machine learning' }],
  model: 'gpt-4-turbo',
  modelParameters: {
    temperature: 0.7,
    maxTokens: 500,
    topP: 1.0
  },
  metadata: { priority: 'high', timeout: 30000 }
}, { asType: 'generation' }); // Returns LangfuseGeneration

// Create child agent for complex reasoning
const reasoningAgent = parentObservation.startObservation('reasoning-agent', {
  input: {
    task: 'Analyze market trends',
    context: 'Q4 2024 financial data'
  },
  metadata: {
    model: 'gpt-4',
    tools: ['calculator', 'web-search', 'data-analysis'],
    maxIterations: 5
  }
}, { asType: 'agent' }); // Returns LangfuseAgent

// Create child tool for external API calls
const apiCall = reasoningAgent.startObservation('market-data-api', {
  input: {
    endpoint: '/market/trends',
    params: { symbol: 'AAPL', period: '1Y' }
  },
  metadata: {
    provider: 'alpha-vantage',
    rateLimit: 5,
    timeout: 10000
  }
}, { asType: 'tool' }); // Returns LangfuseTool

// Create child retriever for document search
const docSearch = parentObservation.startObservation('document-retrieval', {
  input: {
    query: 'sustainable energy solutions',
    filters: { year: '2024', category: 'research' },
    topK: 10
  },
  metadata: {
    vectorStore: 'pinecone',
    embeddingModel: 'text-embedding-ada-002',
    similarity: 'cosine'
  }
}, { asType: 'retriever' }); // Returns LangfuseRetriever

// Create child evaluator for quality assessment
const qualityCheck = parentObservation.startObservation('response-evaluator', {
  input: {
    response: llmCall.output?.content,
    reference: 'Expected high-quality explanation',
    criteria: ['accuracy', 'clarity', 'completeness']
  },
  metadata: {
    evaluator: 'custom-bert-scorer',
    threshold: 0.8,
    metrics: ['bleu', 'rouge', 'semantic-similarity']
  }
}, { asType: 'evaluator' }); // Returns LangfuseEvaluator

// Create child guardrail for safety checking
const safetyCheck = parentObservation.startObservation('content-guardrail', {
  input: {
    text: llmCall.output?.content,
    policies: ['no-harmful-content', 'no-personal-info', 'professional-tone']
  },
  metadata: {
    guardrailVersion: 'v2.1',
    strictMode: true,
    confidence: 0.95
  }
}, { asType: 'guardrail' }); // Returns LangfuseGuardrail

// Create child embedding for vector generation
const textEmbedding = parentObservation.startObservation('text-embedder', {
  input: {
    texts: ['Document summary', 'Key insights', 'Conclusions'],
    batchSize: 3
  },
  model: 'text-embedding-ada-002',
  metadata: {
    dimensions: 1536,
    normalization: 'l2',
    purpose: 'semantic-search'
  }
}, { asType: 'embedding' }); // Returns LangfuseEmbedding

// Create child event for point-in-time logging
const userAction = parentObservation.startObservation('user-interaction', {
  input: {
    action: 'button-click',
    element: 'generate-report',
    timestamp: new Date().toISOString()
  },
  level: 'DEFAULT',
  metadata: {
    sessionId: 'sess_123',
    userId: 'user_456',
    browser: 'Chrome 120.0'
  }
}, { asType: 'event' }); // Returns LangfuseEvent (auto-ended)

// Chain operations - each child inherits context
dataProcessing.update({ output: { processed: true, records: 1000 } });
dataProcessing.end();

llmCall.update({
  output: { role: 'assistant', content: 'Machine learning is...' },
  usageDetails: { promptTokens: 25, completionTokens: 150 }
});
llmCall.end();

parentObservation.update({
  output: {
    workflowCompleted: true,
    childOperations: 8,
    totalDuration: Date.now() - startTime
  }
});
parentObservation.end();

See

startObservation for creating root-level observations
startActiveObservation for function-scoped child observations

startObservation(
    name: string,
    attributes: LangfuseSpanAttributes,
    options: { asType: "tool" },
): LangfuseTool

Creates a new child observation within this observation's context with full type safety.

Hierarchy & Context

Child observations automatically inherit the parent's trace ID and span context
Creates proper parent-child relationships in the trace structure
Enables distributed tracing across nested operations
Maintains correlation between related operations

Type Safety

Return type is automatically inferred from asType parameter
Attributes parameter is type-checked based on observation type
Compile-time validation prevents type mismatches
Full IntelliSense support for observation-specific attributes

Parameters

name: string
Descriptive name for the child observation
attributes: LangfuseSpanAttributes
Type-specific attributes (varies by observation type)
options: { asType: "tool" }
Configuration including observation type (defaults to 'span')

Returns LangfuseTool

Strongly-typed observation instance based on asType

Example

// Within any observation (span, generation, agent, etc.)
const parentObservation = startObservation('ai-workflow');

// Create child span (default)
const dataProcessing = parentObservation.startObservation('data-processing', {
  input: { userId: '123', dataSize: 1024 },
  metadata: { processor: 'fast-lane', version: '2.1' }
}); // Returns LangfuseSpan

// Create child generation with full LLM attributes
const llmCall = parentObservation.startObservation('openai-gpt-4', {
  input: [{ role: 'system', content: 'You are a helpful assistant' },
          { role: 'user', content: 'Explain machine learning' }],
  model: 'gpt-4-turbo',
  modelParameters: {
    temperature: 0.7,
    maxTokens: 500,
    topP: 1.0
  },
  metadata: { priority: 'high', timeout: 30000 }
}, { asType: 'generation' }); // Returns LangfuseGeneration

// Create child agent for complex reasoning
const reasoningAgent = parentObservation.startObservation('reasoning-agent', {
  input: {
    task: 'Analyze market trends',
    context: 'Q4 2024 financial data'
  },
  metadata: {
    model: 'gpt-4',
    tools: ['calculator', 'web-search', 'data-analysis'],
    maxIterations: 5
  }
}, { asType: 'agent' }); // Returns LangfuseAgent

// Create child tool for external API calls
const apiCall = reasoningAgent.startObservation('market-data-api', {
  input: {
    endpoint: '/market/trends',
    params: { symbol: 'AAPL', period: '1Y' }
  },
  metadata: {
    provider: 'alpha-vantage',
    rateLimit: 5,
    timeout: 10000
  }
}, { asType: 'tool' }); // Returns LangfuseTool

// Create child retriever for document search
const docSearch = parentObservation.startObservation('document-retrieval', {
  input: {
    query: 'sustainable energy solutions',
    filters: { year: '2024', category: 'research' },
    topK: 10
  },
  metadata: {
    vectorStore: 'pinecone',
    embeddingModel: 'text-embedding-ada-002',
    similarity: 'cosine'
  }
}, { asType: 'retriever' }); // Returns LangfuseRetriever

// Create child evaluator for quality assessment
const qualityCheck = parentObservation.startObservation('response-evaluator', {
  input: {
    response: llmCall.output?.content,
    reference: 'Expected high-quality explanation',
    criteria: ['accuracy', 'clarity', 'completeness']
  },
  metadata: {
    evaluator: 'custom-bert-scorer',
    threshold: 0.8,
    metrics: ['bleu', 'rouge', 'semantic-similarity']
  }
}, { asType: 'evaluator' }); // Returns LangfuseEvaluator

// Create child guardrail for safety checking
const safetyCheck = parentObservation.startObservation('content-guardrail', {
  input: {
    text: llmCall.output?.content,
    policies: ['no-harmful-content', 'no-personal-info', 'professional-tone']
  },
  metadata: {
    guardrailVersion: 'v2.1',
    strictMode: true,
    confidence: 0.95
  }
}, { asType: 'guardrail' }); // Returns LangfuseGuardrail

// Create child embedding for vector generation
const textEmbedding = parentObservation.startObservation('text-embedder', {
  input: {
    texts: ['Document summary', 'Key insights', 'Conclusions'],
    batchSize: 3
  },
  model: 'text-embedding-ada-002',
  metadata: {
    dimensions: 1536,
    normalization: 'l2',
    purpose: 'semantic-search'
  }
}, { asType: 'embedding' }); // Returns LangfuseEmbedding

// Create child event for point-in-time logging
const userAction = parentObservation.startObservation('user-interaction', {
  input: {
    action: 'button-click',
    element: 'generate-report',
    timestamp: new Date().toISOString()
  },
  level: 'DEFAULT',
  metadata: {
    sessionId: 'sess_123',
    userId: 'user_456',
    browser: 'Chrome 120.0'
  }
}, { asType: 'event' }); // Returns LangfuseEvent (auto-ended)

// Chain operations - each child inherits context
dataProcessing.update({ output: { processed: true, records: 1000 } });
dataProcessing.end();

llmCall.update({
  output: { role: 'assistant', content: 'Machine learning is...' },
  usageDetails: { promptTokens: 25, completionTokens: 150 }
});
llmCall.end();

parentObservation.update({
  output: {
    workflowCompleted: true,
    childOperations: 8,
    totalDuration: Date.now() - startTime
  }
});
parentObservation.end();

See

startObservation for creating root-level observations
startActiveObservation for function-scoped child observations

startObservation(
    name: string,
    attributes: LangfuseSpanAttributes,
    options: { asType: "chain" },
): LangfuseChain

Creates a new child observation within this observation's context with full type safety.

Hierarchy & Context

Child observations automatically inherit the parent's trace ID and span context
Creates proper parent-child relationships in the trace structure
Enables distributed tracing across nested operations
Maintains correlation between related operations

Type Safety

Return type is automatically inferred from asType parameter
Attributes parameter is type-checked based on observation type
Compile-time validation prevents type mismatches
Full IntelliSense support for observation-specific attributes

Parameters

name: string
Descriptive name for the child observation
attributes: LangfuseSpanAttributes
Type-specific attributes (varies by observation type)
options: { asType: "chain" }
Configuration including observation type (defaults to 'span')

Returns LangfuseChain

Strongly-typed observation instance based on asType

Example

// Within any observation (span, generation, agent, etc.)
const parentObservation = startObservation('ai-workflow');

// Create child span (default)
const dataProcessing = parentObservation.startObservation('data-processing', {
  input: { userId: '123', dataSize: 1024 },
  metadata: { processor: 'fast-lane', version: '2.1' }
}); // Returns LangfuseSpan

// Create child generation with full LLM attributes
const llmCall = parentObservation.startObservation('openai-gpt-4', {
  input: [{ role: 'system', content: 'You are a helpful assistant' },
          { role: 'user', content: 'Explain machine learning' }],
  model: 'gpt-4-turbo',
  modelParameters: {
    temperature: 0.7,
    maxTokens: 500,
    topP: 1.0
  },
  metadata: { priority: 'high', timeout: 30000 }
}, { asType: 'generation' }); // Returns LangfuseGeneration

// Create child agent for complex reasoning
const reasoningAgent = parentObservation.startObservation('reasoning-agent', {
  input: {
    task: 'Analyze market trends',
    context: 'Q4 2024 financial data'
  },
  metadata: {
    model: 'gpt-4',
    tools: ['calculator', 'web-search', 'data-analysis'],
    maxIterations: 5
  }
}, { asType: 'agent' }); // Returns LangfuseAgent

// Create child tool for external API calls
const apiCall = reasoningAgent.startObservation('market-data-api', {
  input: {
    endpoint: '/market/trends',
    params: { symbol: 'AAPL', period: '1Y' }
  },
  metadata: {
    provider: 'alpha-vantage',
    rateLimit: 5,
    timeout: 10000
  }
}, { asType: 'tool' }); // Returns LangfuseTool

// Create child retriever for document search
const docSearch = parentObservation.startObservation('document-retrieval', {
  input: {
    query: 'sustainable energy solutions',
    filters: { year: '2024', category: 'research' },
    topK: 10
  },
  metadata: {
    vectorStore: 'pinecone',
    embeddingModel: 'text-embedding-ada-002',
    similarity: 'cosine'
  }
}, { asType: 'retriever' }); // Returns LangfuseRetriever

// Create child evaluator for quality assessment
const qualityCheck = parentObservation.startObservation('response-evaluator', {
  input: {
    response: llmCall.output?.content,
    reference: 'Expected high-quality explanation',
    criteria: ['accuracy', 'clarity', 'completeness']
  },
  metadata: {
    evaluator: 'custom-bert-scorer',
    threshold: 0.8,
    metrics: ['bleu', 'rouge', 'semantic-similarity']
  }
}, { asType: 'evaluator' }); // Returns LangfuseEvaluator

// Create child guardrail for safety checking
const safetyCheck = parentObservation.startObservation('content-guardrail', {
  input: {
    text: llmCall.output?.content,
    policies: ['no-harmful-content', 'no-personal-info', 'professional-tone']
  },
  metadata: {
    guardrailVersion: 'v2.1',
    strictMode: true,
    confidence: 0.95
  }
}, { asType: 'guardrail' }); // Returns LangfuseGuardrail

// Create child embedding for vector generation
const textEmbedding = parentObservation.startObservation('text-embedder', {
  input: {
    texts: ['Document summary', 'Key insights', 'Conclusions'],
    batchSize: 3
  },
  model: 'text-embedding-ada-002',
  metadata: {
    dimensions: 1536,
    normalization: 'l2',
    purpose: 'semantic-search'
  }
}, { asType: 'embedding' }); // Returns LangfuseEmbedding

// Create child event for point-in-time logging
const userAction = parentObservation.startObservation('user-interaction', {
  input: {
    action: 'button-click',
    element: 'generate-report',
    timestamp: new Date().toISOString()
  },
  level: 'DEFAULT',
  metadata: {
    sessionId: 'sess_123',
    userId: 'user_456',
    browser: 'Chrome 120.0'
  }
}, { asType: 'event' }); // Returns LangfuseEvent (auto-ended)

// Chain operations - each child inherits context
dataProcessing.update({ output: { processed: true, records: 1000 } });
dataProcessing.end();

llmCall.update({
  output: { role: 'assistant', content: 'Machine learning is...' },
  usageDetails: { promptTokens: 25, completionTokens: 150 }
});
llmCall.end();

parentObservation.update({
  output: {
    workflowCompleted: true,
    childOperations: 8,
    totalDuration: Date.now() - startTime
  }
});
parentObservation.end();

See

startObservation for creating root-level observations
startActiveObservation for function-scoped child observations

startObservation(
    name: string,
    attributes: LangfuseSpanAttributes,
    options: { asType: "retriever" },
): LangfuseRetriever

Creates a new child observation within this observation's context with full type safety.

Hierarchy & Context

Child observations automatically inherit the parent's trace ID and span context
Creates proper parent-child relationships in the trace structure
Enables distributed tracing across nested operations
Maintains correlation between related operations

Type Safety

Return type is automatically inferred from asType parameter
Attributes parameter is type-checked based on observation type
Compile-time validation prevents type mismatches
Full IntelliSense support for observation-specific attributes

Parameters

name: string
Descriptive name for the child observation
attributes: LangfuseSpanAttributes
Type-specific attributes (varies by observation type)
options: { asType: "retriever" }
Configuration including observation type (defaults to 'span')

Returns LangfuseRetriever

Strongly-typed observation instance based on asType

Example

// Within any observation (span, generation, agent, etc.)
const parentObservation = startObservation('ai-workflow');

// Create child span (default)
const dataProcessing = parentObservation.startObservation('data-processing', {
  input: { userId: '123', dataSize: 1024 },
  metadata: { processor: 'fast-lane', version: '2.1' }
}); // Returns LangfuseSpan

// Create child generation with full LLM attributes
const llmCall = parentObservation.startObservation('openai-gpt-4', {
  input: [{ role: 'system', content: 'You are a helpful assistant' },
          { role: 'user', content: 'Explain machine learning' }],
  model: 'gpt-4-turbo',
  modelParameters: {
    temperature: 0.7,
    maxTokens: 500,
    topP: 1.0
  },
  metadata: { priority: 'high', timeout: 30000 }
}, { asType: 'generation' }); // Returns LangfuseGeneration

// Create child agent for complex reasoning
const reasoningAgent = parentObservation.startObservation('reasoning-agent', {
  input: {
    task: 'Analyze market trends',
    context: 'Q4 2024 financial data'
  },
  metadata: {
    model: 'gpt-4',
    tools: ['calculator', 'web-search', 'data-analysis'],
    maxIterations: 5
  }
}, { asType: 'agent' }); // Returns LangfuseAgent

// Create child tool for external API calls
const apiCall = reasoningAgent.startObservation('market-data-api', {
  input: {
    endpoint: '/market/trends',
    params: { symbol: 'AAPL', period: '1Y' }
  },
  metadata: {
    provider: 'alpha-vantage',
    rateLimit: 5,
    timeout: 10000
  }
}, { asType: 'tool' }); // Returns LangfuseTool

// Create child retriever for document search
const docSearch = parentObservation.startObservation('document-retrieval', {
  input: {
    query: 'sustainable energy solutions',
    filters: { year: '2024', category: 'research' },
    topK: 10
  },
  metadata: {
    vectorStore: 'pinecone',
    embeddingModel: 'text-embedding-ada-002',
    similarity: 'cosine'
  }
}, { asType: 'retriever' }); // Returns LangfuseRetriever

// Create child evaluator for quality assessment
const qualityCheck = parentObservation.startObservation('response-evaluator', {
  input: {
    response: llmCall.output?.content,
    reference: 'Expected high-quality explanation',
    criteria: ['accuracy', 'clarity', 'completeness']
  },
  metadata: {
    evaluator: 'custom-bert-scorer',
    threshold: 0.8,
    metrics: ['bleu', 'rouge', 'semantic-similarity']
  }
}, { asType: 'evaluator' }); // Returns LangfuseEvaluator

// Create child guardrail for safety checking
const safetyCheck = parentObservation.startObservation('content-guardrail', {
  input: {
    text: llmCall.output?.content,
    policies: ['no-harmful-content', 'no-personal-info', 'professional-tone']
  },
  metadata: {
    guardrailVersion: 'v2.1',
    strictMode: true,
    confidence: 0.95
  }
}, { asType: 'guardrail' }); // Returns LangfuseGuardrail

// Create child embedding for vector generation
const textEmbedding = parentObservation.startObservation('text-embedder', {
  input: {
    texts: ['Document summary', 'Key insights', 'Conclusions'],
    batchSize: 3
  },
  model: 'text-embedding-ada-002',
  metadata: {
    dimensions: 1536,
    normalization: 'l2',
    purpose: 'semantic-search'
  }
}, { asType: 'embedding' }); // Returns LangfuseEmbedding

// Create child event for point-in-time logging
const userAction = parentObservation.startObservation('user-interaction', {
  input: {
    action: 'button-click',
    element: 'generate-report',
    timestamp: new Date().toISOString()
  },
  level: 'DEFAULT',
  metadata: {
    sessionId: 'sess_123',
    userId: 'user_456',
    browser: 'Chrome 120.0'
  }
}, { asType: 'event' }); // Returns LangfuseEvent (auto-ended)

// Chain operations - each child inherits context
dataProcessing.update({ output: { processed: true, records: 1000 } });
dataProcessing.end();

llmCall.update({
  output: { role: 'assistant', content: 'Machine learning is...' },
  usageDetails: { promptTokens: 25, completionTokens: 150 }
});
llmCall.end();

parentObservation.update({
  output: {
    workflowCompleted: true,
    childOperations: 8,
    totalDuration: Date.now() - startTime
  }
});
parentObservation.end();

See

startObservation for creating root-level observations
startActiveObservation for function-scoped child observations

startObservation(
    name: string,
    attributes: LangfuseSpanAttributes,
    options: { asType: "evaluator" },
): LangfuseEvaluator

Creates a new child observation within this observation's context with full type safety.

Hierarchy & Context

Child observations automatically inherit the parent's trace ID and span context
Creates proper parent-child relationships in the trace structure
Enables distributed tracing across nested operations
Maintains correlation between related operations

Type Safety

Return type is automatically inferred from asType parameter
Attributes parameter is type-checked based on observation type
Compile-time validation prevents type mismatches
Full IntelliSense support for observation-specific attributes

Parameters

name: string
Descriptive name for the child observation
attributes: LangfuseSpanAttributes
Type-specific attributes (varies by observation type)
options: { asType: "evaluator" }
Configuration including observation type (defaults to 'span')

Returns LangfuseEvaluator

Strongly-typed observation instance based on asType

Example

// Within any observation (span, generation, agent, etc.)
const parentObservation = startObservation('ai-workflow');

// Create child span (default)
const dataProcessing = parentObservation.startObservation('data-processing', {
  input: { userId: '123', dataSize: 1024 },
  metadata: { processor: 'fast-lane', version: '2.1' }
}); // Returns LangfuseSpan

// Create child generation with full LLM attributes
const llmCall = parentObservation.startObservation('openai-gpt-4', {
  input: [{ role: 'system', content: 'You are a helpful assistant' },
          { role: 'user', content: 'Explain machine learning' }],
  model: 'gpt-4-turbo',
  modelParameters: {
    temperature: 0.7,
    maxTokens: 500,
    topP: 1.0
  },
  metadata: { priority: 'high', timeout: 30000 }
}, { asType: 'generation' }); // Returns LangfuseGeneration

// Create child agent for complex reasoning
const reasoningAgent = parentObservation.startObservation('reasoning-agent', {
  input: {
    task: 'Analyze market trends',
    context: 'Q4 2024 financial data'
  },
  metadata: {
    model: 'gpt-4',
    tools: ['calculator', 'web-search', 'data-analysis'],
    maxIterations: 5
  }
}, { asType: 'agent' }); // Returns LangfuseAgent

// Create child tool for external API calls
const apiCall = reasoningAgent.startObservation('market-data-api', {
  input: {
    endpoint: '/market/trends',
    params: { symbol: 'AAPL', period: '1Y' }
  },
  metadata: {
    provider: 'alpha-vantage',
    rateLimit: 5,
    timeout: 10000
  }
}, { asType: 'tool' }); // Returns LangfuseTool

// Create child retriever for document search
const docSearch = parentObservation.startObservation('document-retrieval', {
  input: {
    query: 'sustainable energy solutions',
    filters: { year: '2024', category: 'research' },
    topK: 10
  },
  metadata: {
    vectorStore: 'pinecone',
    embeddingModel: 'text-embedding-ada-002',
    similarity: 'cosine'
  }
}, { asType: 'retriever' }); // Returns LangfuseRetriever

// Create child evaluator for quality assessment
const qualityCheck = parentObservation.startObservation('response-evaluator', {
  input: {
    response: llmCall.output?.content,
    reference: 'Expected high-quality explanation',
    criteria: ['accuracy', 'clarity', 'completeness']
  },
  metadata: {
    evaluator: 'custom-bert-scorer',
    threshold: 0.8,
    metrics: ['bleu', 'rouge', 'semantic-similarity']
  }
}, { asType: 'evaluator' }); // Returns LangfuseEvaluator

// Create child guardrail for safety checking
const safetyCheck = parentObservation.startObservation('content-guardrail', {
  input: {
    text: llmCall.output?.content,
    policies: ['no-harmful-content', 'no-personal-info', 'professional-tone']
  },
  metadata: {
    guardrailVersion: 'v2.1',
    strictMode: true,
    confidence: 0.95
  }
}, { asType: 'guardrail' }); // Returns LangfuseGuardrail

// Create child embedding for vector generation
const textEmbedding = parentObservation.startObservation('text-embedder', {
  input: {
    texts: ['Document summary', 'Key insights', 'Conclusions'],
    batchSize: 3
  },
  model: 'text-embedding-ada-002',
  metadata: {
    dimensions: 1536,
    normalization: 'l2',
    purpose: 'semantic-search'
  }
}, { asType: 'embedding' }); // Returns LangfuseEmbedding

// Create child event for point-in-time logging
const userAction = parentObservation.startObservation('user-interaction', {
  input: {
    action: 'button-click',
    element: 'generate-report',
    timestamp: new Date().toISOString()
  },
  level: 'DEFAULT',
  metadata: {
    sessionId: 'sess_123',
    userId: 'user_456',
    browser: 'Chrome 120.0'
  }
}, { asType: 'event' }); // Returns LangfuseEvent (auto-ended)

// Chain operations - each child inherits context
dataProcessing.update({ output: { processed: true, records: 1000 } });
dataProcessing.end();

llmCall.update({
  output: { role: 'assistant', content: 'Machine learning is...' },
  usageDetails: { promptTokens: 25, completionTokens: 150 }
});
llmCall.end();

parentObservation.update({
  output: {
    workflowCompleted: true,
    childOperations: 8,
    totalDuration: Date.now() - startTime
  }
});
parentObservation.end();

See

startObservation for creating root-level observations
startActiveObservation for function-scoped child observations

startObservation(
    name: string,
    attributes: LangfuseSpanAttributes,
    options: { asType: "guardrail" },
): LangfuseGuardrail

Creates a new child observation within this observation's context with full type safety.

Hierarchy & Context

Child observations automatically inherit the parent's trace ID and span context
Creates proper parent-child relationships in the trace structure
Enables distributed tracing across nested operations
Maintains correlation between related operations

Type Safety

Return type is automatically inferred from asType parameter
Attributes parameter is type-checked based on observation type
Compile-time validation prevents type mismatches
Full IntelliSense support for observation-specific attributes

Parameters

name: string
Descriptive name for the child observation
attributes: LangfuseSpanAttributes
Type-specific attributes (varies by observation type)
options: { asType: "guardrail" }
Configuration including observation type (defaults to 'span')

Returns LangfuseGuardrail

Strongly-typed observation instance based on asType

Example

// Within any observation (span, generation, agent, etc.)
const parentObservation = startObservation('ai-workflow');

// Create child span (default)
const dataProcessing = parentObservation.startObservation('data-processing', {
  input: { userId: '123', dataSize: 1024 },
  metadata: { processor: 'fast-lane', version: '2.1' }
}); // Returns LangfuseSpan

// Create child generation with full LLM attributes
const llmCall = parentObservation.startObservation('openai-gpt-4', {
  input: [{ role: 'system', content: 'You are a helpful assistant' },
          { role: 'user', content: 'Explain machine learning' }],
  model: 'gpt-4-turbo',
  modelParameters: {
    temperature: 0.7,
    maxTokens: 500,
    topP: 1.0
  },
  metadata: { priority: 'high', timeout: 30000 }
}, { asType: 'generation' }); // Returns LangfuseGeneration

// Create child agent for complex reasoning
const reasoningAgent = parentObservation.startObservation('reasoning-agent', {
  input: {
    task: 'Analyze market trends',
    context: 'Q4 2024 financial data'
  },
  metadata: {
    model: 'gpt-4',
    tools: ['calculator', 'web-search', 'data-analysis'],
    maxIterations: 5
  }
}, { asType: 'agent' }); // Returns LangfuseAgent

// Create child tool for external API calls
const apiCall = reasoningAgent.startObservation('market-data-api', {
  input: {
    endpoint: '/market/trends',
    params: { symbol: 'AAPL', period: '1Y' }
  },
  metadata: {
    provider: 'alpha-vantage',
    rateLimit: 5,
    timeout: 10000
  }
}, { asType: 'tool' }); // Returns LangfuseTool

// Create child retriever for document search
const docSearch = parentObservation.startObservation('document-retrieval', {
  input: {
    query: 'sustainable energy solutions',
    filters: { year: '2024', category: 'research' },
    topK: 10
  },
  metadata: {
    vectorStore: 'pinecone',
    embeddingModel: 'text-embedding-ada-002',
    similarity: 'cosine'
  }
}, { asType: 'retriever' }); // Returns LangfuseRetriever

// Create child evaluator for quality assessment
const qualityCheck = parentObservation.startObservation('response-evaluator', {
  input: {
    response: llmCall.output?.content,
    reference: 'Expected high-quality explanation',
    criteria: ['accuracy', 'clarity', 'completeness']
  },
  metadata: {
    evaluator: 'custom-bert-scorer',
    threshold: 0.8,
    metrics: ['bleu', 'rouge', 'semantic-similarity']
  }
}, { asType: 'evaluator' }); // Returns LangfuseEvaluator

// Create child guardrail for safety checking
const safetyCheck = parentObservation.startObservation('content-guardrail', {
  input: {
    text: llmCall.output?.content,
    policies: ['no-harmful-content', 'no-personal-info', 'professional-tone']
  },
  metadata: {
    guardrailVersion: 'v2.1',
    strictMode: true,
    confidence: 0.95
  }
}, { asType: 'guardrail' }); // Returns LangfuseGuardrail

// Create child embedding for vector generation
const textEmbedding = parentObservation.startObservation('text-embedder', {
  input: {
    texts: ['Document summary', 'Key insights', 'Conclusions'],
    batchSize: 3
  },
  model: 'text-embedding-ada-002',
  metadata: {
    dimensions: 1536,
    normalization: 'l2',
    purpose: 'semantic-search'
  }
}, { asType: 'embedding' }); // Returns LangfuseEmbedding

// Create child event for point-in-time logging
const userAction = parentObservation.startObservation('user-interaction', {
  input: {
    action: 'button-click',
    element: 'generate-report',
    timestamp: new Date().toISOString()
  },
  level: 'DEFAULT',
  metadata: {
    sessionId: 'sess_123',
    userId: 'user_456',
    browser: 'Chrome 120.0'
  }
}, { asType: 'event' }); // Returns LangfuseEvent (auto-ended)

// Chain operations - each child inherits context
dataProcessing.update({ output: { processed: true, records: 1000 } });
dataProcessing.end();

llmCall.update({
  output: { role: 'assistant', content: 'Machine learning is...' },
  usageDetails: { promptTokens: 25, completionTokens: 150 }
});
llmCall.end();

parentObservation.update({
  output: {
    workflowCompleted: true,
    childOperations: 8,
    totalDuration: Date.now() - startTime
  }
});
parentObservation.end();

See

startObservation for creating root-level observations
startActiveObservation for function-scoped child observations

startObservation(
    name: string,
    attributes: LangfuseGenerationAttributes,
    options: { asType: "embedding" },
): LangfuseEmbedding

Creates a new child observation within this observation's context with full type safety.

Hierarchy & Context

Child observations automatically inherit the parent's trace ID and span context
Creates proper parent-child relationships in the trace structure
Enables distributed tracing across nested operations
Maintains correlation between related operations

Type Safety

Return type is automatically inferred from asType parameter
Attributes parameter is type-checked based on observation type
Compile-time validation prevents type mismatches
Full IntelliSense support for observation-specific attributes

Parameters

name: string
Descriptive name for the child observation
attributes: LangfuseGenerationAttributes
Type-specific attributes (varies by observation type)
options: { asType: "embedding" }
Configuration including observation type (defaults to 'span')

Returns LangfuseEmbedding

Strongly-typed observation instance based on asType

Example

// Within any observation (span, generation, agent, etc.)
const parentObservation = startObservation('ai-workflow');

// Create child span (default)
const dataProcessing = parentObservation.startObservation('data-processing', {
  input: { userId: '123', dataSize: 1024 },
  metadata: { processor: 'fast-lane', version: '2.1' }
}); // Returns LangfuseSpan

// Create child generation with full LLM attributes
const llmCall = parentObservation.startObservation('openai-gpt-4', {
  input: [{ role: 'system', content: 'You are a helpful assistant' },
          { role: 'user', content: 'Explain machine learning' }],
  model: 'gpt-4-turbo',
  modelParameters: {
    temperature: 0.7,
    maxTokens: 500,
    topP: 1.0
  },
  metadata: { priority: 'high', timeout: 30000 }
}, { asType: 'generation' }); // Returns LangfuseGeneration

// Create child agent for complex reasoning
const reasoningAgent = parentObservation.startObservation('reasoning-agent', {
  input: {
    task: 'Analyze market trends',
    context: 'Q4 2024 financial data'
  },
  metadata: {
    model: 'gpt-4',
    tools: ['calculator', 'web-search', 'data-analysis'],
    maxIterations: 5
  }
}, { asType: 'agent' }); // Returns LangfuseAgent

// Create child tool for external API calls
const apiCall = reasoningAgent.startObservation('market-data-api', {
  input: {
    endpoint: '/market/trends',
    params: { symbol: 'AAPL', period: '1Y' }
  },
  metadata: {
    provider: 'alpha-vantage',
    rateLimit: 5,
    timeout: 10000
  }
}, { asType: 'tool' }); // Returns LangfuseTool

// Create child retriever for document search
const docSearch = parentObservation.startObservation('document-retrieval', {
  input: {
    query: 'sustainable energy solutions',
    filters: { year: '2024', category: 'research' },
    topK: 10
  },
  metadata: {
    vectorStore: 'pinecone',
    embeddingModel: 'text-embedding-ada-002',
    similarity: 'cosine'
  }
}, { asType: 'retriever' }); // Returns LangfuseRetriever

// Create child evaluator for quality assessment
const qualityCheck = parentObservation.startObservation('response-evaluator', {
  input: {
    response: llmCall.output?.content,
    reference: 'Expected high-quality explanation',
    criteria: ['accuracy', 'clarity', 'completeness']
  },
  metadata: {
    evaluator: 'custom-bert-scorer',
    threshold: 0.8,
    metrics: ['bleu', 'rouge', 'semantic-similarity']
  }
}, { asType: 'evaluator' }); // Returns LangfuseEvaluator

// Create child guardrail for safety checking
const safetyCheck = parentObservation.startObservation('content-guardrail', {
  input: {
    text: llmCall.output?.content,
    policies: ['no-harmful-content', 'no-personal-info', 'professional-tone']
  },
  metadata: {
    guardrailVersion: 'v2.1',
    strictMode: true,
    confidence: 0.95
  }
}, { asType: 'guardrail' }); // Returns LangfuseGuardrail

// Create child embedding for vector generation
const textEmbedding = parentObservation.startObservation('text-embedder', {
  input: {
    texts: ['Document summary', 'Key insights', 'Conclusions'],
    batchSize: 3
  },
  model: 'text-embedding-ada-002',
  metadata: {
    dimensions: 1536,
    normalization: 'l2',
    purpose: 'semantic-search'
  }
}, { asType: 'embedding' }); // Returns LangfuseEmbedding

// Create child event for point-in-time logging
const userAction = parentObservation.startObservation('user-interaction', {
  input: {
    action: 'button-click',
    element: 'generate-report',
    timestamp: new Date().toISOString()
  },
  level: 'DEFAULT',
  metadata: {
    sessionId: 'sess_123',
    userId: 'user_456',
    browser: 'Chrome 120.0'
  }
}, { asType: 'event' }); // Returns LangfuseEvent (auto-ended)

// Chain operations - each child inherits context
dataProcessing.update({ output: { processed: true, records: 1000 } });
dataProcessing.end();

llmCall.update({
  output: { role: 'assistant', content: 'Machine learning is...' },
  usageDetails: { promptTokens: 25, completionTokens: 150 }
});
llmCall.end();

parentObservation.update({
  output: {
    workflowCompleted: true,
    childOperations: 8,
    totalDuration: Date.now() - startTime
  }
});
parentObservation.end();

See

startObservation for creating root-level observations
startActiveObservation for function-scoped child observations

startObservation(
    name: string,
    attributes?: LangfuseSpanAttributes,
    options?: { asType?: "span" },
): LangfuseSpan

Creates a new child observation within this observation's context with full type safety.

Hierarchy & Context

Child observations automatically inherit the parent's trace ID and span context
Creates proper parent-child relationships in the trace structure
Enables distributed tracing across nested operations
Maintains correlation between related operations

Type Safety

Return type is automatically inferred from asType parameter
Attributes parameter is type-checked based on observation type
Compile-time validation prevents type mismatches
Full IntelliSense support for observation-specific attributes

Parameters

name: string
Descriptive name for the child observation
Optionalattributes: LangfuseSpanAttributes
Type-specific attributes (varies by observation type)
Optionaloptions: { asType?: "span" }
Configuration including observation type (defaults to 'span')

Returns LangfuseSpan

Strongly-typed observation instance based on asType

Example

// Within any observation (span, generation, agent, etc.)
const parentObservation = startObservation('ai-workflow');

// Create child span (default)
const dataProcessing = parentObservation.startObservation('data-processing', {
  input: { userId: '123', dataSize: 1024 },
  metadata: { processor: 'fast-lane', version: '2.1' }
}); // Returns LangfuseSpan

// Create child generation with full LLM attributes
const llmCall = parentObservation.startObservation('openai-gpt-4', {
  input: [{ role: 'system', content: 'You are a helpful assistant' },
          { role: 'user', content: 'Explain machine learning' }],
  model: 'gpt-4-turbo',
  modelParameters: {
    temperature: 0.7,
    maxTokens: 500,
    topP: 1.0
  },
  metadata: { priority: 'high', timeout: 30000 }
}, { asType: 'generation' }); // Returns LangfuseGeneration

// Create child agent for complex reasoning
const reasoningAgent = parentObservation.startObservation('reasoning-agent', {
  input: {
    task: 'Analyze market trends',
    context: 'Q4 2024 financial data'
  },
  metadata: {
    model: 'gpt-4',
    tools: ['calculator', 'web-search', 'data-analysis'],
    maxIterations: 5
  }
}, { asType: 'agent' }); // Returns LangfuseAgent

// Create child tool for external API calls
const apiCall = reasoningAgent.startObservation('market-data-api', {
  input: {
    endpoint: '/market/trends',
    params: { symbol: 'AAPL', period: '1Y' }
  },
  metadata: {
    provider: 'alpha-vantage',
    rateLimit: 5,
    timeout: 10000
  }
}, { asType: 'tool' }); // Returns LangfuseTool

// Create child retriever for document search
const docSearch = parentObservation.startObservation('document-retrieval', {
  input: {
    query: 'sustainable energy solutions',
    filters: { year: '2024', category: 'research' },
    topK: 10
  },
  metadata: {
    vectorStore: 'pinecone',
    embeddingModel: 'text-embedding-ada-002',
    similarity: 'cosine'
  }
}, { asType: 'retriever' }); // Returns LangfuseRetriever

// Create child evaluator for quality assessment
const qualityCheck = parentObservation.startObservation('response-evaluator', {
  input: {
    response: llmCall.output?.content,
    reference: 'Expected high-quality explanation',
    criteria: ['accuracy', 'clarity', 'completeness']
  },
  metadata: {
    evaluator: 'custom-bert-scorer',
    threshold: 0.8,
    metrics: ['bleu', 'rouge', 'semantic-similarity']
  }
}, { asType: 'evaluator' }); // Returns LangfuseEvaluator

// Create child guardrail for safety checking
const safetyCheck = parentObservation.startObservation('content-guardrail', {
  input: {
    text: llmCall.output?.content,
    policies: ['no-harmful-content', 'no-personal-info', 'professional-tone']
  },
  metadata: {
    guardrailVersion: 'v2.1',
    strictMode: true,
    confidence: 0.95
  }
}, { asType: 'guardrail' }); // Returns LangfuseGuardrail

// Create child embedding for vector generation
const textEmbedding = parentObservation.startObservation('text-embedder', {
  input: {
    texts: ['Document summary', 'Key insights', 'Conclusions'],
    batchSize: 3
  },
  model: 'text-embedding-ada-002',
  metadata: {
    dimensions: 1536,
    normalization: 'l2',
    purpose: 'semantic-search'
  }
}, { asType: 'embedding' }); // Returns LangfuseEmbedding

// Create child event for point-in-time logging
const userAction = parentObservation.startObservation('user-interaction', {
  input: {
    action: 'button-click',
    element: 'generate-report',
    timestamp: new Date().toISOString()
  },
  level: 'DEFAULT',
  metadata: {
    sessionId: 'sess_123',
    userId: 'user_456',
    browser: 'Chrome 120.0'
  }
}, { asType: 'event' }); // Returns LangfuseEvent (auto-ended)

// Chain operations - each child inherits context
dataProcessing.update({ output: { processed: true, records: 1000 } });
dataProcessing.end();

llmCall.update({
  output: { role: 'assistant', content: 'Machine learning is...' },
  usageDetails: { promptTokens: 25, completionTokens: 150 }
});
llmCall.end();

parentObservation.update({
  output: {
    workflowCompleted: true,
    childOperations: 8,
    totalDuration: Date.now() - startTime
  }
});
parentObservation.end();

See

startObservation for creating root-level observations
startActiveObservation for function-scoped child observations

update

update(attributes: LangfuseSpanAttributes): LangfuseAgent

Updates this agent observation with new attributes.

Parameters

attributes: LangfuseSpanAttributes
Agent attributes to set

Returns LangfuseAgent

This agent for method chaining

Example

agent.update({
  output: {
    taskCompleted: true,
    iterationsUsed: 5,
    toolsInvoked: ['web-search', 'calculator', 'summarizer'],
    finalResult: 'Research completed with high confidence'
  },
  metadata: {
    efficiency: 0.85,
    qualityScore: 0.92,
    resourcesConsumed: { tokens: 15000, apiCalls: 12 }
  }
});

updateOtelSpanAttributes

updateOtelSpanAttributes(attributes: LangfuseObservationAttributes): void
Parameters
- attributes: LangfuseObservationAttributes
Returns void
Inherited from LangfuseBaseObservation.updateOtelSpanAttributes
- Defined in tracing/src/spanWrapper.ts:188

updateTrace

updateTrace(attributes: LangfuseTraceAttributes): LangfuseAgent
Updates the parent trace with new attributes.

This sets trace-level attributes that apply to the entire trace, not just this specific observation.
Parameters
- attributes: LangfuseTraceAttributes
  Trace attributes to set
Returns LangfuseAgent
This observation for method chaining
Inherited from LangfuseBaseObservation.updateTrace
- Defined in tracing/src/spanWrapper.ts:203

Class LangfuseAgent

Primary Use Cases

Key Features

Agent-Specific Patterns

Example

See

Hierarchy

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Parameters

Returns LangfuseAgent

Properties

id

ReadonlyotelSpan

traceId

Readonlytype

Accessors

Protectedtracer

Returns Tracer

Methods

end

Parameters

Returns void

startObservation

Hierarchy & Context

Type Safety

Parameters

Returns LangfuseGeneration

Example

See

Hierarchy & Context

Type Safety

Parameters

Returns LangfuseEvent

Example

See

Hierarchy & Context

Type Safety

Parameters

Returns LangfuseAgent

Example

See

Hierarchy & Context

Type Safety

Parameters

Returns LangfuseTool

Example

See

Hierarchy & Context

Type Safety

Parameters

Returns LangfuseChain

Example

See

Hierarchy & Context

Type Safety

Parameters

Returns LangfuseRetriever

Example

See

Hierarchy & Context

Type Safety

Parameters

Returns LangfuseEvaluator

Example

See

Hierarchy & Context

Type Safety

Parameters

Returns LangfuseGuardrail

Example

See

Hierarchy & Context

Type Safety

Parameters

`Readonly`otelSpan

`Readonly`type

`Protected`tracer