Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions content/Cloud/key-value-memory.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -38,4 +38,6 @@ There are two ways to create a new key value instance:
1. From the Services > Key Value page in the Cloud Console
2. In code, using the Agentuity SDK

When creating a key value instance from the Cloud Console, click the **Create Storage** button and select **Key Value Store** from the storage type options.

<ThemeImage baseName="keyvalue-new" alt="New Key Value Memory Storage" />
1 change: 1 addition & 0 deletions content/Cloud/meta.json
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@
"agents",
"vector-memory",
"key-value-memory",
"object-storage",
"ai-gateway",
"settings"
]
Expand Down
40 changes: 40 additions & 0 deletions content/Cloud/object-storage.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
---
title: Object Storage
description: The Object Storage page is for managing your object storage buckets
---

## Understanding Object Storage

Object storage is designed for storing files, media, and unstructured data, making it ideal for:

- Files and documents
- Images and videos
- Backups and archives
- Static assets
- Large binary data
- Public content delivery

## Viewing Your Object Storage Buckets

When you navigate to the Services > Object Store page in the Cloud Console, you'll see a table listing all your object storage buckets with the following information:

- **Bucket Name**: The name of your object storage bucket
- **Provider**: The storage provider for the bucket
- **Created At**: When the bucket was created
- **Size**: The storage size used by the bucket
- **Num. of Objects**: The number of objects stored in the bucket

You can filter the list of buckets using the search box at the top of the table to quickly find specific buckets by name.

<ThemeImage baseName="object-store" alt="Object Storage Overview" />

## Creating a New Object Storage Bucket

There are two ways to create a new object storage bucket:

1. From the Services > Object Store page in the Cloud Console
2. In code, using the Agentuity SDK

When creating an object storage bucket from the Cloud Console, click the **Create Storage** button and select **Object Store** from the storage type options. You can also choose your preferred storage provider from the dropdown menu, including Agentuity's built-in storage, Google Cloud Storage, or Azure Blob Storage.

<ThemeImage baseName="object-store-new" alt="New Object Storage" />
2 changes: 2 additions & 0 deletions content/Cloud/vector-memory.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -37,4 +37,6 @@ There are two ways to create a new vector instance:
1. From the Services > Vector page in the Cloud Console
2. In code, using the Agentuity SDK

When creating a vector instance from the Cloud Console, click the **Create Storage** button and select **Vector Database** from the storage type options.

<ThemeImage baseName="vector-new" alt="New Vector Memory Storage" />
4 changes: 0 additions & 4 deletions content/Guides/.agent-logging.mdx

This file was deleted.

4 changes: 0 additions & 4 deletions content/Guides/.agent-telemetry.mdx

This file was deleted.

4 changes: 0 additions & 4 deletions content/Guides/.agent-tracing.mdx

This file was deleted.

4 changes: 0 additions & 4 deletions content/Guides/.ai-gateway.mdx

This file was deleted.

4 changes: 0 additions & 4 deletions content/Guides/.devmode.mdx

This file was deleted.

4 changes: 0 additions & 4 deletions content/Guides/.key-value.mdx

This file was deleted.

4 changes: 0 additions & 4 deletions content/Guides/.vector-db.mdx

This file was deleted.

2 changes: 1 addition & 1 deletion content/Guides/agent-data-handling.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -161,7 +161,7 @@ async def run(request: AgentRequest, response: AgentResponse, context: AgentCont

You must await the `stream` method to get a stream of the raw binary data. The stream will be a `ReadableStream` object for JavaScript and a `IO[bytes]` object for Python.

See the [Streaming](/guides/agent-streaming) guide for more information on how Agent Streaming works.
See the [Streaming](/Guides/agent-streaming) guide for more information on how Agent Streaming works.


#### Base64
Expand Down
186 changes: 186 additions & 0 deletions content/Guides/agent-logging.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,186 @@
---
title: Agent Logging
description: How to use logging in your agents
---

## What is Agent Logging?

Agent logging provides structured, real-time insights into your agent's execution. Effective logging helps you debug issues, monitor behavior, and understand agent decision-making.

## Logging Interface

The Agentuity platform provides persistent, searchable logs with real-time streaming for all deployed agents.

<ThemeImage baseName="agent-logs" alt="Logs Overview" />

### Log Overview

The Logs dashboard displays:

- **Timestamps**: Precise timing for each log entry
- **Severity levels**: INFO, WARN, ERROR for categorization
- **Source identification**: Which component generated the log
- **Detailed messages**: Context about agent actions

### Search and Filtering

**AI-Powered Search:**
Use natural language queries to find log entries. Click the purple sparkle icon and enter your search:

<ThemeImage baseName="agent-logs-filter" alt="AI-Powered Log Search" />

**Filtering Options:**
- **Severity**: Filter by log level (INFO, WARN, ERROR, etc.)
- **Project**: Scope logs to specific projects
- **Agent**: View logs from specific agents
- **Session ID**: Filter logs for a particular session
- **Deployment ID**: View logs from specific deployments
- **Time Range**: Focus on specific time periods

### Detailed Log Analysis

Each log entry provides comprehensive context and can be expanded for full details:

<ThemeImage baseName="agent-logs-detail" alt="Detailed Log Entry View" />

## Logging Best Practices

### 1. Use Appropriate Log Levels

<CodeExample js={`// INFO: Normal flow and state changes
context.logger.info('Processing user request', { userId, action });

// WARN: Potential issues that don't stop execution
context.logger.warn('Rate limit approaching', { remaining: 5 });

// ERROR: Failures requiring attention
context.logger.error('Failed to fetch data', { error: error.message });`} py={`# INFO: Normal flow and state changes
context.logger.info("Processing user request", user_id=user_id, action=action)

# WARN: Potential issues that don't stop execution
context.logger.warn("Rate limit approaching", remaining=5)

# ERROR: Failures requiring attention
context.logger.error("Failed to fetch data", error=str(err))`} />

### 2. Include Relevant Context

Log enough information to understand what happened without re-running:

<CodeExample js={`// Good - includes context
context.logger.info('Order processed', {
orderId: order.id,
customerId: customer.id,
total: order.total,
itemCount: order.items.length
});

// Less helpful
context.logger.info('Order done');`} py={`# Good - includes context
context.logger.info(
"Order processed",
order_id=order.id,
customer_id=customer.id,
total=order.total,
item_count=len(order.items)
)

# Less helpful
context.logger.info("Order done")`} />

### 3. Log Decision Points

Help future debugging by logging key decisions:

<CodeExample js={`if (useCache) {
context.logger.info('Using cached response', {
cacheKey,
age: cacheAge
});
} else {
context.logger.info('Cache miss, fetching fresh data', {
cacheKey,
reason: 'expired'
});
}`} py={`if use_cache:
context.logger.info(
"Using cached response",
cache_key=cache_key,
age=cache_age
)
else:
context.logger.info(
"Cache miss, fetching fresh data",
cache_key=cache_key,
reason="expired"
)`} />

### 4. Avoid Logging Sensitive Data

Never log passwords, tokens, or personal information:

<CodeExample js={`// Don't log sensitive data
context.logger.info('User authenticated', { userId });

// Not this
context.logger.info('Login attempt', {
username,
password // Never log passwords!
});`} py={`# Don't log sensitive data
context.logger.info("User authenticated", user_id=user_id)

# Not this
context.logger.info(
"Login attempt",
username=username,
password=password # Never log passwords!
)`} />

### 5. Use Child Loggers for Request Context

Create child loggers to automatically include context in all related logs:

<CodeExample js={`// Create a child logger with request context
const requestLogger = context.logger.child({
requestId: req.id,
userId: req.userId,
endpoint: req.path
});

// All logs from this logger include the context
requestLogger.info('Starting request processing');
requestLogger.info('User authenticated');
requestLogger.error('Failed to fetch user data', error);`} py={`# Create a child logger with request context
request_logger = context.logger.child(
request_id=req.id,
user_id=req.user_id,
endpoint=req.path
)

# All logs from this logger include the context
request_logger.info("Starting request processing")
request_logger.info("User authenticated")
request_logger.error("Failed to fetch user data", error=str(e))`} />

## Structured Logging

Use structured data for easier parsing and analysis:

<CodeExample js={`// Structured approach
context.logger.info('API call completed', {
endpoint: '/api/users',
method: 'GET',
duration: 234,
status: 200,
userId: req.userId
});`} py={`# Structured approach
context.logger.info(
"API call completed",
endpoint="/api/users",
method="GET",
duration=234,
status=200,
user_id=req.user_id
)`} />

For more observability features, see [Agent Telemetry](/Guides/agent-telemetry) and [Agent Tracing](/Guides/agent-tracing).
72 changes: 72 additions & 0 deletions content/Guides/agent-telemetry.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,72 @@
---
title: Agent Telemetry
description: How to use telemetry in your agents
---

## What is Agent Telemetry?

Agent telemetry provides performance metrics and execution traces for your agents through OpenTelemetry integration. Monitor how your agents perform, where time is spent, and identify optimization opportunities.

## Production Sessions and Analytics

The Agentuity platform provides comprehensive telemetry for deployed agents through the Sessions interface. All production agent executions are automatically tracked and persist for analysis and troubleshooting.

<ThemeImage baseName="sessions" alt="Production Sessions Overview" />

### Session Overview

The Sessions dashboard displays:

- **Status indicators**: Success, failure, and execution state
- **Agent identification**: Which agent handled each request
- **Performance metrics**: Duration and cost per session
- **Timeline data**: When sessions occurred with precise timestamps

### Detailed Session Analysis

Each session provides detailed execution traces with comprehensive telemetry data:

<ThemeImage baseName="agent-session-detail" alt="Detailed Session Timeline with Spans" />

## Understanding Spans

Telemetry data is organized into spans representing units of work. The timeline visualization uses color coding:

- **Root** (Black): Overall agent execution
- **API/HTTP** (Teal): External service calls
- **AI Services** (Purple): Language model interactions
- **Vector** (Light Blue): Vector database operations
- **KV** (Orange): Key-value storage operations
- **LLM** (Pink): LLM-specific operations
- **Other** (Gray): Miscellaneous operations

Each span includes:
- Start and end timestamps
- Duration in milliseconds
- Relevant attributes (model used, tokens consumed, etc.)
- Parent-child relationships

### Viewing Span Details

Click on any span in the timeline to view detailed information in the sidebar:

<ThemeImage baseName="agent-session-detail-sidebar" alt="Span Detail Sidebar" />

## Performance Analysis

Use telemetry to identify bottlenecks:

1. **Long-running spans**: Operations taking excessive time
2. **Sequential operations**: Tasks that could run in parallel
3. **Repeated calls**: Opportunities for caching
4. **Token usage patterns**: Optimize prompt efficiency

## OpenTelemetry Integration

Agentuity uses OpenTelemetry standards, enabling:
- Export to external observability platforms
- Custom span creation for business logic
- Correlation across distributed systems
- Industry-standard tooling compatibility

For implementation details and code examples, see our SDK documentation for [JavaScript](/SDKs/javascript) and [Python](/SDKs/python).
Loading