Requires version 2.0.0 or later of the Archetype platform.
- Batch mode processes a set of input files, writes its output, and finishes.
- Serving mode keeps the agent running so it can answer queries as they arrive, one payload at a time.
How the Modes Differ
Choosing a Mode
Use batch mode when:- Your data already exists as files, such as a day of sensor logs or a recorded video.
- You want a complete output file, such as per-window predictions for a whole CSV.
- Nothing is waiting on the answer, so it’s fine for the run to take a while.
- Data arrives continuously and you need an answer for each piece as it arrives, such as the newest readings from a live sensor.
- An application, dashboard, or another service needs to ask the agent questions and get answers back in the same request.
- You want to load the agent once and send it many small payloads, rather than starting a new run for each one.
Before You Start
Both modes run a package that’sready. To build one, use Create
Package, then poll Get
Package until its status is ready.
The examples on this page read your API key and the platform URL from environment
variables:
- Standard Account
- Free Trial Account
Running an Agent in Batch Mode
1. Start the Run
Call Create Agent with the package’s ID and the files to process. You can leavemode out, since batch is the default. Each entry in
connectors.source is a file you’ve already uploaded with the Files
API.
202 Accepted with the new agent, whose status is running. Save its id
(an agt_ ID) for the next steps.
To process several files in one run, list them all in source. By default the agent writes one
output per input. To fold all output into a single file instead (for formats that can be
concatenated, such as CSV), name it in connectors.sink:
2. Wait for the Run to Finish
Poll Get Agent untilstatus reaches completed,
failed, or cancelled. If the run failed, error says why.
3. Get the Results
Once the run iscompleted, page through its output files with Get Agent
Results. Each entry’s data.ref points at a
stored output file.
Running an Agent in Serving Mode
1. Start the Agent
Call Create Agent withmode set to serving.
Don’t send connectors: a serving agent gets its input from each query, so a request that binds
files is rejected with 400.
202 Accepted with the new agent, whose status is deploying.
If the request returns 429 with code serving_limit_reached, your organization is already
running as many serving agents as it’s allowed to. Cancel one you no longer need, then try again.
Not every blueprint can be served; one that can’t returns 400 and no agent is created.
2. Wait for the Agent to Be Running
A serving agent can’t answer queries until it has been placed on a worker. Poll Get Agent untilstatus is running. If it ends up
failed instead, the agent couldn’t be placed or started, and error says why; create another
agent to try again.
3. Send Queries
Send each payload to Query Agent. The request body is whatever the blueprint’s source connector accepts, and the agent’s answer comes back in theresponse field, shaped by the blueprint’s sink connector. The records body below is only an
example of what a time-series blueprint might accept.
200:
4. Open a Session for Many Queries (Optional)
If you’re sending a steady stream of payloads, Connect to Agent opens one websocket session instead of making a request for each payload. Each JSON text frame you send gets one answer frame back. Every frame from the server has astatus field: connected when the session opens,
completed for an answer, and failed for a frame the server couldn’t act on.
cURL can’t hold a websocket session open, so this example is in Python only. It uses the
websocket-client package (pip install websocket-client).
Python
failed frame in answer to a bad payload doesn’t end the session, so you can keep sending.
If the agent stops serving, the server sends a failed frame and then closes the session.
5. Stop the Agent
A serving agent keeps running, and counts against your organization’s serving limit, until you stop it. When you’re done with it, cancel it with Cancel Agent. Serving agents can’t be paused, so cancel is the only way to stop one yourself.completed, and queries to it return 409 with a
message that starts released after. Released agents don’t come back; start a new serving agent
from the same package to continue.
Using the Python Client
The Python client wraps these steps. It waits for a batch run to finish withwait_until_done, waits for a serving agent to start with
wait_until_running, and retries 429 and 503 responses to query for you:
Python
wait_until_done raises a ValueError for a serving agent, since a serving agent never
finishes on its own.