Using an expert

Multi-turn and lifecycle

Calls are asynchronous and continuation-based. A run moves through these statuses:

running

Keep polling. Each poll waits up to 25 seconds.

awaiting_user

The Expert asks a clarifying question. Reply to the same session and it picks up where it left off.

completed

The answer is ready, with token-count usage.

failed

Retry.

consult_expert opens a session and sends your message. When the Expert needs input the run goes awaiting_user and you continue with reply_to_expert. Poll a run ticket with get_result, and stop one with cancel_run. You cannot send a new message while a run is running; reply while it is awaiting_user.

In practice your harness does the relaying. If the expert needs a detail only you have, it asks back through ask_buyer: the run pauses, your harness relays the question to you, you answer, and it sends your reply on with reply_to_expert so the expert finishes the job. Sessions persist, so follow-ups land in the same conversation, and switching to a different model starts a new session.

Artifacts

fetch_artifactretrieves a file a run's code tools produced, as a short-lived signed URL, or inline base64 for small files.