[llms-txt]: # (For AI agents: the complete documentation index is at https://developers.tetrascience.com/llms.txt — markdown versions of any page are available by appending .md to the URL.) This guide shows how to use and configure [Tetra HTTP Relay Agent](https://developers.tetrascience.com/docs/tetra-http-relay-agent) versions 1.0.X after the Agent is [installed](https://developers.tetrascience.com/docs/tetra-http-relay-agent-installation-guide-v10x). # Reconfigure the Agent To reconfigure the Tetra HTTP Relay Agent, you must first stop the Agent's container that's running on the Agent's host server. Then, you can run the container with a new configuration. You can't apply a new configuration to a running Tetra HTTP Relay Agent. To stop the Agent, run the following command from the local host server's terminal: > ```sh > docker stop $CONTAINER_ID > ``` > 🚧 IMPORTANT > > Stopping the Agent can interrupt commands that are still processing. For this reason, it's recommended that you temporarily deactivate any associated pipelines and services while you reconfigure the Agent. To start your Agent with a new configuration, run the `docker run $IMAGE_NAME` command with new parameters. For instructions, see the [Tetra HTTP Relay Agent Installation Guide (v1.0.x)](https://developers.tetrascience.com/docs/tetra-http-relay-agent-installation-guide-v10x). It may be important to reuse the same Docker parameters that are used in the initial deployment. Make sure that you review the container status and Agent logs to verify agent health after restarting the container. # Send HTTP or HTTPS Requests to a Target System The Tetra HTTP Relay Agent relays HTTP and HTTPS requests by polling the [TDP Command Service](https://developers.tetrascience.com/docs/command-service) for commands. The Agent then parses commands retrieved from the TDP Command Service and sends their corresponding HTTP or HTTPS requests to the target service(s). The response from the requests are relayed back to the TDP Command Service. Customer applications that send commands to the Tetra HTTP Relay Agent can send a `POST` request to the Command Service directly by using the [Create Command API endpoint](https://developers.tetrascience.com/reference/ag-create-command). Tetra Data Pipelines that send commands to the Tetra HTTP Relay Agent can use the [Context API](https://developers.tetrascience.com/docs/context-api) from within their task scripts. For example, you can use the [`context.run_cmd()` method](https://developers.tetrascience.com/docs/context-api#contextrun_command) to send a command to the Agent and await the result of the Agent's command handling. The TetraScience context API will return the command `responseBody` when the command reaches a terminal status. More information on command outcomes is below. ## Supported Command Actions The Tetra HTTP Relay Agent supports the following command actions, which are specified in the `action` field of the command: * [`TetraScience.Connector.gdc.HttpRequest`](https://developers.tetrascience.com/docs/context-api#contextrun_command): This is a legacy command used by the [Generic Data Connector](https://developers.tetrascience.com/docs/generic-data-connector-1), which can also be processed by the Tetra HTTP Relay Agent. * `TetraScience.Connector.http.Request`. This command action offers a configurable timeout parameter, enabling the Tetra HTTP Relay AGent to fail commands and HTTP or HTTPS requests that timeout. * `TetraScience.Connector.http.Request.V2`. This command action encrypts the contents of the HTTP or HTTP request body. Commands whose `command.action` field does not match one of the supported command actions will be marked as `rejected` by the agent. ## Command Payload Definition What follows is the definition for the `command.payload` field, also known as the request body, for the command. The content of the command payload should fully specify a HTTP or HTTPS request to the target system. ## Common HTTP Relay-Supported Command Payload fields The Tetra HTTP Relay Agent recognizes the following fields of the `TetraScience.Connector.http.Request` and `TetraScience.Connector.http.Request.V2` command actions: | Field | Required | Data Type | Definition | | :----------------------- | :------: | :-------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------------- | | `method` | required | string | One of the following HTTP Request methods: 'GET', 'POST', 'PUT', 'PATCH', 'DELETE' 'HEAD', 'OPTIONS'. | | `url` | required | string | Full URL to the target system and API endpoint (for example, `https://localhost:3000/route/to/endpoint?send=true&query=param`). | | `ignore_tls_certificate` | optional | boolean | Determines if the Tetra HTTP Relay Agent ignores TLS certificates or not. | | `headers` | optional | JSON `object` or `object[]` | Optional headers to add to the HTTP or HTTPS request. | | `timeout` | optional | number | How long the Tetra HTTP Relay Agent will wait before failing the HTTP or HTTPS request, measured in milliseconds. The default value is `10000`. | | `body` | optional | JSON | The body must conform to one of the following JSON definitions. | When the HTTP or HTTPS requests require a body/data to send to the target server, the Tetra HTTP Relay Agent can prepare a corresponding request if the `body` is in one of the following formats: ### Raw Request Body A `raw` request body is converted to JSON directly by parsing the `.raw` field and using that as the HTTP or HTTPS request data. The following is an example `raw` request body: ```json { "mode": "raw", "raw": "{\"message\":\"Hello world\"}" } ``` ### Formdata Request Body A `formdata` request body is converted to [RFC 2388](https://www.ietf.org/rfc/rfc2388.txt) form-data by parsing the `.formdata` field, which must be a JSON array of objects with fields `key` and `value`, and using that as the HTTP or HTTPS request data. The following is an example `formdata` request body: ```json { "mode": "formdata", "formdata": [{"key": "requestor", "value": "TetraScience"}] } ``` ### URL-Encoded Request Body A `URL-encoded` request body is converted to an `application/x-www-form-urlencoded` request. The HTTP Relay Agent expects a JSON array of objects with fields `key` and `value`, and converts that to a URL-encoded body for the HTTP or HTTPS request data. The following is an example `URL-encoded` request body: ```json { "mode": "urlencoded", "urlencoded": [{"key": "requestor", "value": "TetraScience"}] } ``` ## Encrypted Commands To apply end-to-end encryption to your commands, use the `TetraScience.Connector.http.Request.V2` command. The command uses AES 256 encryption and Pipelines and other requestors that use it must use the same 256-bit key string as the Agent's `$SECURE_COMMAND_KEY` parameter to decrypt the responses. > 📘 NOTE > > Pipelines should store the Agent's `$SECURE_COMMAND_KEY` parameter value as a [Shared Secret in the TDP](https://developers.tetrascience.com/docs/shared-settings-and-secrets#manage-secrets). The `TetraScience.Connector.http.Request.V2` command has a similar body format as the `TetraScience.Connector.http.Request` command, but uses the following fields to hold the encrypted command body: | Field | Required | Data Type | Definition | | :----------- | :------: | :-----------: | :---------------------------------------------------------------------------------- | | `nonce` | required | base64 string | A one-time-used base64-encoded string. | | `tag` | required | base64 string | A tag from encrypting and digesting the data. | | `ciphertext` | required | base64 string | The command body, consistent with other commands, but base64 encoded and encrypted. | Failure to decrypt a `TetraScience.Connector.http.Request.V2` command by the Agent results in a `FAILURE` command status. This failure mode can occur if the `$SECURE_COMMAND_KEY` differs between the requestor/pipeline and the Agent. ## Command Response Body format The HTTP Relay Agent packages HTTP responses from the target system for transit to the requestor in the command `responseBody` field. For customers using the TetraScience Context API within a TDP Pipeline, this describes the return format from that method when sending commands to the HTTP Relay Agent. For commands with status `SUCCESS` and also `FAILED` commands that were able to complete the HTTP request but received a status code greater than 400, then the command response will be an object with the following definition: | Field | Data Type | Definition | | :----------- | :-------: | :------------------------------------------------------------------------------------------------------------ | | `body` | string | The response data from the target. If the response data is provided as a JSON object, then it is stringified | | `statusCode` | integer | The HTTP response status code from the target | | `headers` | object\[] | An array of key-value pairs. For example: `[{"content-length": "102"}, {"content-type": "application/json"}]` | The `TetraScience.Connector.http.Request.V2` command response body format is the same as the request body format, described above. Requestors are responsible to decrypt the command response body in order to review details. For commands with status `FAILED` that were unable to complete the HTTP request, then the response will have the following format: | Field | Data Type | Definition | | :----- | :-------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `body` | string | Commonly a stringified object containing a `message` field whose value has additional details. For example: `"{"message":"An error occurred while handling the command: Error making request: The request was made by the HTTP Relay but no response was received. Additional info: connect ECONNREFUSED 127.0.0.1:12345"}"` | ## Command Outcomes The commands that the Tetra HTTP Relay Agent handles all go through the following statuses: * `CREATED`: The command was posted to the TDP Command Service. * `PENDING`: The command is awaiting recognition by the agent. Based on how the Agent handles the command, it can then enter any of the following statuses: * `REJECTED`: The command was received by the Agent and rejected. Additional information about why the request was rejected is accessible on the [**Command Details** page](https://developers.tetrascience.com/docs/command-service#view-command-details). * `PROCESSING`: The Agent is processing the command. * `SUCCESS`: The HTTP or HTTPS request was executed and returned a response with status code `200-399`. * `FAILURE`: The HTTP request failed, either because the request was unable to be executed, or the response has status code `400` or higher. Rare HTTP or HTTPS workflows featuring status code `100` can fail. Additional information about why the request failed is accessible in the response body visible from the [**Command Details** page](https://developers.tetrascience.com/docs/command-service#view-command-details). # Test the Agent To verify end-to-end command relay after installation, run one of the following command examples. Both examples target `https://httpbin.org/get`, a public endpoint that requires no authentication. ## Command Line Test Command Example Set the following environment variables, then run the following example `curl` command to send a test command using the [Create Command API](https://developers.tetrascience.com/reference/ag-create-command). | Variable | Description | | :--- | :--- | | `AGENT_ID` | The Agent ID from TDP | | `ORG_SLUG` | Your organization slug | | `API_TARGET` | TDP API hostname, for example `api.tetrascience.com` | | `JWT` | A valid TDP auth token | ```bash # macOS EXPIRES_AT=$(date -u -v "+10M" +"%Y-%m-%dT%H:%M:%S") # Linux # EXPIRES_AT=$(date -u -d "+10 minutes" +"%Y-%m-%dT%H:%M:%S") curl --silent \ --location "https://$API_TARGET/v1/commands" \ --header "ts-auth-token: $JWT" \ --header "x-org-slug: $ORG_SLUG" \ --header "Content-Type: application/json" \ --data "{ \"targetId\": \"$AGENT_ID\", \"action\": \"TetraScience.Connector.gdc.HttpRequest\", \"expiresAt\": \"$EXPIRES_AT\", \"payload\": { \"method\": \"GET\", \"url\": \"https://httpbin.org/get\", \"headers\": [{\"Content-Type\": \"application/json\"}], \"ignore_tls_certificate\": false, \"timeout\": 30000 } }" ``` The response contains an `id` field. Pass that value as `$COMMAND_ID` to check the result: ```bash curl --silent \ --location "https://$API_TARGET/v1/commands/$COMMAND_ID" \ --header "ts-auth-token: $JWT" \ --header "x-org-slug: $ORG_SLUG" | jq '.status' ``` A `SUCCESS` status confirms the Agent received the command and relayed the request. ## Pipeline Test Command Example The following example shows how to use the [`context.run_cmd()` command](https://developers.tetrascience.com/docs/context-api#contextrun_command) in a [python-exec](https://developers.tetrascience.com/docs/python-exec) pipeline script to send a test command. A completed workflow confirms the Agent is operational. The response body from `https://httpbin.org/get` is visible in the workflow logs. ```python import json agent_id = "your-agent-id" logger = context.get_logger() payload = { "method": "GET", "url": "https://httpbin.org/get", "headers": [{"Content-Type": "application/json"}], "ignore_tls_certificate": False, "timeout": 30000 } response = context.run_cmd( target_id=agent_id, action="TetraScience.Connector.gdc.HttpRequest", metadata={}, payload=payload, ttl_sec=120 ) logger.log({"message": "HTTP relay response", "body": response.get("body")}) output = { "status": "success", "response": json.loads(response.get("body", "{}")) } ``` # Troubleshooting The following are known errors that you can encounter when using the Tetra HTTP Relay Agent, along with steps to resolve each issue.

Potential Issue	Resolution
The Agent's container is unhealthy (for example, if it has entered an exit-restart loop)	Inspect the Agent's logs for more details. The initial Agent configuration may be incorrect, potentially because the environmental variables passed to the container aren't valid. Keep in mind the following: - In some cases, configurations that aren't valid are detected prior to initialization. Descriptive error messages are provided. - Inspecting the log messages will provide details about configurations that aren't valid (for example, failing to authenticate to the TDP, because either the `$ORG_SLUG` and `$JWT` aren't valid or the Agent doesn't have the ability to communicate with the TetraScience API because of host machine network restrictions.
Errors related to communicating with the Agent's Amazon Simple Queue Service (SQS) queue	[Enable the Agent's Queue](https://developers.tetrascience.com/docs/centralized-configuration-of-tetra-data-platform-components#enable-the-agents-queue). If the queue is enabled, then review the host's networking configuration to ensure communication with the TDP.
Errors that indicate that the Agent is disabled	[Enable the Agent's Connection](https://developers.tetrascience.com/docs/centralized-configuration-of-tetra-data-platform-components#enable-an-agents-connection).
Commands fail without a `statusCode` in the response	There may be issues with network connectivity to the target system. Common error messages in these responses could include `ECONREFUSED`, `ETIMEDOUT`, and `ENOTFOUND`. Manually logging into the host machine and verifying connectivity to the target machine, target port, and target system with command line tools like `curl`, `wget`, `nc`, or `ping` will reveal more information. Executing `wget` commands from the Docker container using `docker exec -it $COMMAND` can reveal if the deployment's Docker networking configuration is blocking the request.
Commands sent to the Agent fail and return status codes `407`, `502`, or `503`	There may be issues in the connection between the HTTP Relay Agent and the proxy service, if one is in use. Inspecting the `headers` and `body` of the command response may yield more information.
Commands sent to the Agent fail and return a 4xx `statusCode`, such as `401` or `403`	Verify that the command sent to the Agent includes the required authentication information.
Proxy-related errors, such as `ssl wrong version number`	Verify that your proxy environment variables include the protocol prefix: - Correct: `HTTP_PROXY=http://proxy.company.com:8080` - Incorrect: `HTTP_PROXY=proxy.company.com:8080`
SSL certificate validation errors, or if you need to bypass certificate validation for development or self-signed certificates	Set `NODE_TLS_REJECT_UNAUTHORIZED=0` in your Docker run command. For production deployments, properly configure certificates instead.
The Agent stops polling Amazon SQS, but still shows an Online status	Use a task scheduler, such as [Cron](https://docs.gitlab.com/topics/cron/), to restart the Agent's container periodically. A fix for this issue is in development and testing and is scheduled for a future release.

# Documentation Feedback Do you have questions about our documentation or suggestions for how we can improve it? [Start a discussion in TetraConnect Hub](https://tetrascience.zendesk.com/hc/en-us/community/topics/38259263466893-Documentation-Feedback). For access, see [Access the TetraConnect Hub](https://developers.tetrascience.com/docs/access-the-tetrascience-knowledge-base). > 📘 NOTE > > Feedback isn't part of the official TetraScience product documentation. TetraScience doesn't warrant or make any guarantees about the feedback provided, including its accuracy, relevance, or reliability. All feedback is subject to the terms set forth in the [TetraConnect Hub Community Guidelines](https://tetrascience.zendesk.com/hc/en-us/articles/26916126183309-TetraConnect-Hub-Community-Guidelines).