Use search results and user files in the hosted shell

In GovTribe AI Analyst conversations, use Create_Container to prepare the hosted shell when it is unavailable. Use Add_To_Container when an agent needs GovTribe data or files as local inputs to the hosted shell. The tool can stage an accessible User File, files attached to another supported GovTribe record, a typed-search result page, or a generated image from the active conversation. These inputs can be combined in one request.

Normal Search_* calls do not create files or contact the OpenAI Files or Containers APIs. The agent must call Add_To_Container explicitly when shell staging is useful.

Choose the smallest useful path

Do not stage a typed search merely to continue reasoning from its returned rows. Shell staging adds file materialization, billing, upload, and container-attachment work and is useful only when the shell needs a local JSON file.

Prepare the hosted shell

Create_Container is a native tool at the root of the GovTribe AI Analyst tool catalog. It does not require deferred tool discovery and is not an MCP tool available to external clients. All hosted skills live in the container. When Shell is unavailable, call it before reading skills or memory, using local files, executing code, or creating artifacts. Greetings, thanks, and status-only replies do not need container creation.

{
  "tool": "Create_Container",
  "arguments": {
    "action": "ensure",
    "request_id": null,
    "restore_file_ids": null,
    "restore_all_file_ids": false,
    "restore_manifest_id": null
  }
}

An ensure call creates or reuses the conversation's container and returns a preparation snapshot. With no restore selections, it prepares skills and eligible memory and lists available checkpoint manifests; it does not restore earlier working files. While a request is active, use status with its request_id rather than calling ensure again:

{
  "tool": "Create_Container",
  "arguments": {
    "action": "status",
    "request_id": "<request_id>",
    "restore_file_ids": null,
    "restore_all_file_ids": false,
    "restore_manifest_id": null
  }
}

request_id identifies the preparation request. While pending, stage can describe queued creation, creation in progress, reconciliation, or file preparation. A returned container_id alone is not a readiness signal.

Create_Container prepares the environment; Add_To_Container stages selected inputs. Their success fields differ: creation uses ready and shell_available, while attachment uses completed and hosted_tool_ready. Continue to use the attachment checks below for each requested input.

Resume after container replacement

An expired or missing container does not trigger automatic replacement or checkpoint restoration. If the task needs Shell, call Create_Container with action: "ensure". Once ready, inspect the returned manifests. Each completed checkpoint has a manifest_id, capture time, and version-specific file_id values with original paths. Check which files the current task needs. If no usable checkpoint contains a required file, recreate it from a durable source when possible or explain the gap.

To restore selected files, call ensure with their restore_file_ids. To restore every file from one checkpoint, set restore_all_file_ids: true and supply its restore_manifest_id. Do not combine restore-all with selected IDs or select multiple versions of the same destination path. Restoration overwrites existing files at their original paths, so move conflicting files aside in Shell before requesting it.

{
  "tool": "Create_Container",
  "arguments": {
    "action": "ensure",
    "request_id": null,
    "restore_file_ids": ["<file_id_from_manifest>"],
    "restore_all_file_ids": false,
    "restore_manifest_id": null
  }
}

Poll an active restore with action: "status" and its request_id. When status is setup_required, run the exact returned setup_command alone in Shell, then call status again. A staged file with files[].status: uploaded is not restored yet; only files[].status: restored confirms verified bytes at the original path. Use requested_file_count, completed_file_count, pending_file_count, and failed_file_count to assess the whole selection. A partial or failed restore leaves the initialized container usable. If a failed file is still needed, select its file_id in a later ensure request. Do not repeat completed external actions merely because the container changed.

Handle files that were not restored

A replacement container can reject an individual checkpoint file. Read each entry in files for its status, path, and failure reason. Other files can still be restored and verified.

{
  "status": "partial",
  "files": [
    {
      "file_id": "<file_id_from_manifest>",
      "path": "/mnt/data/project/source/helper.js",
      "status": "failed",
      "reason": "upload_failed"
    }
  ]
}

Each path is the file's original location under /mnt/data. The returned message summarizes the counts and next action.

Do not assume a listed file exists or claim it was restored. If the task needs one, recreate or replace it where possible, for example from the hosted skill that supplied it or from its authoring source. Otherwise explain what is missing. Later checkpoints capture the files that exist at that time; a missing file does not reappear unless it is recreated.

Keep recovery-critical files out of disposable directories

Checkpoints skip directories named scratch, preview, or previews at any depth under /mnt/data, along with cache directories such as __pycache__. Files in those directories are not restored after container replacement. Similar names, such as preview.pdf or a scratchpad directory, are still captured.

Store deliverables, authoring sources, task contracts, and QA receipts outside those directories. Use them only for output that can be regenerated, such as rendered page previews. After recovery, regenerate any previews the task still needs and refresh the validation that depends on them.

A restored checkpoint can predate the latest turn. Inspect the files needed for the task and reconcile any unfinished work. Do not repeat completed external tool actions merely because the container was replaced. For inputs that need staging again, repeat the original Add_To_Container request and use the current returned paths.

Stage an existing workspace User File

Existing User Files do not need to be uploaded to the current conversation. Search for a file the current user can access, then pass the returned govtribe_id to Add_To_Container.

{
  "tool": "Search_User_Files",
  "arguments": {
    "query": "pricing workbook",
    "fields_to_return": [
      "govtribe_id",
      "name",
      "description",
      "updated_at"
    ]
  }
}

{
  "tool": "Add_To_Container",
  "arguments": {
    "items": [
      {
        "govtribe_type": "user_file",
        "govtribe_id": "<user_file_govtribe_id>"
      }
    ]
  }
}

GovTribe applies the User File's current access policy. A file from another workspace, a deleted file, or a file the caller cannot view is rejected before container work begins.

Stage a generated image

In GovTribe AI, the agent calls the native image_generation tool to create or edit an image. Use Create and edit images for prompting, conversational edits, visual review, and deliverable examples. GovTribe displays the rendering progress in chat and automatically saves a completed image as a User File. Generation alone does not attach the image to the hosted shell.

For example, after creating an image of a cat, pass the returned image-generation call ID to Add_To_Container only if the shell needs to inspect or embed that image:

{
  "tool": "Add_To_Container",
  "arguments": {
    "image_generation_call_ids": ["<image_generation_call_id>"]
  }
}

Provide up to ten distinct image-generation call IDs from the active conversation. If the saved User File ID is already known, the existing items input with govtribe_type: "user_file" works too. Supplying both references to the same saved image attaches it once. Combine images with items or search_results_id when a deliverable needs several inputs.

If an image is still being created or saved, the tool returns in_progress. Poll with the same arguments; do not generate another image to retry staging. Failed or stopped generations and exhausted save recovery produce failure guidance. An image-only request that is still waiting for its saved file does not create a container.

Once status is completed and hosted_tool_ready is true, read the current container_files.path_hint. Each generated-image entry also includes the User File ID, image-generation call ID, MIME type, dimensions, and SHA-256 checksum. Use the shell to inspect or embed the image; attaching it does not itself inspect or edit it.

After container replacement, call Add_To_Container again with the same image call ID or User File ID and wait for readiness. GovTribe reuses the saved image and resolves its path in the current container. Never rely on an earlier container path. Edits produce a new saved image; the original remains available unless deleted.

Stage typed-search JSON

Run the typed search first. Keep its normal search_results_id; there is no second replay ID.

{
  "tool": "Search_Federal_Contract_Awards",
  "arguments": {
    "query": "zero trust",
    "page": 2,
    "per_page": 25,
    "fields_to_return": [
      "govtribe_id",
      "contract_number",
      "awardee",
      "dollars_obligated"
    ],
    "aggregations": [
      "top_awardees_by_dollars_obligated"
    ]
  }
}

{
  "tool": "Add_To_Container",
  "arguments": {
    "search_results_id": "<search_results_id>"
  }
}

The staged JSON preserves the original search_results_id, requested page, selected fields, filters and operators, sort, and aggregations. GovTribe reruns the search against current data, so records and aggregation values can differ from the earlier response. The staged row count never exceeds the number returned by the original search page.

An aggregation-only search produces JSON with its aggregations and no synthetic row array. An empty result page can still be staged when its descriptor remains valid.

Stage a mixed shell input set

Provide both inputs when one analysis needs search rows and files.

{
  "tool": "Add_To_Container",
  "arguments": {
    "search_results_id": "<search_results_id>",
    "items": [
      {
        "govtribe_type": "user_file",
        "govtribe_id": "<pricing_workbook_user_file_id>"
      },
      {
        "govtribe_type": "government_file",
        "govtribe_id": "<solicitation_attachment_id>"
      }
    ]
  }
}

Ordinary files and search materialization run independently. A search replay failure does not undo a successful ordinary file attachment. Read the combined polling response to identify completed, pending, failed, and skipped files. A failed image does not undo another successful file attachment.

Poll before using the shell

Add_To_Container returns a status snapshot. When status is in_progress and retry_with_same_arguments is true, call the tool again later with the same items, search_results_id, and image_generation_call_ids inputs.

Use the hosted shell only after:

• status is completed
• hosted_tool_ready is true
• container_files includes each required input
• the shell command uses the returned path_hint instead of guessing a filename

Repeated polling reuses the same hidden materialization file and container attachment. It does not create another search JSON file.

Handle interrupted container setup

If Add_To_Container reports error.code: container_unavailable, call Create_Container with action: "ensure" and follow its status until ready. Then repeat the staging request. This does not automatically restore checkpoint files; select those separately if the task needs them.

Add_To_Container can also return an MCP error while GovTribe reconciles an interrupted container creation. Its structured content still contains the status snapshot. For error.code: container_recovery_pending, expect status: in_progress, hosted_tool_ready: false, and error.retryable: true. Wait for error.retry_after_seconds, then repeat the request with identical arguments. Repeated calls rejoin the same interrupted creation operation; they do not restore historical files.

The interrupted-creation reconciliation reported by these attachment errors has a five-minute maximum and may end sooner. Do not hold a client request open for that duration, run shell commands before readiness, or treat the pending error as successful attachment. Follow each returned status snapshot.

When the error is container_recovery_failed or container_creation_rejected, status is failed and error.retryable is false. Stop polling and report the returned message and failure guidance. Repeating a terminal request does not restart it. A new conversation requires the user's decision; do not create one automatically to bypass the failure. See Add to container MCP response for the error fields.

Billing, authorization, and failures

The original typed search is billed and metered normally. Staging its JSON explicitly reruns and meters that typed search once, based on the durable replay output. A retry after JSON creation reuses the same bytes and usage counts, preventing duplicate replay charges.

Before staging, GovTribe checks the current user, workspace, active Analyst response, OAuth tool scopes, typed-search registration, and the live authorization rules of the underlying search. User- and workspace-scoped searches keep their current live restrictions. Public searches can be replayed by an authorized caller who holds a valid ID.

Billing is checked once, when the Analyst turn starts. Inside that turn, analysis-environment readiness depends on successful creation and file preparation, not on billing settlement. Settlement problems are recorded and reviewed internally and do not fail staging or attachment.

Common failures include:

Verify coverage and final deliverables

A staged search result represents one requested page. For an exhaustive export, preserve the exact filters, traverse every page, union results by canonical record ID, retain source-search membership, and reconcile prior-batch exclusions. Keep ranked shortlists separate from the complete universe. Report failed pages and unknown dates explicitly.

Use the relevant hosted format skill to declare a task contract before building an artifact. The contract identifies source coverage, required columns or ranges, expected results, permitted revisions, and delivery state. Distinguish outline, working-draft, review-draft, and submission-candidate; marked missing inputs are valid draft gaps, while mandatory unresolved inputs prevent submission readiness.

Prepare layout and recalculate workbooks before final rendering and validation. Keep QA receipts bound to the exact artifact and rendered output hashes. Any later binary change requires fresh validation. Structural checks, behavioral checks, rendered review, and unresolved work are separate evidence; a successful file save or structural pass does not establish task completion.

Related articles

• Add to container MCP tool: Review the exact input contract and examples.
• Add to container MCP response: Interpret polling, readiness, paths, and failures.
• Search user files MCP tool: Resolve accessible workspace files.
• Vector-store content retrieval: Choose semantic file retrieval instead of shell staging when appropriate.
• Manage search context: Keep search arguments and identifiers consistent across multi-step analysis.