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

# Past-artifact tools

> Read tools that let the agent reference earlier typed artifacts (charts, tables) by id without re-emitting their data.

The `ArtifactTools` collection lets the agent inspect artifacts produced earlier in the same conversation, for example to compare against the chart from an earlier turn or summarise a past table. One instance is created per thread, bound to its `thread_id`, so listing and fetching are scoped to that one conversation without the id being an LLM-facing parameter.

Both tools are **read-only**: they produce no artifact and stream no `artifact` event. They exist so the agent can reason over its own past output by id, rather than re-emitting large payloads into the conversation.

Shared conventions (the `@workspace_tool` contract, the injected `action_and_reasoning` argument, and the JSON envelope) are documented in [Tools](/docs/tools); the typed-artifact channel that produces these artifacts in the first place is in [Agent core logic](/docs/agent-core-logic). The decorator injects the required `action_and_reasoning` argument, so it is omitted from the argument tables below.

Source: [`backend/app/tools/artifacts.py`](https://github.com/petrosrapto/HAICO/blob/main/backend/app/tools/artifacts.py)

## `list_artifacts`

Return a compact, newest-first index of the artifacts produced earlier in this conversation.

**Description shown to the agent:**

> List artifacts produced earlier in this conversation, newest first. Returns a compact index (id, type, title, turn). Useful before referencing or re-fetching a specific artifact.

**Arguments**

| Argument        | Type                               | Required | Description shown to the agent                                                                      |
| --------------- | ---------------------------------- | -------- | --------------------------------------------------------------------------------------------------- |
| `artifact_type` | `string \| null` (default `null`)  | No       | Optional filter, e.g. 'line\_chart' / 'bar\_chart' / 'pie\_chart'. Omit to list all artifact types. |
| `limit`         | `integer` (1 to 100, default `20`) | No       | Maximum number of rows to return. Default 20, max 100.                                              |

**Returns:** newline-separated lines of the form `#<id> [turn <n>] <type> — <title>` (the title clause is dropped when the artifact has no title), newest first, or `(no artifacts produced yet in this conversation)` when none exist. The listing is scoped to this thread.

**Implementation:** calls `repo.list_artifacts(thread_id, artifact_type=..., limit=...)` and formats each row into the compact index line. Source: [`backend/app/tools/artifacts.py`](https://github.com/petrosrapto/HAICO/blob/main/backend/app/tools/artifacts.py).

## `get_artifact`

Fetch the full JSON payload of one past artifact by its id, plus its metadata.

**Description shown to the agent:**

> Fetch the full JSON payload of a past artifact by id. Use this to compare against, summarise, or reason over an earlier chart or table. The payload is returned as JSON; do not re-emit it verbatim to the user, refer to it by id and describe what changed.

**Arguments**

| Argument      | Type               | Required | Description shown to the agent                                                             |
| ------------- | ------------------ | -------- | ------------------------------------------------------------------------------------------ |
| `artifact_id` | `integer` (`>= 1`) | Yes      | Primary key of the artifact to fetch. Use `list_artifacts` first if you don't know the id. |

**Returns:** a JSON string wrapping the payload **with its metadata**, not the bare payload:

```json theme={null}
{
  "id": 42,
  "type": "line_chart",
  "title": "Revenue",
  "turn_index": 3,
  "payload": { }
}
```

When no row matches the id, or the matching row belongs to a different conversation, it returns `artifact #<id> not found in this conversation`.

**Implementation:** calls `repo.get_artifact(artifact_id)` and enforces thread scoping by checking `artifact.thread_id == self.thread_id` before returning, so artifacts from other conversations are never disclosed. The payload is serialised with `json.dumps(..., default=str)`. Source: [`backend/app/tools/artifacts.py`](https://github.com/petrosrapto/HAICO/blob/main/backend/app/tools/artifacts.py).