diff --git a/content/Cloud/key-value-memory.mdx b/content/Cloud/key-value-memory.mdx index 92811064..0dc75be7 100644 --- a/content/Cloud/key-value-memory.mdx +++ b/content/Cloud/key-value-memory.mdx @@ -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. + \ No newline at end of file diff --git a/content/Cloud/meta.json b/content/Cloud/meta.json index 98a6a51b..29b6a6a0 100644 --- a/content/Cloud/meta.json +++ b/content/Cloud/meta.json @@ -6,6 +6,7 @@ "agents", "vector-memory", "key-value-memory", + "object-storage", "ai-gateway", "settings" ] diff --git a/content/Cloud/object-storage.mdx b/content/Cloud/object-storage.mdx new file mode 100644 index 00000000..fc06f6e5 --- /dev/null +++ b/content/Cloud/object-storage.mdx @@ -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. + + + +## 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. + + \ No newline at end of file diff --git a/content/Cloud/vector-memory.mdx b/content/Cloud/vector-memory.mdx index 0635ec77..350d75fd 100644 --- a/content/Cloud/vector-memory.mdx +++ b/content/Cloud/vector-memory.mdx @@ -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. + \ No newline at end of file diff --git a/content/Guides/.agent-logging.mdx b/content/Guides/.agent-logging.mdx deleted file mode 100644 index 0769e6f0..00000000 --- a/content/Guides/.agent-logging.mdx +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: Agent Logging -description: How to use logging in your agents ---- diff --git a/content/Guides/.agent-telemetry.mdx b/content/Guides/.agent-telemetry.mdx deleted file mode 100644 index 5cfc64f5..00000000 --- a/content/Guides/.agent-telemetry.mdx +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: Agent Telemetry -description: How to use telemetry in your agents ---- diff --git a/content/Guides/.agent-tracing.mdx b/content/Guides/.agent-tracing.mdx deleted file mode 100644 index fc331478..00000000 --- a/content/Guides/.agent-tracing.mdx +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: Agent Tracing -description: Understanding how to use tracing in your agents ---- diff --git a/content/Guides/.ai-gateway.mdx b/content/Guides/.ai-gateway.mdx deleted file mode 100644 index 6875f85a..00000000 --- a/content/Guides/.ai-gateway.mdx +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: Using AI Gateway -description: Using AI Gateway in your Agents ---- diff --git a/content/Guides/.devmode.mdx b/content/Guides/.devmode.mdx deleted file mode 100644 index a047ab4d..00000000 --- a/content/Guides/.devmode.mdx +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: Agent DevMode -description: Developing agents locally with DevMode ---- diff --git a/content/Guides/.key-value.mdx b/content/Guides/.key-value.mdx deleted file mode 100644 index 4bbc4964..00000000 --- a/content/Guides/.key-value.mdx +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: Using Key Value -description: Using Key Value storage in your Agents ---- diff --git a/content/Guides/.vector-db.mdx b/content/Guides/.vector-db.mdx deleted file mode 100644 index 3fc52f7b..00000000 --- a/content/Guides/.vector-db.mdx +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: Using Vector DB -description: Using the Vector DB for search and retrieval ---- diff --git a/content/Guides/agent-data-handling.mdx b/content/Guides/agent-data-handling.mdx index 6d45f572..0b20b4c7 100644 --- a/content/Guides/agent-data-handling.mdx +++ b/content/Guides/agent-data-handling.mdx @@ -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 diff --git a/content/Guides/agent-logging.mdx b/content/Guides/agent-logging.mdx new file mode 100644 index 00000000..e916aebf --- /dev/null +++ b/content/Guides/agent-logging.mdx @@ -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. + + + +### 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: + + + +**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: + + + +## Logging Best Practices + +### 1. Use Appropriate Log Levels + + + +### 2. Include Relevant Context + +Log enough information to understand what happened without re-running: + + + +### 3. Log Decision Points + +Help future debugging by logging key decisions: + + + +### 4. Avoid Logging Sensitive Data + +Never log passwords, tokens, or personal information: + + + +### 5. Use Child Loggers for Request Context + +Create child loggers to automatically include context in all related logs: + + + +## Structured Logging + +Use structured data for easier parsing and analysis: + + + +For more observability features, see [Agent Telemetry](/Guides/agent-telemetry) and [Agent Tracing](/Guides/agent-tracing). \ No newline at end of file diff --git a/content/Guides/agent-telemetry.mdx b/content/Guides/agent-telemetry.mdx new file mode 100644 index 00000000..86b8e3f2 --- /dev/null +++ b/content/Guides/agent-telemetry.mdx @@ -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. + + + +### 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: + + + +## 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: + + + +## 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). \ No newline at end of file diff --git a/content/Guides/agent-tracing.mdx b/content/Guides/agent-tracing.mdx new file mode 100644 index 00000000..111f342e --- /dev/null +++ b/content/Guides/agent-tracing.mdx @@ -0,0 +1,219 @@ +--- +title: Agent Tracing +description: Understanding how to use tracing in your agents +--- + +Agent tracing provides deep visibility into your agent's execution flow, performance, and behavior using OpenTelemetry. This enables debugging, performance monitoring, and understanding complex agent workflows. + +**Key benefits:** +- **Track execution flow** through agent operations +- **Identify performance bottlenecks** and slow operations +- **Debug errors** with detailed context and stack traces +- **Monitor agent performance** and resource usage +- Understand complex **multi-agent interactions** + +## OpenTelemetry Integration + +Agentuity integrates with OpenTelemetry, the industry-standard observability framework. The SDK provides access to tracing capabilities through the `context.tracer` object, allowing you to create spans that track your agent's operations. + +Traces consist of spans that represent individual operations. Spans can be nested to show parent-child relationships and include attributes, events, and timing information. + +## Basic Tracing + +### Creating Spans + +Create spans to track specific operations in your agent: + + { + return context.tracer.startActiveSpan('process-request', async (span) => { + try { + // Add attributes to identify the span + span.setAttribute('userId', '123'); + span.setAttribute('requestType', 'data-processing'); + + // Perform work + const result = await processData(); + + // Add events to mark important moments + span.addEvent('data-processed', { + itemCount: result.length + }); + + return response.json(result); + } catch (error) { + // Record errors in the span + span.recordException(error); + span.setStatus({ code: SpanStatusCode.ERROR }); + throw error; + } + // Span automatically ends when async callback completes + }); +}; + +export default handler;`} py={`from agentuity import AgentRequest, AgentResponse, AgentContext +from opentelemetry.trace.status import Status, StatusCode + +async def run(request: AgentRequest, response: AgentResponse, context: AgentContext): + async with context.tracer.start_as_current_span("process-request") as span: + try: + # Add attributes to identify the span + span.set_attribute("userId", "123") + span.set_attribute("requestType", "data-processing") + + # Perform work + result = await process_data() + + # Add events to mark important moments + span.add_event("data-processed", { + "itemCount": len(result) + }) + + return response.json(result) + except Exception as error: + # Record errors in the span + span.record_exception(error) + span.set_status(Status(StatusCode.ERROR)) + context.logger.error(f"Error processing: {str(error)}") + raise error`}/> + +### Span Attributes and Events + +**Attributes** provide metadata about the span (user IDs, operation types, parameters) +**Events** mark specific moments in time with additional context (milestones, state changes) + +## Advanced Tracing Patterns + +### Nested Spans + +Create nested spans to trace complex operations with multiple steps: + + { + return context.tracer.startActiveSpan('agent-request', async (parentSpan) => { + try { + parentSpan.setAttribute('trigger', request.trigger()); + const data = await request.data.json(); + + // Create child span for data processing + return await context.tracer.startActiveSpan('process-data', async (childSpan) => { + try { + childSpan.addEvent('processing-started', { + timestamp: Date.now() + }); + + const result = await complexDataProcessing(data); + + childSpan.addEvent('processing-completed', { + timestamp: Date.now(), + resultSize: JSON.stringify(result).length + }); + + childSpan.setStatus({ code: SpanStatusCode.OK }); + return response.json(result); + } catch (error) { + childSpan.recordException(error); + childSpan.setStatus({ + code: SpanStatusCode.ERROR, + message: error.message + }); + throw error; + } + // Span automatically ends when async callback completes + }); + } catch (error) { + parentSpan.recordException(error); + parentSpan.setStatus({ + code: SpanStatusCode.ERROR, + message: error.message + }); + + context.logger.error('Request failed', error); + return response.json({ + error: 'Request failed', + message: error.message + }); + } + // Span automatically ends when async callback completes + }); +}; + +export default handler;`} py={`import time +from agentuity import AgentRequest, AgentResponse, AgentContext +from opentelemetry.trace.status import Status, StatusCode + +async def run(request: AgentRequest, response: AgentResponse, context: AgentContext): + async with context.tracer.start_as_current_span("agent-request") as parent_span: + try: + parent_span.set_attribute("trigger", request.trigger()) + data = await request.data.json() + + # Create child span for data processing + async with context.tracer.start_as_current_span("process-data") as child_span: + try: + child_span.add_event("processing-started", { + "timestamp": time.time() + }) + + result = await complex_data_processing(data) + + child_span.add_event("processing-completed", { + "timestamp": time.time(), + "resultSize": len(str(result)) + }) + + child_span.set_status(Status(StatusCode.OK)) + return response.json(result) + except Exception as error: + child_span.record_exception(error) + child_span.set_status(Status(StatusCode.ERROR)) + raise error + except Exception as error: + parent_span.record_exception(error) + parent_span.set_status(Status(StatusCode.ERROR)) + + context.logger.error(f"Request failed: {str(error)}") + return response.json({ + "error": "Request failed", + "message": str(error) + })`}/> + +## Best Practices + +### When to Use Tracing +- **Complex operations**: Multi-step processes that could fail at various points +- **Performance monitoring**: Operations that might have performance issues +- **External calls**: API calls, database queries, or agent-to-agent communication +- **Error debugging**: Operations where you need detailed error context + +### Optimization Tips +- **Meaningful span names**: Use descriptive names that indicate the operation +- **Relevant attributes**: Include contextual information like user IDs, operation types +- **Strategic events**: Mark important milestones, not every small step +- **Error handling**: Always record exceptions and set appropriate status codes +- **Resource cleanup**: Ensure spans are properly ended (automatic in most cases) + +### Common Attributes +- `userId`: Identify which user triggered the operation +- `requestId`: Link related operations across agents +- `operationType`: Categorize different types of operations +- `resourceId`: Track operations on specific resources + +## Integration with Agent Operations + +Tracing works seamlessly with other Agentuity features: + +- **Storage operations**: Trace vector searches, key-value operations +- **Agent communication**: Track calls between agents +- **External integrations**: Monitor API calls and third-party services +- **Streaming responses**: Trace streaming operations and chunks + +You can view traces in the session timeline visualization: + + + +For more details on observability, see [Agent Logging](/Guides/agent-logging) for application logs and [Agent Telemetry](/Guides/agent-telemetry) for metrics and monitoring. diff --git a/content/Guides/ai-gateway.mdx b/content/Guides/ai-gateway.mdx new file mode 100644 index 00000000..5e51106d --- /dev/null +++ b/content/Guides/ai-gateway.mdx @@ -0,0 +1,127 @@ +--- +title: Using AI Gateway +description: Using AI Gateway in your Agents +--- + +## What is the AI Gateway? + +The AI Gateway provides seamless access to multiple AI providers through a single interface. It automatically routes your LLM requests, tracks usage and costs, and eliminates the need to manage individual API keys for each provider. + +## Supported Providers + +The AI Gateway supports the following providers out of the box: + +- **OpenAI** +- **Anthropic** +- **Google** +- **Cohere** +- **DeepSeek** +- **Grok** +- **Groq** +- **Mistral** +- **Perplexity** + +## How It Works + +### Automatic Detection + +When you use supported LLM SDKs without providing API keys, Agentuity automatically routes requests through the AI Gateway: + + + +### Using Your Own API Keys + +To bypass the AI Gateway and use your own API keys, simply provide them: + + + +## Cost Tracking and Monitoring + +### Session Overview + +Navigate to **Services > AI Gateway** in the Cloud Console to view: + +- **Agent**: Which agent made the request +- **Provider**: AI provider used (OpenAI, Anthropic, etc.) +- **Model**: Specific model used +- **LLM Cost**: Cost per request +- **Timestamp**: When the request was made + + + +### Detailed Session Analysis + +Click any session to view comprehensive details: + + + +- **Token usage**: Input and output token counts +- **Cost breakdown**: Per-token pricing and total cost +- **Request metadata**: Model, provider, and performance metrics +- **Trace information**: Full span details for debugging + +## Filtering and Search + +Use the filter options to analyze your AI usage: + +- **By Provider**: Compare costs across different AI providers +- **By Model**: Track usage of specific models +- **By Agent**: See which agents consume the most tokens +- **By Time Range**: Analyze usage patterns over time + + + +## Framework Integration + +AI Gateway works seamlessly with popular AI frameworks: + +### JavaScript +- OpenAI SDK +- Anthropic SDK +- Langchain.js +- Vercel AI SDK + +### Python +- OpenAI SDK +- Anthropic SDK +- LangChain +- LiteLLM + +The Agentuity CLI provides templates with these frameworks already configured. Since these frameworks use the underlying LLM SDKs, requests are routed through the AI Gateway when no API keys are provided. + +## Telemetry Integration + +AI Gateway spans appear in your [agent telemetry](/Guides/agent-telemetry) with: +- Request duration +- Token counts +- Cost information +- Provider details + +This integration enables you to track costs, monitor usage patterns, and understand the full performance impact of AI calls in your agent workflows. \ No newline at end of file diff --git a/content/Guides/devmode.mdx b/content/Guides/devmode.mdx new file mode 100644 index 00000000..5c45b890 --- /dev/null +++ b/content/Guides/devmode.mdx @@ -0,0 +1,203 @@ +--- +title: Agent DevMode +description: Developing agents locally with DevMode +--- + +## What is DevMode? + +DevMode is Agentuity's local development environment that lets you test and debug your agents before deploying them to the cloud. It provides the exact same interface and capabilities you'll have in production. + +**Key benefits:** +- **Instant feedback** on agent behavior and responses +- **Complete observability** with real-time logs, sessions, and detailed traces +- **Cost visibility** to monitor token usage and LLM costs +- **Performance insights** to identify potential bottlenecks + +## Starting DevMode + +Run the following command in your project directory: + + +Agentuity DevMode + +DevMode https://app.agentuity.com/devmode/[agent-id] +Port http://127.0.0.1:3500 +Public https://dev-[hash].agentuity.run/ + +[INFO] Loading config from /path/to/your/project/agentuity/config.json +[INFO] Starting server on port 3500 + Listening on http://127.0.0.1:3500 =======> +(Press Ctrl+C to exit) +[INFO] 🚀 DevMode ready + + +DevMode provides: +- **Local development server** on port 3500 (configurable) +- **Web interface** for testing and monitoring at the provided URL +- **Public URL** for external access while the server is running + +## The DevMode Interface + +### CLI Input Section + +The CLI Input section is where you test your agents with various input types and scenarios. This interface is powered by your agent's `welcome()` function configuration. + + + +**Input Types Available:** +- **JSON**: Structured data for API-like interactions +- **HTML**: Rich content and web-based inputs +- **Markdown**: Documentation and formatted text +- **Text**: Plain text for conversational interfaces + +**Key Features:** +- **Agent Selection**: Choose which agent to test from the dropdown +- **Pre-configured Prompts**: Sample inputs defined in the `welcome()` function +- **Custom Inputs**: Write your own test scenarios +- **Run Button**: Execute tests instantly and see results + +### Configuring the Welcome Function + +Your agent's `welcome()` function defines the test scenarios available in DevMode: + + { + return { + "welcome": "Welcome to your agent! Send a message to get started.", + "prompts": [ + { + "data": "Hello, how can you help me?", + "contentType": "text/plain" + }, + { + "data": JSON.stringify({"query": "What is AI?", "format": "brief"}), + "contentType": "application/json" + }, + { + "data": "# Research Request\\n\\nPlease analyze current market trends", + "contentType": "text/markdown" + }, + { + "data": "

HTML Content

Process this HTML document

", + "contentType": "text/html" + } + ] + }; +};`} py={`def welcome(): + return { + "welcome": "Welcome to your agent! Send a message to get started.", + "prompts": [ + { + "data": "Hello, how can you help me?", + "contentType": "text/plain" + }, + { + "data": '{"query": "What is AI?", "format": "brief"}', + "contentType": "application/json" + }, + { + "data": "# Research Request\\n\\nPlease analyze current market trends", + "contentType": "text/markdown" + }, + { + "data": "

HTML Content

Process this HTML document

", + "contentType": "text/html" + } + ] + } +`} /> + +These prompts appear as clickable examples in the DevMode interface, making it easy to test common scenarios and edge cases. + +## Monitoring and Debugging + +### Sessions Tab + +Track your test runs with details on status, duration, costs, and performance metrics. + + + + +DevMode sessions are temporary and cleared when you exit DevMode. For persistent production analytics, see [Agent Telemetry](/Guides/agent-telemetry). + + +### Logs Tab + +Watch your agent's execution logs in real-time with structured timestamps, severity levels, and debug information. + + + + +DevMode logs are temporary and cleared when you exit DevMode. For persistent production logs, see [Agent Logging](/Guides/agent-logging). + + +## Best Practices + +### 1. Design Comprehensive Test Scenarios + +Create a robust `welcome()` function that covers various use cases: + + { + return { + "welcome": "Welcome to your agent! Send a message to get started.", + "prompts": [ + // Happy path + { + "data": "Normal user request", + "contentType": "text/plain" + }, + // Edge cases + { + "data": "", + "contentType": "text/plain" + }, + // Structured data + { + "data": JSON.stringify({"query": "structured request"}), + "contentType": "application/json" + }, + // Complex scenarios + { + "data": "Multi-step task with specific requirements", + "contentType": "text/plain" + } + ] + }; +};`} py={`def welcome(): + return { + "welcome": "Welcome to your agent! Send a message to get started.", + "prompts": [ + # Happy path + { + "data": "Normal user request", + "contentType": "text/plain" + }, + # Edge cases + { + "data": "", + "contentType": "text/plain" + }, + # Structured data + { + "data": '{"query": "structured request"}', + "contentType": "application/json" + }, + # Complex scenarios + { + "data": "Multi-step task with specific requirements", + "contentType": "text/plain" + } + ] + } +`} /> + +### 2. Test Thoroughly Before Production + +- **Monitor costs** during development to avoid surprises +- **Check performance** using the session timeline views +- **Validate edge cases** with your comprehensive test scenarios + +### 3. Remember DevMode Limitations + +- **Sessions and logs are temporary** - they won't persist after stopping DevMode +- **Use production deployments** for persistent monitoring and analytics +- **Test with realistic data** to ensure production readiness diff --git a/content/Guides/key-value.mdx b/content/Guides/key-value.mdx new file mode 100644 index 00000000..552736e5 --- /dev/null +++ b/content/Guides/key-value.mdx @@ -0,0 +1,197 @@ +--- +title: Using Key Value +description: Using Key Value storage in your Agents +--- + +## When to Use Key-Value Storage + +Key-value storage is your go-to solution for fast, ephemeral data that agents need to access quickly. Think of it as your agent's short-term memory — perfect for session state, configuration, caching, and temporary data. + +Choose the right storage for your use case: + +- **Key-Value**: Fast lookups, simple data, temporary state +- **[Vector Storage](/Cloud/vector-memory)**: Semantic search, embeddings, similarity matching +- **[Object Storage](/Cloud/object-storage)**: Large files, media, backups + +## Common Use Cases + +- **Session Management**: Store user sessions, authentication tokens, and temporary state between agent interactions +- **Configuration Storage**: Keep agent-specific settings, feature flags, and runtime configuration that can be updated without redeployment +- **Caching**: Cache expensive computation results, API responses, or frequently accessed data to improve agent performance +- **Inter-Agent Communication**: Share state between agents working together on complex workflows +- **Rate Limiting**: Track API usage, request counts, and implement throttling mechanisms + +## Creating Key-Value Storage + +You can create key-value storage either through the Cloud Console or programmatically in your agent code. + +### Via Cloud Console + +Navigate to **Services > Key Value** and click **Create Storage**. Choose a descriptive name that reflects the storage purpose (e.g., `user-sessions`, `agent-config`, `api-cache`). + + + +### Via SDK + +Both JavaScript and Python SDKs automatically create key-value storage when you first access it: + + { + // Storage is created automatically on first use + await context.kv.set('user-sessions', 'user-123', { + lastSeen: new Date().toISOString(), + preferences: { theme: 'dark' } + }); + + return response.json({ message: 'Session stored' }); +}; + +export default handler;`} py={`# Python +from agentuity import AgentRequest, AgentResponse, AgentContext +from datetime import datetime + +async def run(request: AgentRequest, response: AgentResponse, context: AgentContext): + # Storage is created automatically on first use + await context.kv.set("user-sessions", "user-123", { + "lastSeen": datetime.now().isoformat(), + "preferences": {"theme": "dark"} + }) + + return response.json({"message": "Session stored"}) +`} /> + +## Working with Key-Value Storage + +The key-value API provides three core operations: `get`, `set`, and `delete`. All operations are asynchronous and support various data types. + +### Storing Data + +Store strings, objects, or binary data with optional TTL (time-to-live): + + + +### Retrieving Data + +Retrieve stored values with automatic deserialization: + + + +### Deleting Data + +Remove keys when they're no longer needed: + + + +## Best Practices + +### Key Naming Conventions + +Use hierarchical, descriptive keys to organize your data: +- `user:{userId}:preferences` +- `session:{sessionId}:data` +- `cache:api:{endpoint}:{params}` + +### Error Handling + +Always handle potential storage errors gracefully: + + + +### TTL Strategy + +Use TTL for temporary data to prevent storage bloat: +- **Session data**: 24-48 hours +- **API cache**: 5-60 minutes +- **Rate limiting counters**: Until period reset + +### Data Size Considerations + +Key-value storage is optimized for small to medium-sized values. For large files or documents, consider using [Object Storage](/Cloud/object-storage) instead. + +## Monitoring Usage + +Track your key-value storage usage through the Cloud Console: + +1. Navigate to **Services > Key Value** +2. View storage size and record count for each instance +3. Click on an instance to browse stored keys and values +4. Monitor [agent telemetry](/Guides/agent-telemetry) for KV operation performance + + + +For more complex data relationships or query needs, consider combining storage types or using external databases through your agent. \ No newline at end of file diff --git a/content/Guides/meta.json b/content/Guides/meta.json index 3e097bcf..bcdd7314 100644 --- a/content/Guides/meta.json +++ b/content/Guides/meta.json @@ -4,10 +4,14 @@ "what-is-an-agent", "agent-native-cloud", "agent-engineering", + "devmode", + "agent-logging", + "agent-telemetry", "...", "ai-gateway", "key-value", "vector-db", + "object-storage", "security" ] } diff --git a/content/Guides/object-storage.mdx b/content/Guides/object-storage.mdx new file mode 100644 index 00000000..f48e9b10 --- /dev/null +++ b/content/Guides/object-storage.mdx @@ -0,0 +1,393 @@ +--- +title: Using Object Storage +description: Using Object Storage for files and media in your Agents +--- + +## When to Use Object Storage + +Object storage is your solution for storing files, media, and large unstructured data that agents need to manage. Think of it as your agent's file system — perfect for documents, images, videos, backups, and any binary content. + +Choose the right storage for your use case: + +- **Object Storage**: Files, media, documents, backups +- **[Key-Value Storage](/Cloud/key-value-memory)**: Fast lookups, session data, configuration +- **[Vector Storage](/Cloud/vector-memory)**: Semantic search, embeddings, AI context + +## Common Use Cases + +- **File Management**: Store user uploads, generated documents, and processed files +- **Media Storage**: Keep images, videos, audio files, and other media assets +- **Document Processing**: Store PDFs, spreadsheets, and documents for agent processing +- **Backup and Archive**: Maintain backups of agent-generated content or historical data +- **Static Asset Serving**: Host files that can be accessed via public URLs +- **Data Export**: Store generated reports, exports, and downloadable content + +## Creating Object Storage + +You can create object storage buckets either through the Cloud Console or programmatically in your agent code. + +### Via Cloud Console + +Navigate to **Services > Object Store** and click **Create Storage**. Choose a descriptive bucket name that reflects its purpose (e.g., `user-uploads`, `processed-documents`, `media-assets`). + + + +### Via SDK + +Both JavaScript and Python SDKs automatically create buckets when you first access them: + + { + // Bucket is created automatically on first use + const imageData = Buffer.from(await request.data.binary()); + + await context.objectstore.put('user-uploads', 'profile-123.jpg', imageData, { + contentType: 'image/jpeg' + }); + + return response.json({ message: 'Image uploaded successfully' }); +}; + +export default handler;`} py={`# Python +from agentuity import AgentRequest, AgentResponse, AgentContext + +async def run(request: AgentRequest, response: AgentResponse, context: AgentContext): + # Bucket is created automatically on first use + image_data = await request.data.binary() + + await context.objectstore.put("user-uploads", "profile-123.jpg", image_data, { + "content_type": "image/jpeg" + }) + + return response.json({"message": "Image uploaded successfully"}) +`} /> + +## Working with Object Storage + +The object storage API provides four core operations: `get`, `put`, `delete`, and `createPublicURL`. All operations are asynchronous and support various content types. + +### Storing Objects + +Store files with automatic content type detection or explicit metadata: + + + +### Retrieving Objects + +Retrieve stored objects with automatic format handling: + + + +### Generating Public URLs + +Create time-limited public URLs for direct access to objects: + + + +### Deleting Objects + +Remove objects when they're no longer needed: + + + +## Best Practices + +### Bucket Organization + +Structure your buckets by purpose and access patterns: +- `user-uploads`: User-submitted content +- `processed-output`: Agent-generated results +- `public-assets`: Files meant for public access +- `temp-storage`: Short-lived processing files + +### Key Naming Conventions + +Use hierarchical paths for better organization: +- `users/{userId}/profile.jpg` +- `documents/{year}/{month}/report-{id}.pdf` +- `exports/{timestamp}/data.csv` + +### Content Type Management + +Always set appropriate content types for better browser handling: + + + +### Public URL Security + +Use appropriate expiration times for public URLs: +- **Temporary downloads**: 5-15 minutes +- **Shared documents**: 1-24 hours +- **Never**: Create permanent public URLs for sensitive data + +### Error Handling + +Handle storage operations gracefully: + + + +## File Processing Patterns + +### Upload Handler + +Create a robust file upload handler: + + { + const contentType = request.headers.get('content-type') || ''; + const fileName = request.headers.get('x-filename') || 'upload'; + + // Store the uploaded file + const fileData = await request.data.binary(); + const key = \`uploads/\${Date.now()}-\${fileName}\`; + + await context.objectstore.put('user-files', key, fileData, { + contentType, + metadata: { + 'original-name': fileName, + 'upload-time': new Date().toISOString() + } + }); + + // Generate access URL + const url = await context.objectstore.createPublicURL( + 'user-files', + key, + 3600000 + ); + + return response.json({ + message: 'File uploaded successfully', + key, + url + }); +};`} py={`async def run(request: AgentRequest, response: AgentResponse, context: AgentContext): + content_type = request.headers.get("content-type", "") + file_name = request.headers.get("x-filename", "upload") + + # Store the uploaded file + file_data = await request.data.binary() + key = f"uploads/{int(time.time())}-{file_name}" + + await context.objectstore.put("user-files", key, file_data, { + "content_type": content_type, + "metadata": { + "original-name": file_name, + "upload-time": datetime.now().isoformat() + } + }) + + # Generate access URL + url = await context.objectstore.create_public_url( + "user-files", + key, + 3600000 + ) + + return response.json({ + "message": "File uploaded successfully", + "key": key, + "url": url + })`} /> + +## Monitoring Usage + +Track your object storage usage through the Cloud Console: + +1. Navigate to **Services > Object Store** +2. View storage size and object count for each bucket +3. Monitor provider information and creation dates +4. Use [agent telemetry](/Guides/agent-telemetry) to track storage operations + +For structured data with complex queries, consider using object storage to store data exports while maintaining indexes in key-value or vector storage. \ No newline at end of file diff --git a/content/Guides/vector-db.mdx b/content/Guides/vector-db.mdx new file mode 100644 index 00000000..a75174f3 --- /dev/null +++ b/content/Guides/vector-db.mdx @@ -0,0 +1,206 @@ +--- +title: Using Vector DB +description: Using the Vector DB for search and retrieval +--- + +Vector storage enables semantic search for your agents, allowing them to find information by meaning rather than keywords. Ideal for knowledge bases, RAG systems, and persistent agent memory. + +## Understanding Vector Storage + +Vector storage works by converting text into high-dimensional numerical representations (embeddings) that capture semantic meaning. When you search, the system finds documents with similar meanings rather than just keyword matches. + +**Key use cases:** +- Knowledge bases and documentation search +- Long-term memory across agent sessions +- RAG systems combining retrieval with AI generation +- Semantic similarity search + +## Managing Vector Instances + +### Viewing Vector Storage in the Cloud Console + +Navigate to **Services > Vector** in the Agentuity Cloud Console to view all your vector storage instances. The interface shows: + +- **Database Name**: The identifier for your vector storage +- **Projects**: Which projects are using this storage +- **Agents**: Which agents have access +- **Size**: Storage utilization + +You can filter instances by name using the search box and create new vector storage instances with the **Create Storage** button. + + + +### Creating Vector Storage + +You can create vector storage either through the Cloud Console or programmatically in your agent code. + +#### Via Cloud Console + +Navigate to **Services > Vector** and click **Create Storage**. Choose a descriptive name that reflects the storage purpose (e.g., `knowledge-base`, `agent-memory`, `product-catalog`). + +#### Via SDK + +Vector storage is created automatically when your agent first calls `context.vector.upsert()` with an instance name: + +## Vector Storage API + +### Upserting Documents + +The `upsert` operation inserts new documents or updates existing ones. You can provide either text (which gets automatically converted to embeddings) or pre-computed embeddings. + + +```javascript +// JavaScript/TypeScript +// Upsert documents with text (automatic embedding) +const ids = await context.vector.upsert( + 'knowledge-base', + { + document: 'Agentuity is an agent-native cloud platform', + metadata: { category: 'platform', source: 'docs' } + }, + { + document: 'Vector storage enables semantic search capabilities', + metadata: { category: 'features', source: 'docs' } + } +); + +// Upsert with pre-computed embeddings +const embeddingIds = await context.vector.upsert( + 'custom-embeddings', + { + embeddings: [0.1, 0.2, 0.3, 0.4], + metadata: { id: 'doc-1', type: 'custom' } + } +); +``` + +```python +# Python +# Upsert documents with text +documents = [ + { + "document": "Agentuity is an agent-native cloud platform", + "metadata": {"category": "platform", "source": "docs"} + }, + { + "document": "Vector storage enables semantic search capabilities", + "metadata": {"category": "features", "source": "docs"} + } +] + +ids = await context.vector.upsert("knowledge-base", *documents) + +# Upsert with embeddings +embedding_docs = [ + { + "embeddings": [0.1, 0.2, 0.3, 0.4], + "metadata": {"id": "doc-1", "type": "custom"} + } +] + +ids = await context.vector.upsert("custom-embeddings", *embedding_docs) +``` + + +### Searching Vector Storage + +Search operations find semantically similar documents based on a text query. You can control the number of results, similarity threshold, and filter by metadata. + + +```javascript +// JavaScript/TypeScript +// Basic semantic search +const results = await context.vector.search('knowledge-base', { + query: 'What is an agent platform?', + limit: 5, + similarity: 0.7, + metadata: { category: 'platform' } +}); + +// Process results +results.forEach(result => { + console.log(`Found: ${result.metadata.source}`); + console.log(`Similarity: ${1 - result.distance}`); +}); +``` + +```python +# Python +# Semantic search with parameters +results = await context.vector.search( + "knowledge-base", + query="What is an agent platform?", + limit=5, + similarity=0.7, + metadata={"category": "platform"} +) + +# Process results +for result in results: + similarity_score = 1.0 - result.distance + print(f"Found: {result.metadata['source']}") + print(f"Similarity: {similarity_score}") +``` + + +**Search Parameters:** +- `query` (required): Text query to search for +- `limit` (optional): Maximum number of results to return +- `similarity` (optional): Minimum similarity threshold (0.0-1.0) +- `metadata` (optional): Filter results by metadata key-value pairs + +### Deleting Vectors + +Remove specific vectors from storage using their IDs. + + +```javascript +// JavaScript/TypeScript +// Delete single vector +const deletedCount = await context.vector.delete('knowledge-base', 'vector-id-1'); + +// Delete multiple vectors +const bulkDeleteCount = await context.vector.delete( + 'knowledge-base', + 'id-1', 'id-2', 'id-3' +); +``` + +```python +# Python +# Delete single vector +count = await context.vector.delete("knowledge-base", "vector-id-1") + +# Note: Python SDK currently supports single deletion +# For bulk operations, call delete multiple times +``` + + + +## Best Practices + +### Document Structure +- **Include context in documents**: Store enough context so documents are meaningful when retrieved +- **Use descriptive metadata**: Include relevant metadata for filtering and identification +- **Consistent formatting**: Use consistent document formatting for better embeddings + +### Search Optimization +- **Adjust similarity thresholds**: Start with 0.7 and adjust based on result quality +- **Use metadata filtering**: Combine semantic search with metadata filters for precise results +- **Limit result sets**: Use appropriate limits to balance performance and relevance + +### Performance Considerations +- **Batch upsert operations**: Use bulk upsert instead of individual calls +- **Monitor storage usage**: Track vector storage size in the Cloud Console +- **Consider document chunking**: Break large documents into smaller, focused chunks + +## Integration with Agent Memory + +Vector storage serves as long-term memory for agents, enabling them to: + +- Remember past conversations and context across sessions +- Access organizational knowledge bases +- Retrieve relevant examples for few-shot learning +- Build and maintain agent-specific knowledge repositories + +For more information on memory patterns, see the [Key-Value Storage guide](/Guides/key-value) for short-term memory or explore [Agent Communication](/Guides/agent-communication) for sharing knowledge between agents. diff --git a/public/images/agent-logs-filter-dark.png b/public/images/agent-logs-filter-dark.png new file mode 100644 index 00000000..5435b256 Binary files /dev/null and b/public/images/agent-logs-filter-dark.png differ diff --git a/public/images/agent-logs-filter-light.png b/public/images/agent-logs-filter-light.png new file mode 100644 index 00000000..94f89343 Binary files /dev/null and b/public/images/agent-logs-filter-light.png differ diff --git a/public/images/aigateway-filters-dark.png b/public/images/aigateway-filters-dark.png new file mode 100644 index 00000000..0dd2a6b1 Binary files /dev/null and b/public/images/aigateway-filters-dark.png differ diff --git a/public/images/aigateway-filters-light.png b/public/images/aigateway-filters-light.png new file mode 100644 index 00000000..1eb8fa50 Binary files /dev/null and b/public/images/aigateway-filters-light.png differ diff --git a/public/images/devmode-interface-dark.png b/public/images/devmode-interface-dark.png new file mode 100644 index 00000000..c3f6701e Binary files /dev/null and b/public/images/devmode-interface-dark.png differ diff --git a/public/images/devmode-interface-light.png b/public/images/devmode-interface-light.png new file mode 100644 index 00000000..f0aca026 Binary files /dev/null and b/public/images/devmode-interface-light.png differ diff --git a/public/images/devmode-logs-dark.png b/public/images/devmode-logs-dark.png new file mode 100644 index 00000000..3dfabb46 Binary files /dev/null and b/public/images/devmode-logs-dark.png differ diff --git a/public/images/devmode-logs-light.png b/public/images/devmode-logs-light.png new file mode 100644 index 00000000..f01429d1 Binary files /dev/null and b/public/images/devmode-logs-light.png differ diff --git a/public/images/devmode-sessions-dark.png b/public/images/devmode-sessions-dark.png new file mode 100644 index 00000000..04fe18db Binary files /dev/null and b/public/images/devmode-sessions-dark.png differ diff --git a/public/images/devmode-sessions-light.png b/public/images/devmode-sessions-light.png new file mode 100644 index 00000000..3a0484ed Binary files /dev/null and b/public/images/devmode-sessions-light.png differ diff --git a/public/images/keyvalue-new-dark.png b/public/images/keyvalue-new-dark.png index 95a215ff..49624113 100644 Binary files a/public/images/keyvalue-new-dark.png and b/public/images/keyvalue-new-dark.png differ diff --git a/public/images/keyvalue-new-light.png b/public/images/keyvalue-new-light.png index cd4cdb0c..0e899caf 100644 Binary files a/public/images/keyvalue-new-light.png and b/public/images/keyvalue-new-light.png differ diff --git a/public/images/object-store-dark.png b/public/images/object-store-dark.png new file mode 100644 index 00000000..e328d8ee Binary files /dev/null and b/public/images/object-store-dark.png differ diff --git a/public/images/object-store-light.png b/public/images/object-store-light.png new file mode 100644 index 00000000..985866bb Binary files /dev/null and b/public/images/object-store-light.png differ diff --git a/public/images/object-store-new-dark.png b/public/images/object-store-new-dark.png new file mode 100644 index 00000000..f0a9fa14 Binary files /dev/null and b/public/images/object-store-new-dark.png differ diff --git a/public/images/object-store-new-light.png b/public/images/object-store-new-light.png new file mode 100644 index 00000000..b75fb0ee Binary files /dev/null and b/public/images/object-store-new-light.png differ diff --git a/public/images/vector-new-dark.png b/public/images/vector-new-dark.png index c7c22e86..b767fd50 100644 Binary files a/public/images/vector-new-dark.png and b/public/images/vector-new-dark.png differ diff --git a/public/images/vector-new-light.png b/public/images/vector-new-light.png index 7d898faf..402dda73 100644 Binary files a/public/images/vector-new-light.png and b/public/images/vector-new-light.png differ