AI tools
get_artifactLast updated on
Last updated on
Retrieve one artifact and its instructions from an Asterdoc registry
Retrieves one artifact from a registry. The tool reads registry.json, finds the edition and version you asked for, and fetches that file. Without an edition or a version, it uses the current edition and the latest version, as the registry states them. It refuses a file whose SHA-256 differs from the one in registry.json. By default it also returns the artifact's instructions and agentInstructions.
Input
| Field | Type | Required | Description |
|---|---|---|---|
registry_url | string (URL) | No | Registry base URL. Falls back to defaultRegistryUrl in the config. |
artifact_name | string | Yes | Artifact name within the registry |
edition | string | No | Edition key, such as 2024-03. Omit it, or pass current, for the current edition. Only for an artifact that has editions. |
version | string | No | Version, such as 1.2.0. Omit it, or pass latest, for the latest version of the edition. |
include_instructions | boolean | No | Return the artifact's instructions. Default true. |
include_agent_instructions | boolean | No | Return the artifact's agentInstructions. Default true. |
Output
| Field | Type | Description |
|---|---|---|
artifact | object | The artifact JSON (form, document, bundle, or checklist) |
artifact_name | string | The requested name |
edition | string | Key of the edition that was read. Absent for an artifact that has no editions. |
version | string | The version that was read |
releases | object | Every edition and version the registry lists for this artifact, in the same fields as a get_registry item |
base_url | string | The artifact's directory. Pass it as base_url in an artifact source so file-backed layers resolve. |
instructions | InstructionContent | The artifact's instructions, when present and requested |
agent_instructions | InstructionContent | The artifact's agent instructions, when present and requested |
error | ToolError | Set when the artifact could not be fetched, for example artifact_not_found |
InstructionContent has these fields:
| Field | Type | Description |
|---|---|---|
kind | "inline" | "file" | Inline text or a file next to the artifact |
mime_type | string | File MIME type (file only) |
path | string | File path relative to the artifact (file only) |
content | string | The instruction content |
encoding | "utf-8" | "base64" | utf-8 for text, base64 for binary files |
Direct usage
import { executeGetArtifact } from "@asterdoc/ai-tools"
const result = await executeGetArtifact({
registry_url: "https://registry.acme.com",
artifact_name: "pet-addendum",
})Name one edition and version:
const result = await executeGetArtifact({
registry_url: "https://forms.example.com",
artifact_name: "w-9",
edition: "2024-03",
version: "1.0.0",
})Example response
The artifact is shortened here. The real registry response also includes file-backed instructions and agent_instructions entries.
{
"artifact": {
"kind": "form",
"name": "pet-addendum",
"version": "1.0.0",
"title": "Pet Addendum to Lease Agreement",
"fields": { "petName": { "type": "text", "label": "Pet name", "required": true } }
},
"artifact_name": "pet-addendum",
"version": "1.0.0",
"releases": { "latest_version": "1.0.0", "versions": ["1.0.0"] },
"base_url": "https://registry.acme.com/pet-addendum/1.0.0"
}