> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gulp.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Enhance Task

> API reference for the enhance task endpoint

The `/enhance_task` endpoint enriches tasks with relevant knowledge and context to improve agent responses.

This endpoint should be used whenever a user is prompting an agent.
If your agent spawns sub sub agents, each sub task should also call this endpoint.

## Base URL

```bash
POST https://osmosis.gulp.dev/enhance_task
```

## Authentication

<RequestHeader>
  <HeaderParameter name="Content-Type" required type="string">
    application/json
  </HeaderParameter>

  <HeaderParameter name="x-api-key" required type="string">
    Your API key
  </HeaderParameter>
</RequestHeader>

## Request Body

### Root Level Parameters

<ParamField body="tenant_id" type="string" required>
  Unique identifier that corresponds to a dedicated recommendation collection, enabling sub-tenancy isolation for different agentic workflows.
</ParamField>

<ParamField body="input_text" type="string" required>
  The agent's input/query. This can be a user prompt, or the task given to a sub agent.
</ParamField>

<ParamField body="agent_type" type="string">
  Type of agent making the request (e.g., 'browser', 'orchestrator'). Best used in multi-agent environments.
</ParamField>

## Example Requests

<CodeGroup>
  ```bash cURL
  curl -X POST https://osmosis.gulp.dev/enhance_task \
    -H "Content-Type: application/json" \
    -H "x-api-key: your-api-key" \
    -d '{
      "tenant_id": "api_key",
      "input_text": "Process refund request for damaged item",
      "agent_type": "support_agent"
    }'
  ```

  ```typescript TypeScript
  import axios from 'axios';

  async function enhanceTask() {
    const apiKey = process.env.OSMOSIS_API_KEY;
    
    const payload = {
      tenant_id: 'api_key',
      input_text: 'Process refund request for damaged item',
      agent_type: 'support_agent'
    };

    const response = await axios.post('https://osmosis.gulp.dev/enhance_task', payload, {
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': apiKey
      }
    });
    
    return response.data;
  }
  ```

  ```python Python
  import os
  import requests

  def enhance_task():
      api_key = os.getenv('OSMOSIS_API_KEY')
      
      payload = {
          "tenant_id": "api_key",
          "input_text": "Process refund request for damaged item",
          "agent_type": "support_agent"
      }
      
      response = requests.post(
          "https://osmosis.gulp.dev/enhance_task",
          json=payload,
          headers={
              "Content-Type": "application/json",
              "x-api-key": api_key
          }
      )
      
      return response.json()
  ```

  ```go Go
  package main

  import (
      "bytes"
      "encoding/json"
      "net/http"
      "os"
  )

  type EnhanceTaskPayload struct {
      TenantID  string `json:"tenant_id"`
      InputText string `json:"input_text"`
      AgentType string `json:"agent_type,omitempty"`
  }

  func enhanceTask() ([]byte, error) {
      apiKey := os.Getenv("OSMOSIS_API_KEY")
      
      payload := EnhanceTaskPayload{
          TenantID:  "api_key",
          InputText: "Process refund request for damaged item",
          AgentType: "support_agent",
      }

      jsonData, err := json.Marshal(payload)
      if err != nil {
          return nil, err
      }

      req, err := http.NewRequest("POST", "https://osmosis.gulp.dev/enhance_task", bytes.NewBuffer(jsonData))
      if err != nil {
          return nil, err
      }

      req.Header.Set("Content-Type", "application/json")
      req.Header.Set("x-api-key", apiKey)

      client := &http.Client{}
      resp, err := client.Do(req)
      if err != nil {
          return nil, err
      }
      defer resp.Body.Close()

      return json.Marshal(resp)
  }
  ```
</CodeGroup>

## Response

### Success Response

<ResponseField name="response" type="string" required>
  The processed response with enhanced context and recommendations
</ResponseField>

<ResponseField name="metadata" type="object">
  Additional metadata about the enhancement process and results
</ResponseField>

Example success response:

```json
{
  "response": "Process refund request for damaged item, note that the item is damaged and the user has not provided a valid reason for the refund. Check the company return policy manual for section 1.2 on damaged items.",
  "metadata": {
    "confidence_score": 0.45,
    "agent_type": "support_agent"
  }
}
```

<Note>
  The confidence score in the metadata is currently a simple computation based on our [Monte Carlo Tree Search](https://llm-mcts.github.io/) process.
  While it provides a general indication, it should not be treated as a definitive metric of response quality at this stage.
  We only provide confidence score if it is below 0.7
</Note>

### Error Response

<ResponseField name="detail" type="array" required>
  Array of error details
</ResponseField>

Example error response:

```json
{
  "detail": [
    {
      "loc": ["body", "tenant_id"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}
```

## Status Codes

<ResponseStatus code={200} status="OK">
  Task enhancement completed successfully
</ResponseStatus>

<ResponseStatus code={422} status="Unprocessable Entity">
  Invalid request (validation error)
</ResponseStatus>

## Error Codes

| Code                  | Description                  |
| --------------------- | ---------------------------- |
| `value_error.missing` | Required field is missing    |
| `value_error.json`    | Invalid JSON in request body |
| `type_error`          | Incorrect type for a field   |
| `value_error`         | Invalid value for a field    |

## Best Practices

1. **Request Timing**
   * Call this endpoint before agent execution
   * Use it for both main tasks and sub-tasks

2. **Input Text Formatting**
   * Keep input text clear and specific
   * Include relevant context
   * Use consistent formatting across requests

3. **Agent Type Usage**
   * Always specify agent\_type when using multiple agents
   * Use consistent agent type names
   * Document agent types in your system

4. **Error Handling**
   * Implement proper retry logic
   * Cache successful responses
   * Handle validation errors gracefully